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')

Parse a string representation of a date into a date object.

Parameters:

• date_str (str | None) – The string to parse as a date.

• fmt (str) – 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:

date | None

Warns:

USPTODateParseWarning – If the date string cannot be parsed.

pyUSPTO.models.utils.parse_to_datetime_utc(datetime_str)

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 (str | None) – 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:

datetime | None

Warns:

• USPTODateParseWarning – If the datetime string cannot be parsed.

• USPTOTimezoneWarning – If timezone localization fails.

pyUSPTO.models.utils.parse_yn_to_bool(value)

Convert a ‘Y’/’N’ (case-insensitive) string to a boolean.

Parameters:

value (str | None) – 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:

bool | None

Warns:

USPTOBooleanParseWarning – If the value is not ‘Y’ or ‘N’.

pyUSPTO.models.utils.serialize_bool_to_yn(value)

Convert a boolean value to its ‘Y’/’N’ string representation.

Parameters:

value (bool | None) – The boolean value to convert.

Returns:

“Y” if value is True, “N” if value is False.

Returns None if value is None.

Return type:

str | None

pyUSPTO.models.utils.serialize_date(d)

Serialize a date object into an ISO 8601 string (YYYY-MM-DD).

Parameters:

d (date | None) – The date object to serialize.

Returns:

The date as an ISO 8601 formatted string, or None

if the input is None.

Return type:

str | None

pyUSPTO.models.utils.serialize_datetime_as_iso(dt)

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 (datetime | None) – 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:

str | None

pyUSPTO.models.utils.serialize_datetime_as_naive(dt)

Serialize a datetime object to ISO format as a naive datetime.

Converts aware datetimes to the assumed timezone and strips timezone information before serializing to ISO format.

Parameters:

dt (datetime) – The datetime object to serialize.

Returns:

ISO formatted datetime string without timezone information.

Return type:

str

pyUSPTO.models.utils.to_camel_case(snake_str)

Convert a snake_case string to lowerCamelCase.

For example, “example_snake_string” becomes “exampleSnakeString”.

Parameters:

snake_str (str) – The input string in snake_case.

Returns:

The converted string in lowerCamelCase.

Return type:

str