pyUSPTO.warnings — pyUSPTO 0.2.3.dev1+g2c5d89b38.d20251125 documentation

# Source code for pyUSPTO.warnings

    """
    warnings - Warning classes for pyUSPTO data parsing issues

    This module defines custom warning categories for different types of
    data parsing issues encountered when working with USPTO API responses.
    These warnings follow Python's standard warning framework and can be
    controlled using warnings.filterwarnings().

    Example:
        # Suppress all pyUSPTO data warnings
        import warnings
        from pyUSPTO.warnings import USPTODataWarning
        warnings.filterwarnings('ignore', category=USPTODataWarning)

        # Turn specific warnings into errors (strict mode)
        warnings.filterwarnings('error', category=USPTODateParseWarning)
    """

    class USPTODataWarning(UserWarning):
        """Base warning class for USPTO data parsing issues.

        All pyUSPTO data-related warnings inherit from this class,
        allowing users to filter all data warnings at once.
        """

        pass

    class USPTODateParseWarning(USPTODataWarning):
        """Warning for date/datetime string parsing failures.

        Raised when a date or datetime string from the API cannot be
        parsed into a Python date/datetime object. The field will be
        set to None.
        """

        pass

    class USPTOBooleanParseWarning(USPTODataWarning):
        """Warning for Y/N boolean string parsing failures.

        Raised when a string that should be 'Y' or 'N' has an unexpected
        value. The field will be set to None.
        """

        pass

    class USPTOTimezoneWarning(USPTODataWarning):
        """Warning for timezone-related issues.

        Raised when timezone data is not available or timezone conversion
        fails. Falls back to UTC timezone.
        """

        pass

    class USPTOEnumParseWarning(USPTODataWarning):
        """Warning for enum value parsing failures.

        Raised when an API response contains a value that doesn't match
        any defined enum member. The field will be set to None.
        """

        pass

    class USPTODataMismatchWarning(USPTODataWarning):
        """Warning for data validation mismatches.

        Raised when the API returns data that doesn't match the requested
        identifier (e.g., requesting application 12345678 but receiving 87654321).
        This indicates a potential API inconsistency or data integrity issue.
        """

        pass