Utils
models.utils - Utility functions for USPTO data models.
This module provides utility functions for parsing, serializing, and converting data used across USPTO API data models. These utilities handle date/datetime conversions, boolean string representations, and string transformations.
- pyUSPTO.models.utils.parse_to_date(date_str, fmt='%Y-%m-%d')[source]
Parse a string representation of a date into a date object.
- Parameters:
date_str (
Optional[str]) – The string to parse as a date.fmt (
str, optional) – The expected strptime format string for parsing the date. Defaults to “%Y-%m-%d”.
- Returns:
- A date object if parsing is successful and date_str
is not None. Returns None if date_str is None or if parsing fails.
- Return type:
Optional[date]
- Warns:
USPTODateParseWarning – If the date string cannot be parsed.
- pyUSPTO.models.utils.parse_to_datetime_utc(datetime_str)[source]
Parse a string representation of a datetime into a UTC datetime object.
Attempts to parse ISO format strings. If the input string contains timezone information, it’s used. If the string is a naive datetime (no timezone), it’s assumed to be in the ASSUMED_NAIVE_TIMEZONE_STR (e.g., “America/New_York”) and then converted to UTC.
- Parameters:
datetime_str (
Optional[str]) – The string to parse as a datetime. Supports ISO 8601 format, including those ending with “Z”.- Returns:
- A timezone-aware datetime object in UTC if parsing
is successful and datetime_str is not None. Returns None if datetime_str is None or if parsing/conversion fails.
- Return type:
Optional[datetime]
- Warns:
USPTODateParseWarning – If the datetime string cannot be parsed.
USPTOTimezoneWarning – If timezone localization fails.
- pyUSPTO.models.utils.parse_yn_to_bool(value)[source]
Convert a ‘Y’/’N’ (case-insensitive) string to a boolean.
- Parameters:
value (
Optional[str]) – The string value to convert. Expected to be ‘Y’, ‘y’, ‘N’, or ‘n’.- Returns:
- True if value is ‘Y’ or ‘y’, False if value is
’N’ or ‘n’. Returns None if value is None or any other string.
- Return type:
Optional[bool]
- Warns:
USPTOBooleanParseWarning – If the value is not ‘Y’ or ‘N’.
- pyUSPTO.models.utils.serialize_bool_to_yn(value)[source]
Convert a boolean value to its ‘Y’/’N’ string representation.
- Parameters:
value (
Optional[bool]) – The boolean value to convert.- Returns:
- “Y” if value is True, “N” if value is False.
Returns None if value is None.
- Return type:
Optional[str]
- pyUSPTO.models.utils.serialize_date(d)[source]
Serialize a date object into an ISO 8601 string (YYYY-MM-DD).
- Parameters:
d (
Optional[date]) – The date object to serialize.- Returns:
- The date as an ISO 8601 formatted string, or None
if the input is None.
- Return type:
Optional[str]
- pyUSPTO.models.utils.serialize_datetime_as_iso(dt)[source]
Serialize a datetime object to a local-timezone ISO 8601 string.
If the input datetime object is timezone-aware, it is converted to the assumed local timezone defined by ASSUMED_NAIVE_TIMEZONE. If it is naive (lacks timezone information), it is first assigned that assumed local timezone.
The resulting datetime is formatted as YYYY-MM-DDTHH:MM:SS.000±HHMM (e.g., “2024-12-10T00:00:00.000-0500”).
- Parameters:
dt (
Optional[datetime]) – The datetime object to serialize. Can be naive or timezone-aware.- Returns:
- The datetime formatted in the assumed local timezone,
or None if the input dt is None.
- Return type:
Optional[str]