Models

models.bulk_data - Data models for USPTO bulk data API

This module provides data models for the USPTO Open Data Portal (ODP) Bulk Data API.

class pyUSPTO.models.bulk_data.BulkDataProduct(product_identifier, product_description_text, product_title_text, product_frequency_text, product_label_array_text, product_dataset_array_text, product_dataset_category_array_text, product_from_date, product_to_date, product_total_file_size, product_file_total_quantity, last_modified_date_time, mime_type_identifier_array_text, product_file_bag=None, days_of_week_text=None)

Bases: object

Represents a product in the bulk data API.

days_of_week_text: str | None = None

classmethod from_dict(data)

Create a BulkDataProduct object from a dictionary.

Return type:

BulkDataProduct

last_modified_date_time: str

mime_type_identifier_array_text: List[str]

product_dataset_array_text: List[str]

product_dataset_category_array_text: List[str]

product_description_text: str

product_file_bag: ProductFileBag | None = None

product_file_total_quantity: int

product_frequency_text: str

product_from_date: str

product_identifier: str

product_label_array_text: List[str]

product_title_text: str

product_to_date: str

product_total_file_size: int

class pyUSPTO.models.bulk_data.BulkDataResponse(count, bulk_data_product_bag, raw_data=None)

Bases: object

Top-level response from the bulk data API.

count

The number of bulk data products in the response.

bulk_data_product_bag

List of bulk data products.

raw_data

Optional raw JSON data from the API response (for debugging).

bulk_data_product_bag: List[BulkDataProduct]

count: int

classmethod from_dict(data, include_raw_data=False)

Create a BulkDataResponse object from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing API response data.

• include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of BulkDataResponse.

Return type:

BulkDataResponse

raw_data: str | None = None

to_dict()

Convert the BulkDataResponse object to a dictionary.

Return type:

Dict[str, Any]

class pyUSPTO.models.bulk_data.FileData(file_name, file_size, file_data_from_date, file_data_to_date, file_type_text, file_release_date, file_download_uri=None, file_date=None, file_last_modified_date_time=None)

Bases: object

Represents a file in the bulk data API.

file_data_from_date: str

file_data_to_date: str

file_date: str | None = None

file_download_uri: str | None = None

file_last_modified_date_time: str | None = None

file_name: str

file_release_date: str

file_size: int

file_type_text: str

classmethod from_dict(data)

Create a FileData object from a dictionary.

Return type:

FileData

class pyUSPTO.models.bulk_data.ProductFileBag(count, file_data_bag)

Bases: object

Container for file data elements.

count: int

file_data_bag: List[FileData]

classmethod from_dict(data)

Create a ProductFileBag object from a dictionary.

Return type:

ProductFileBag

models.patent_data - Data models for USPTO patent data API

This module provides Pydantic-style data models, primarily using frozen dataclasses, for representing responses from the USPTO Patent Data API. It aims to offer more Pythonic representations (e.g., Enums, native date/datetime objects) of the API’s JSON data. Models cover aspects like application metadata, party information (applicants, inventors, attorneys), document details, continuity, assignments, and more.

class pyUSPTO.models.patent_data.ActiveIndicator(*values)

Bases: Enum

Represents an active or inactive status, often used for practitioners or entities.

This Enum is designed to flexibly parse common string representations of active/inactive or true/false states (e.g., “Y”, “N”, “true”, “false”, “Active”) into standardized Enum members.

ACTIVE = 'Active'

FALSE = 'false'

NO = 'N'

TRUE = 'true'

YES = 'Y'

class pyUSPTO.models.patent_data.Address(name_line_one_text=None, name_line_two_text=None, address_line_one_text=None, address_line_two_text=None, address_line_three_text=None, address_line_four_text=None, geographic_region_name=None, geographic_region_code=None, postal_code=None, city_name=None, country_code=None, country_name=None, postal_address_category=None, correspondent_name_text=None, country_or_state_code=None, ict_state_code=None, ict_country_code=None)

Bases: object

Represents a postal address with fields for street, city, region, country, and postal code.

It can be used for various entities like applicants, inventors, or correspondence.

name_line_one_text

First line of the name (e.g., company name).

name_line_two_text

Second line of the name.

address_line_one_text

First line of the street address.

address_line_two_text

Second line of the street address.

address_line_three_text

Third line of the street address.

address_line_four_text

Fourth line of the street address.

geographic_region_name

Name of the geographic region (e.g., state, province).

geographic_region_code

Code for the geographic region.

postal_code

Postal or ZIP code.

city_name

Name of the city.

country_code

Two-letter country code (e.g., “US”).

country_name

Full name of the country (e.g., “United States”).

postal_address_category

Category of the address (e.g., “MAILING_ADDRESS”).

correspondent_name_text

Name of the correspondent at this address.

country_or_state_code

Country or state code.

ict_state_code

International code for the state/region (USPTO format).

ict_country_code

International code for the country (USPTO format).

address_line_four_text: str | None = None

address_line_one_text: str | None = None

address_line_three_text: str | None = None

address_line_two_text: str | None = None

city_name: str | None = None

correspondent_name_text: str | None = None

country_code: str | None = None

country_name: str | None = None

country_or_state_code: str | None = None

classmethod from_dict(data)

Creates an Address instance from a dictionary representation.

Maps camelCase keys from API data to class attributes.

Parameters:

data (Dict[str, Any]) – Dictionary containing address data.

Returns:

An instance of Address.

Return type:

Address

geographic_region_code: str | None = None

geographic_region_name: str | None = None

ict_country_code: str | None = None

ict_state_code: str | None = None

name_line_one_text: str | None = None

name_line_two_text: str | None = None

postal_address_category: str | None = None

postal_code: str | None = None

to_dict()

Converts the Address instance to a dictionary with camelCase keys.

Returns:

A dictionary representation of the address.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Applicant(first_name=None, middle_name=None, last_name=None, name_prefix=None, name_suffix=None, preferred_name=None, country_code=None, applicant_name_text=None, correspondence_address_bag=<factory>)

Bases: Person

Represents an applicant for a patent, inheriting from Person.

Includes applicant-specific name text and a list of correspondence addresses.

applicant_name_text

The full name of the applicant as a single string.

correspondence_address_bag

A list of Address objects for the applicant.

applicant_name_text: str | None = None

correspondence_address_bag: List[Address]

classmethod from_dict(data)

Creates an Applicant instance from a dictionary.

Inherits person fields and adds applicant-specific fields.

Parameters:

data (Dict[str, Any]) – Dictionary with applicant data.

Returns:

An instance of Applicant.

Return type:

Applicant

to_dict()

Converts the Applicant instance to a dictionary.

Includes inherited person fields and applicant-specific fields, using camelCase keys and omitting None values or empty lists.

Returns:

Dictionary representation of the applicant.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.ApplicationContinuityData(parent_continuity_bag=<factory>, child_continuity_bag=<factory>)

Bases: object

Holds parent and child continuity application data for a specific patent application.

This class consolidates lists of ParentContinuity and ChildContinuity objects, representing the lineage of an application.

parent_continuity_bag

List of ParentContinuity objects.

child_continuity_bag

List of ChildContinuity objects.

child_continuity_bag: List[ChildContinuity]

classmethod from_wrapper(wrapper)

Creates an ApplicationContinuityData instance from a PatentFileWrapper.

Extracts parent and child continuity bags from the wrapper.

Parameters:

wrapper (PatentFileWrapper) – The patent file wrapper containing continuity data.

Returns:

An instance of ApplicationContinuityData.

Return type:

ApplicationContinuityData

parent_continuity_bag: List[ParentContinuity]

to_dict()

Converts the ApplicationContinuityData instance to a dictionary.

Returns:

Dictionary representation with “parentContinuityBag”

and “childContinuityBag” keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.ApplicationMetaData(national_stage_indicator=None, entity_status_data=None, publication_date_bag=<factory>, publication_sequence_number_bag=<factory>, publication_category_bag=<factory>, docket_number=None, first_inventor_to_file_indicator=None, first_applicant_name=None, first_inventor_name=None, application_confirmation_number=None, application_status_date=None, application_status_description_text=None, filing_date=None, effective_filing_date=None, grant_date=None, group_art_unit_number=None, application_type_code=None, application_type_label_name=None, application_type_category=None, invention_title=None, patent_number=None, application_status_code=None, earliest_publication_number=None, earliest_publication_date=None, pct_publication_number=None, pct_publication_date=None, international_registration_publication_date=None, international_registration_number=None, examiner_name_text=None, class_field=None, subclass=None, uspc_symbol_text=None, customer_number=None, cpc_classification_bag=<factory>, applicant_bag=<factory>, inventor_bag=<factory>, raw_data=None)

Bases: object

Represents the metadata associated with a patent application.

This class holds a wide range of information including application status, dates (filing, grant, publication), applicant and inventor details, classification data, and other identifying information.

national_stage_indicator

Indicates if the application is a national stage entry.

entity_status_data

EntityStatus object detailing applicant’s entity status.

publication_date_bag

List of publication dates.

publication_sequence_number_bag

List of publication sequence numbers.

publication_category_bag

List of publication categories.

docket_number

Applicant’s or attorney’s docket number.

first_inventor_to_file_indicator

Boolean indicating if under First-Inventor-to-File.

first_applicant_name

Name of the first listed applicant.

first_inventor_name

Name of the first listed inventor.

application_confirmation_number

USPTO confirmation number for the application.

application_status_date

Date the current application status was set.

application_status_description_text

Textual description of the current application status.

filing_date

Official filing date of the application.

effective_filing_date

Effective filing date, considering priority claims.

grant_date

Date the patent was granted, if applicable.

group_art_unit_number

USPTO Group Art Unit number.

application_type_code

Code for the application type.

application_type_label_name

Label for the application type (e.g., “Utility”).

application_type_category

Category of the application type.

invention_title

Title of the invention.

patent_number

USPTO patent number, if granted.

application_status_code

Numeric code for the application status.

earliest_publication_number

Number of the earliest pre-grant publication.

earliest_publication_date

Date of the earliest pre-grant publication.

pct_publication_number

PCT publication number, if applicable.

pct_publication_date

PCT publication date, if applicable.

international_registration_publication_date

Date of international registration publication.

international_registration_number

International registration number.

examiner_name_text

Name of the patent examiner.

class_field

USPC main classification. (Named class_field to avoid keyword clash).

subclass

USPC subclass.

uspc_symbol_text

Full USPC classification symbol.

customer_number

USPTO customer number associated with the application.

cpc_classification_bag

List of CPC classification symbols.

applicant_bag

List of Applicant objects.

inventor_bag

List of Inventor objects.

raw_data

Raw JSON string of the data used to create this instance (for debugging).

applicant_bag: List[Applicant]

application_confirmation_number: int | None = None

application_status_code: int | None = None

application_status_date: date | None = None

application_status_description_text: str | None = None

application_type_category: str | None = None

application_type_code: str | None = None

application_type_label_name: str | None = None

class_field: str | None = None

cpc_classification_bag: List[str]

customer_number: int | None = None

docket_number: str | None = None

earliest_publication_date: date | None = None

earliest_publication_number: str | None = None

effective_filing_date: date | None = None

entity_status_data: EntityStatus | None = None

examiner_name_text: str | None = None

filing_date: date | None = None

first_applicant_name: str | None = None

first_inventor_name: str | None = None

first_inventor_to_file_indicator: bool | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an ApplicationMetaData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary with application metadata.

• include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of ApplicationMetaData.

Return type:

ApplicationMetaData

grant_date: date | None = None

group_art_unit_number: str | None = None

international_registration_number: str | None = None

international_registration_publication_date: date | None = None

invention_title: str | None = None

inventor_bag: List[Inventor]

property is_aia: bool | None

Returns True if the application is AIA, False if pre-AIA, None if unknown.

property is_pre_aia: bool | None

Returns True if the application is pre-AIA, False if AIA, None if unknown.

national_stage_indicator: bool | None = None

patent_number: str | None = None

pct_publication_date: date | None = None

pct_publication_number: str | None = None

publication_category_bag: List[str]

publication_date_bag: List[date]

publication_sequence_number_bag: List[str]

raw_data: str | None = None

subclass: str | None = None

to_dict()

Converts the ApplicationMetaData instance to a dictionary.

Serializes attributes to camelCase keys suitable for API interaction or storage. Omits keys with None values or empty lists. Handles date and boolean serialization.

Returns:

Dictionary representation of the application metadata.

Return type:

Dict[str, Any]

uspc_symbol_text: str | None = None

class pyUSPTO.models.patent_data.Assignee(assignee_name_text=None, assignee_address=None)

Bases: object

Represents an assignee in a patent assignment.

assignee_name_text

The name of the party receiving the assignment.

assignee_address

The Address of the assignee.

assignee_address: Address | None = None

assignee_name_text: str | None = None

classmethod from_dict(data)

Creates an Assignee instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with assignee data.

Returns:

An instance of Assignee.

Return type:

Assignee

to_dict()

Converts the Assignee instance to a dictionary.

Omits keys with None values.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Assignment(reel_number=None, frame_number=None, reel_and_frame_number=None, page_total_quantity=None, assignment_document_location_uri=None, assignment_received_date=None, assignment_recorded_date=None, assignment_mailed_date=None, conveyance_text=None, image_available_status_code=None, attorney_docket_number=None, assignor_bag=<factory>, assignee_bag=<factory>, correspondence_address=None, domestic_representative=None)

Bases: object

Represents a patent assignment, detailing the transfer of rights.

Includes information about the reel and frame, document location, dates, conveyance text, and bags of assignors, assignees, correspondence address, and domestic representative.

reel_number

Reel number for the assignment record.

frame_number

Frame number for the assignment record.

reel_and_frame_number

Combined reel and frame number.

page_total_quantity

Total number of pages in the assignment document.

assignment_document_location_uri

URI for the assignment document.

assignment_received_date

Date the assignment was received by USPTO.

assignment_recorded_date

Date the assignment was recorded by USPTO.

assignment_mailed_date

Date the assignment notification was mailed.

conveyance_text

Text describing the nature of the conveyance.

image_available_status_code

Code to indicate the availability of the image.

attorney_docket_number

Attorney docket number for the assignment.

assignor_bag

List of Assignor objects.

assignee_bag

List of Assignee objects.

correspondence_address

Address object for correspondence (single object).

domestic_representative

Address object for the domestic representative.

assignee_bag: List[Assignee]

assignment_document_location_uri: str | None = None

assignment_mailed_date: date | None = None

assignment_received_date: date | None = None

assignment_recorded_date: date | None = None

assignor_bag: List[Assignor]

attorney_docket_number: str | None = None

conveyance_text: str | None = None

correspondence_address: Address | None = None

domestic_representative: Address | None = None

frame_number: int | None = None

classmethod from_dict(data)

Creates an Assignment instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with assignment data.

Returns:

An instance of Assignment.

Return type:

Assignment

image_available_status_code: bool | None = None

page_total_quantity: int | None = None

reel_and_frame_number: str | None = None

reel_number: int | None = None

to_dict()

Converts the Assignment instance to a dictionary.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Assignor(assignor_name=None, execution_date=None)

Bases: object

Represents an assignor in a patent assignment.

assignor_name

The name of the assigning party.

execution_date

The date the assignment was executed.

assignor_name: str | None = None

execution_date: date | None = None

classmethod from_dict(data)

Creates an Assignor instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with assignor data.

Returns:

An instance of Assignor.

Return type:

Assignor

to_dict()

Converts the Assignor instance to a dictionary.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Attorney(first_name=None, middle_name=None, last_name=None, name_prefix=None, name_suffix=None, preferred_name=None, country_code=None, registration_number=None, active_indicator=None, registered_practitioner_category=None, attorney_address_bag=<factory>, telecommunication_address_bag=<factory>)

Bases: Person

Represents an attorney or agent associated with a patent application, inheriting from Person.

Includes registration number, active status, practitioner category, addresses, and telecommunication details.

registration_number

The attorney’s USPTO registration number.

active_indicator

Indicates if the attorney is currently active (e.g., “Y”, “N”).

registered_practitioner_category

Category of the practitioner (e.g., “ATTORNEY”, “AGENT”).

attorney_address_bag

List of Address objects for the attorney.

telecommunication_address_bag

List of Telecommunication objects for the attorney.

active_indicator: str | None = None

attorney_address_bag: List[Address]

classmethod from_dict(data)

Creates an Attorney instance from a dictionary.

Inherits person fields and adds attorney-specific details.

Parameters:

data (Dict[str, Any]) – Dictionary with attorney data.

Returns:

An instance of Attorney.

Return type:

Attorney

registered_practitioner_category: str | None = None

registration_number: str | None = None

telecommunication_address_bag: List[Telecommunication]

to_dict()

Converts the Attorney instance to a dictionary.

Includes inherited person fields and attorney-specific fields, using camelCase keys and omitting None values or empty lists.

Returns:

Dictionary representation of the attorney.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.ChildContinuity(first_inventor_to_file_indicator=None, application_number_text=None, filing_date=None, status_code=None, status_description_text=None, patent_number=None, claim_parentage_type_code=None, claim_parentage_type_code_description_text=None, child_application_status_code=None, parent_application_number_text=None, child_application_number_text=None, child_application_status_description_text=None, child_application_filing_date=None, child_patent_number=None)

Bases: Continuity

Represents a child application in a patent application’s continuity chain.

Inherits from Continuity and adds specific fields for child application details.

child_application_status_code

Status code of the child application.

parent_application_number_text

Application number of the parent (current) application.

child_application_number_text

Application number of the child application.

child_application_status_description_text

Status description of the child application.

child_application_filing_date

Filing date of the child application.

child_patent_number

Patent number of the child application, if granted.

child_application_filing_date: date | None = None

child_application_number_text: str | None = None

child_application_status_code: int | None = None

child_application_status_description_text: str | None = None

child_patent_number: str | None = None

classmethod from_dict(data)

Creates a ChildContinuity instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with child continuity data.

Returns:

An instance of ChildContinuity.

Return type:

ChildContinuity

parent_application_number_text: str | None = None

to_dict()

Converts the ChildContinuity instance to a dictionary.

Maps attributes to specific camelCase keys expected by the API for child continuity. Filters out None values to match the API response structure.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Continuity(first_inventor_to_file_indicator=None, application_number_text=None, filing_date=None, status_code=None, status_description_text=None, patent_number=None, claim_parentage_type_code=None, claim_parentage_type_code_description_text=None)

Bases: object

Base class representing continuity data for a patent application.

This includes details about the application’s relationship to other applications (parent/child), its filing status under AIA (America Invents Act), and key identifiers.

first_inventor_to_file_indicator

Boolean indicating if the application is under First-Inventor-to-File provisions.

application_number_text

The application number of the related (parent or child) application.

filing_date

The filing date of the related application.

status_code

The status code of the related application.

status_description_text

The status description of the related application.

patent_number

The patent number if the related application is granted.

claim_parentage_type_code

Code indicating the type of continuity claim (e.g., “CON”, “DIV”).

claim_parentage_type_code_description_text

Description of the continuity claim type.

application_number_text: str | None = None

claim_parentage_type_code: str | None = None

claim_parentage_type_code_description_text: str | None = None

filing_date: date | None = None

first_inventor_to_file_indicator: bool | None = None

property is_aia: bool | None

Returns True if the application is AIA, False if pre-AIA, None if unknown.

property is_pre_aia: bool | None

Returns True if the application is pre-AIA, False if AIA, None if unknown.

patent_number: str | None = None

status_code: int | None = None

status_description_text: str | None = None

to_dict()

Converts the Continuity instance to a dictionary.

Omits attributes that are None and property-derived fields. Keys are converted to camelCase.

Returns:

A dictionary representation of the continuity data.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.CustomerNumberCorrespondence(patron_identifier=None, organization_standard_name=None, power_of_attorney_address_bag=<factory>, telecommunication_address_bag=<factory>)

Bases: object

Represents correspondence data associated with a USPTO customer number.

Includes patron identifier, organization name, power of attorney addresses, and telecommunication details.

patron_identifier

The USPTO customer number.

organization_standard_name

The name of the organization associated with the customer number.

power_of_attorney_address_bag

List of Address objects for power of attorney.

telecommunication_address_bag

List of Telecommunication objects.

classmethod from_dict(data)

Creates a CustomerNumberCorrespondence instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with customer number correspondence data.

Returns:

An instance of CustomerNumberCorrespondence.

Return type:

CustomerNumberCorrespondence

organization_standard_name: str | None = None

patron_identifier: int | None = None

power_of_attorney_address_bag: List[Address]

telecommunication_address_bag: List[Telecommunication]

to_dict()

Converts the CustomerNumberCorrespondence instance to a dictionary.

Omits keys with None values or empty lists.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.DirectionCategory(*values)

Bases: Enum

Represents the direction of a document relative to the USPTO (e.g., INCOMING, OUTGOING).

INCOMING = 'INCOMING'

OUTGOING = 'OUTGOING'

class pyUSPTO.models.patent_data.Document(application_number_text=None, official_date=None, document_identifier=None, document_code=None, document_code_description_text=None, direction_category=None, document_formats=<factory>)

Bases: object

Represents a single document associated with a patent application.

This includes metadata such as its identifier, official date, code, description, direction (incoming/outgoing), and available download formats.

application_number_text

The application number this document belongs to.

official_date

The official date of the document.

document_identifier

A unique identifier for this document.

document_code

A code representing the type of document.

document_code_description_text

A textual description of the document code.

direction_category

The direction of the document (e.g., INCOMING, OUTGOING).

document_formats

A list of available download formats for this document.

application_number_text: str | None = None

direction_category: DirectionCategory | None = None

document_code: str | None = None

document_code_description_text: str | None = None

document_formats: List[DocumentFormat]

document_identifier: str | None = None

classmethod from_dict(data)

Creates a Document instance from a dictionary representation.

Maps API JSON keys (camelCase) to class attributes, parsing nested objects like DocumentFormat and DirectionCategory.

Parameters:

data (Dict[str, Any]) – A dictionary containing document data, typically from an API response.

Returns:

An instance of Document.

Return type:

Document

official_date: datetime | None = None

to_dict()

Converts the Document instance to a dictionary for API compatibility.

Serializes attributes to camelCase keys and handles nested objects. Omits keys with None values or empty lists.

Returns:

A dictionary representation of the Document.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.DocumentBag(documents)

Bases: object

A collection of Document objects associated with a patent application.

Provides iterable access and standard collection methods like len and getitem. This class is immutable by convention after initialization.

documents

An immutable tuple of Document objects.

Type:

tuple[Document, ]

__init__(documents)

Initializes the DocumentBag with a list of documents.

Parameters:

documents (List[Document]) – A list of Document instances.

__repr__()

Returns a detailed string representation for debugging.

Returns:

Detailed representation of the DocumentBag.

Return type:

str

__str__()

Returns a string representation showing document count and summary.

Returns:

Human-readable summary of the DocumentBag.

Return type:

str

property documents: tuple[Document, ...]

Provides access to the tuple of documents.

classmethod from_dict(data)

Creates a DocumentBag instance from a dictionary representation.

Expects a dictionary with a “documentBag” key containing a list of document data dictionaries.

Parameters:

data (Dict[str, Any]) – A dictionary, typically from an API response, containing the document bag.

Returns:

An instance of DocumentBag.

Return type:

DocumentBag

to_dict()

Converts the DocumentBag instance to a dictionary.

Serializes the collection into a dictionary with a “documentBag” key, containing a list of Document dictionaries.

Returns:

A dictionary representation of the DocumentBag.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.DocumentFormat(mime_type_identifier=None, download_url=None, page_total_quantity=None)

Bases: object

Represents an available download format for a specific document.

mime_type_identifier

The MIME type of the downloadable file (e.g., “PDF”).

download_url

The URL from which the document format can be downloaded.

page_total_quantity

The total number of pages in this document format.

download_url: str | None = None

classmethod from_dict(data)

Creates a DocumentFormat instance from a dictionary representation.

This factory method is typically used to construct DocumentFormat objects from data parsed from an API JSON response. It maps dictionary keys (expected in camelCase) to the class attributes.

Parameters:

data (Dict[str, Any]) – A dictionary containing the data for a DocumentFormat. Expected keys from the API are “mimeTypeIdentifier”, “downloadUrl”, and “pageTotalQuantity”.

Returns:

An instance of DocumentFormat initialized with

data from the input dictionary.

Return type:

DocumentFormat

mime_type_identifier: str | None = None

page_total_quantity: int | None = None

to_dict()

Converts the DocumentFormat instance to a dictionary.

This method serializes the DocumentFormat object into a dictionary, mapping the instance’s attributes to camelCase keys. This is typically useful for generating JSON representations compatible with API expectations.

Returns:

A dictionary representation of the DocumentFormat

instance with keys “mimeTypeIdentifier”, “downloadUrl”, and “pageTotalQuantity”.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.EntityStatus(small_entity_status_indicator=None, business_entity_status_category=None)

Bases: object

Represents the entity status of an applicant (e.g., small entity status).

small_entity_status_indicator

Boolean indicating if the applicant qualifies for small entity status.

business_entity_status_category

String category of the business entity status (e.g., “Undiscounted”).

business_entity_status_category: str | None = None

classmethod from_dict(data)

Creates an EntityStatus instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with entity status data.

Returns:

An instance of EntityStatus.

Return type:

EntityStatus

small_entity_status_indicator: bool | None = None

to_dict()

Converts the EntityStatus instance to a dictionary.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.EventData(event_code=None, event_description_text=None, event_date=None)

Bases: object

Represents a single event in the transaction history of a patent application.

event_code

A code identifying the type of event.

event_description_text

A textual description of the event.

event_date

The date the event was recorded.

event_code: str | None = None

event_date: date | None = None

event_description_text: str | None = None

classmethod from_dict(data)

Creates an EventData instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with event data.

Returns:

An instance of EventData.

Return type:

EventData

to_dict()

Converts the EventData instance to a dictionary.

Omits keys with None values and converts field names to camelCase.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.ForeignPriority(ip_office_name=None, filing_date=None, application_number_text=None)

Bases: object

Represents a foreign priority claim for a patent application.

ip_office_name

The name of the intellectual property office of the priority application.

filing_date

The filing date of the priority application.

application_number_text

The application number of the priority application.

application_number_text: str | None = None

filing_date: date | None = None

classmethod from_dict(data)

Creates a ForeignPriority instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with foreign priority data.

Returns:

An instance of ForeignPriority.

Return type:

ForeignPriority

ip_office_name: str | None = None

to_dict()

Converts the ForeignPriority instance to a dictionary.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Inventor(first_name=None, middle_name=None, last_name=None, name_prefix=None, name_suffix=None, preferred_name=None, country_code=None, inventor_name_text=None, correspondence_address_bag=<factory>)

Bases: Person

Represents an inventor for a patent application, inheriting from Person.

Includes inventor-specific name text and a list of correspondence addresses.

inventor_name_text

The full name of the inventor as a single string.

correspondence_address_bag

A list of Address objects for the inventor.

correspondence_address_bag: List[Address]

classmethod from_dict(data)

Creates an Inventor instance from a dictionary.

Inherits person fields and adds inventor-specific fields.

Parameters:

data (Dict[str, Any]) – Dictionary with inventor data.

Returns:

An instance of Inventor.

Return type:

Inventor

inventor_name_text: str | None = None

to_dict()

Converts the Inventor instance to a dictionary.

Includes inherited person fields and inventor-specific fields, using camelCase keys and omitting None values or empty lists.

Returns:

Dictionary representation of the inventor.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.ParentContinuity(first_inventor_to_file_indicator=None, application_number_text=None, filing_date=None, status_code=None, status_description_text=None, patent_number=None, claim_parentage_type_code=None, claim_parentage_type_code_description_text=None, parent_application_status_code=None, parent_patent_number=None, parent_application_status_description_text=None, parent_application_filing_date=None, parent_application_number_text=None, child_application_number_text=None)

Bases: Continuity

Represents a parent application in a patent application’s continuity chain.

Inherits from Continuity and adds specific fields for parent application details.

parent_application_status_code

Status code of the parent application.

parent_patent_number

Patent number of the parent application, if granted.

parent_application_status_description_text

Status description of the parent application.

parent_application_filing_date

Filing date of the parent application.

parent_application_number_text

Application number of the parent application.

child_application_number_text

Application number of the child (current) application.

child_application_number_text: str | None = None

classmethod from_dict(data)

Creates a ParentContinuity instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with parent continuity data.

Returns:

An instance of ParentContinuity.

Return type:

ParentContinuity

parent_application_filing_date: date | None = None

parent_application_number_text: str | None = None

parent_application_status_code: int | None = None

parent_application_status_description_text: str | None = None

parent_patent_number: str | None = None

to_dict()

Converts the ParentContinuity instance to a dictionary.

Maps attributes to specific camelCase keys expected by the API for parent continuity. Filters out None values to match the API response structure.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.PatentDataResponse(count, patent_file_wrapper_data_bag=<factory>, request_identifier=None, raw_data=None)

Bases: object

Represents the overall response from a patent data API request.

It typically includes a count of the results and a list of PatentFileWrapper objects, each containing detailed data for a patent application.

count

The total number of patent applications found matching the query.

patent_file_wrapper_data_bag

A list of PatentFileWrapper objects.

request_identifier

An identifier for the API request, if provided.

raw_data

Optional raw JSON data from the API response (for debugging).

count: int

classmethod from_dict(data, include_raw_data=False)

Creates a PatentDataResponse instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary with API response data.

• include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of PatentDataResponse.

Return type:

PatentDataResponse

patent_file_wrapper_data_bag: List[PatentFileWrapper]

raw_data: str | None = None

request_identifier: str | None = None

to_csv()

Converts the patent data in this response to a CSV formatted string.

The CSV will contain key metadata fields for each application, such as invention title, application number, filing date, status, etc.

Returns:

A string containing the data in CSV format.

Return type:

str

to_dict()

Converts the PatentDataResponse instance to a dictionary.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.PatentFileWrapper(application_number_text=None, application_meta_data=None, correspondence_address_bag=<factory>, assignment_bag=<factory>, record_attorney=None, foreign_priority_bag=<factory>, parent_continuity_bag=<factory>, child_continuity_bag=<factory>, patent_term_adjustment_data=None, event_data_bag=<factory>, pgpub_document_meta_data=None, grant_document_meta_data=None, last_ingestion_date_time=None)

Bases: object

Represents the complete file wrapper for a single patent application.

This is a top-level object containing all data sections related to an application, such as metadata, addresses, assignments, attorney information, continuity data, PTA data, transaction events, and associated document metadata.

application_number_text

The primary application number.

application_meta_data

Comprehensive ApplicationMetaData.

correspondence_address_bag

List of Address objects for correspondence.

assignment_bag

List of Assignment records.

record_attorney

Information about the RecordAttorney.

foreign_priority_bag

List of ForeignPriority claims.

parent_continuity_bag

List of ParentContinuity records.

child_continuity_bag

List of ChildContinuity records.

patent_term_adjustment_data

PatentTermAdjustmentData details.

event_data_bag

List of EventData (transaction history).

pgpub_document_meta_data

PrintedMetaData for Pre-Grant Publication.

grant_document_meta_data

PrintedMetaData for the granted patent.

last_ingestion_date_time

Timestamp of when this data was last ingested by the API (UTC).

application_meta_data: ApplicationMetaData | None = None

application_number_text: str | None = None

assignment_bag: List[Assignment]

child_continuity_bag: List[ChildContinuity]

correspondence_address_bag: List[Address]

event_data_bag: List[EventData]

foreign_priority_bag: List[ForeignPriority]

classmethod from_dict(data, include_raw_data=False)

Creates a PatentFileWrapper instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary with patent file wrapper data.

• include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of PatentFileWrapper.

Return type:

PatentFileWrapper

grant_document_meta_data: PrintedMetaData | None = None

last_ingestion_date_time: datetime | None = None

parent_continuity_bag: List[ParentContinuity]

patent_term_adjustment_data: PatentTermAdjustmentData | None = None

pgpub_document_meta_data: PrintedMetaData | None = None

record_attorney: RecordAttorney | None = None

to_dict()

Converts the PatentFileWrapper instance to a dictionary.

Omits keys with None values or empty lists. Serializes nested objects.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.PatentTermAdjustmentData(a_delay_quantity=None, adjustment_total_quantity=None, applicant_day_delay_quantity=None, b_delay_quantity=None, c_delay_quantity=None, non_overlapping_day_quantity=None, overlapping_day_quantity=None, non_overlapping_day_delay_quantity=None, ip_office_adjustment_delay_quantity=None, patent_term_adjustment_history_data_bag=<factory>)

Bases: object

Represents the overall patent term adjustment (PTA) data for an application.

Includes various delay quantities (A, B, C, applicant, IP office), total adjustment, and a history of PTA events.

a_delay_quantity

Number of days of ‘A’ delay.

adjustment_total_quantity

Total calculated PTA in days.

applicant_day_delay_quantity

Total days of delay attributable to the applicant.

b_delay_quantity

Number of days of ‘B’ delay.

c_delay_quantity

Number of days of ‘C’ delay.

non_overlapping_day_quantity

Number of non-overlapping delay days.

overlapping_day_quantity

Number of overlapping delay days.

non_overlapping_day_delay_quantity

Number of non-overlapping delay days specifically for delay calculation.

ip_office_adjustment_delay_quantity

Days of IP office delay used in adjustment calculation.

patent_term_adjustment_history_data_bag

List of PatentTermAdjustmentHistoryData events.

a_delay_quantity: float | None = None

adjustment_total_quantity: float | None = None

applicant_day_delay_quantity: float | None = None

b_delay_quantity: float | None = None

c_delay_quantity: float | None = None

classmethod from_dict(data)

Creates a PatentTermAdjustmentData instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with PTA data.

Returns:

An instance of PatentTermAdjustmentData.

Return type:

PatentTermAdjustmentData

ip_office_adjustment_delay_quantity: float | None = None

non_overlapping_day_delay_quantity: float | None = None

non_overlapping_day_quantity: float | None = None

overlapping_day_quantity: float | None = None

patent_term_adjustment_history_data_bag: List[PatentTermAdjustmentHistoryData]

to_dict()

Converts the PatentTermAdjustmentData instance to a dictionary.

Omits keys with None values or empty lists, and converts field names to camelCase.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.PatentTermAdjustmentHistoryData(event_date=None, applicant_day_delay_quantity=None, event_description_text=None, event_sequence_number=None, originating_event_sequence_number=None, pta_pte_code=None, ip_office_day_delay_quantity=None)

Bases: object

Represents a single entry in the patent term adjustment (PTA) history for an application.

Details specific events, dates, and day quantities affecting the patent term.

event_date

Date of the PTA event.

applicant_day_delay_quantity

Number of days of delay attributable to the applicant for this event.

event_description_text

Textual description of the PTA event.

event_sequence_number

Sequence number of this event in the PTA history.

originating_event_sequence_number

Sequence number of an event that originated this event.

pta_pte_code

Code indicating if the event relates to PTA or Patent Term Extension (PTE).

ip_office_day_delay_quantity

Number of days of IP office delay used in adjustment calculation for this event.

applicant_day_delay_quantity: float | None = None

event_date: date | None = None

event_description_text: str | None = None

event_sequence_number: float | None = None

classmethod from_dict(data)

Creates a PatentTermAdjustmentHistoryData instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with PTA history event data.

Returns:

An instance of PatentTermAdjustmentHistoryData.

Return type:

PatentTermAdjustmentHistoryData

ip_office_day_delay_quantity: float | None = None

originating_event_sequence_number: float | None = None

pta_pte_code: str | None = None

to_dict()

Converts the PatentTermAdjustmentHistoryData instance to a dictionary.

Omits keys with None values.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Person(first_name=None, middle_name=None, last_name=None, name_prefix=None, name_suffix=None, preferred_name=None, country_code=None)

Bases: object

A base data class representing a person with common name and country attributes.

This class is typically inherited by more specific types like Applicant, Inventor, or Attorney.

first_name

The first name of the person.

middle_name

The middle name or initial of the person.

last_name

The last name or surname of the person.

name_prefix

A prefix for the name (e.g., “Dr.”, “Mr.”).

name_suffix

A suffix for the name (e.g., “Jr.”, “PhD”).

preferred_name

The person’s preferred name, if different.

country_code

The country code associated with the person (e.g., citizenship).

country_code: str | None = None

first_name: str | None = None

last_name: str | None = None

middle_name: str | None = None

name_prefix: str | None = None

name_suffix: str | None = None

preferred_name: str | None = None

to_dict()

Converts the Person instance to a dictionary with camelCase keys.

Omits attributes that are None.

Returns:

A dictionary representation of the person.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.PrintedMetaData(zip_file_name=None, product_identifier=None, file_location_uri=None, file_create_date_time=None, xml_file_name=None)

Bases: object

Represents metadata for a specific archive file, such as a PGPUB or Grant XML file.

zip_file_name

The name of the ZIP archive.

product_identifier

An identifier for the data product (e.g., “APPXML”, “PTGRXML”).

file_location_uri

The URI where the document file can be accessed.

file_create_date_time

The creation timestamp of the document file (UTC).

xml_file_name

The name of the XML file within the ZIP archive.

file_create_date_time: datetime | None = None

file_location_uri: str | None = None

classmethod from_dict(data)

Creates a PrintedMetaData instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with printed metadata.

Returns:

An instance of PrintedMetaData.

Return type:

PrintedMetaData

product_identifier: str | None = None

to_dict()

Converts the PrintedMetaData instance to a dictionary.

Omits keys with None values. Serializes datetime to ISO format with ‘Z’.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

xml_file_name: str | None = None

zip_file_name: str | None = None

class pyUSPTO.models.patent_data.PrintedPublication(pgpub_document_meta_data=None, grant_document_meta_data=None)

Bases: object

Holds metadata for associated documents like Pre-Grant Publications (PGPUB) and Grant documents for a specific patent application.

pgpub_document_meta_data

PrintedMetaData for the Pre-Grant Publication, if any.

grant_document_meta_data

PrintedMetaData for the Grant document, if any.

classmethod from_wrapper(wrapper)

Creates a PrintedPublication instance from a PatentFileWrapper.

Extracts PGPUB and Grant document metadata from the wrapper.

Parameters:

wrapper (PatentFileWrapper) – The patent file wrapper.

Returns:

An instance of PrintedPublication.

Return type:

PrintedPublication

grant_document_meta_data: PrintedMetaData | None = None

pgpub_document_meta_data: PrintedMetaData | None = None

to_dict()

Converts the PrintedPublication instance to a dictionary.

Omits keys if their corresponding metadata is None.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.RecordAttorney(customer_number_correspondence_data=None, power_of_attorney_bag=<factory>, attorney_bag=<factory>)

Bases: object

Represents information about the attorney(s) of record for a patent application.

Contains customer number correspondence data, power of attorney information, and listed attorneys.

customer_number_correspondence_data

CustomerNumberCorrespondence object with customer number details.

power_of_attorney_bag

List of Attorney objects named in a power of attorney.

attorney_bag

List of Attorney objects listed as attorneys of record.

attorney_bag: List[Attorney]

customer_number_correspondence_data: CustomerNumberCorrespondence | None = None

classmethod from_dict(data)

Creates a RecordAttorney instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with record attorney data.

Returns:

An instance of RecordAttorney.

Return type:

RecordAttorney

power_of_attorney_bag: List[Attorney]

to_dict()

Converts the RecordAttorney instance to a dictionary.

Omits keys with None values. Includes empty lists to match API behavior.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.StatusCode(code=None, description=None)

Bases: object

Represents a USPTO application status code and its textual description.

code

The numeric status code.

description

The textual description of the status code.

__str__()

Returns a user-friendly string representation of the status code.

Return type:

str

code: int | None = None

description: str | None = None

classmethod from_dict(data)

Creates a StatusCode instance from a dictionary.

Handles two possible key sets from the API for status information.

Parameters:

data (Dict[str, Any]) – Dictionary with status code data.

Returns:

An instance of StatusCode.

Return type:

StatusCode

to_dict()

Converts the StatusCode instance to a dictionary.

Uses keys “applicationStatusCode” and “applicationStatusDescriptionText” for consistency with some API response parts.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.StatusCodeCollection(status_codes)

Bases: object

A collection of StatusCode objects.

Provides iterable access and helper methods to find or filter status codes. This class is immutable by convention after initialization.

status_codes

An immutable tuple of StatusCode objects.

Type:

tuple[StatusCode, ]

__init__(status_codes)

Initializes the StatusCodeCollection with a list of status codes.

Parameters:

status_codes (List[StatusCode]) – A list of StatusCode instances.

find_by_code(code_to_find)

Finds a status code by its numeric code.

Parameters:

code_to_find (int) – The numeric status code to search for.

Returns:

The StatusCode object if found, otherwise None.

Return type:

Optional[StatusCode]

search_by_description(text)

Searches for status codes by a case-insensitive text match in their description.

Parameters:

text (str) – The text to search for within status code descriptions.

Returns:

A new collection containing matching status codes.

Return type:

StatusCodeCollection

to_dict()

Converts the collection of status codes to a list of dictionaries.

Returns:

A list where each item is the dictionary

representation of a StatusCode.

Return type:

List[Dict[str, Any]]

class pyUSPTO.models.patent_data.StatusCodeSearchResponse(count, status_code_bag, request_identifier=None)

Bases: object

Represents the response from a search query for patent application status codes.

count

The total number of status codes found matching the query.

status_code_bag

A StatusCodeCollection of the StatusCode objects returned.

request_identifier

An identifier for the API request, if provided.

count: int

classmethod from_dict(data)

Creates a StatusCodeSearchResponse instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with API response data for status codes.

Returns:

An instance of StatusCodeSearchResponse.

Return type:

StatusCodeSearchResponse

request_identifier: str | None = None

status_code_bag: StatusCodeCollection

to_dict()

Converts the StatusCodeSearchResponse instance to a dictionary.

Omits keys with None values or empty lists.

Returns:

Dictionary representation.

Return type:

Dict[str, Any]

class pyUSPTO.models.patent_data.Telecommunication(telecommunication_number=None, extension_number=None, telecom_type_code=None)

Bases: object

Represents telecommunication details, such as phone or fax numbers.

telecommunication_number

The main number (e.g., phone number).

extension_number

Any extension associated with the number.

telecom_type_code

A code indicating the type of telecommunication (e.g., “TEL”, “FAX”).

extension_number: str | None = None

classmethod from_dict(data)

Creates a Telecommunication instance from a dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with telecommunication data.

Returns:

An instance of Telecommunication.

Return type:

Telecommunication

telecom_type_code: str | None = None

telecommunication_number: str | None = None

to_dict()

Converts the Telecommunication instance to a dictionary.

Returns:

Dictionary representation with camelCase keys.

Return type:

Dict[str, Any]

models.ptab - Data models for USPTO PTAB (Patent Trial and Appeal Board) APIs

This module provides data models, primarily using frozen dataclasses, for representing responses from the USPTO PTAB APIs. These models cover: - Patent trial proceedings (IPR, PGR, CBM, DER) - Trial documents and decisions - Appeal decisions - Interference decisions

class pyUSPTO.models.ptab.AdditionalPartyData(application_number_text=None, inventor_name=None, patent_number=None, additional_party_name=None)

Bases: object

Additional party information in an interference.

application_number_text

Application number.

inventor_name

Name of inventor.

patent_number

Patent number.

additional_party_name

Name of additional party.

additional_party_name: str | None = None

application_number_text: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an AdditionalPartyData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing additional party data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AdditionalPartyData.

Return type:

AdditionalPartyData

inventor_name: str | None = None

patent_number: str | None = None

to_dict()

Converts the AdditionalPartyData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.AppealDocumentData(document_filing_date=None, document_identifier=None, document_name=None, document_size_quantity=None, document_ocr_text=None, document_type_description_text=None, file_download_uri=None)

Bases: object

Appeal document metadata.

document_filing_date

Date the document was filed.

document_identifier

Unique identifier for the document.

document_name

Name of the document.

document_size_quantity

Size of the document in bytes.

document_ocr_text

Full OCR text of the document.

document_type_description_text

Description of the document type.

file_download_uri

URI to download the document.

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_type_description_text: str | None = None

file_download_uri: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an AppealDocumentData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing document data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AppealDocumentData.

Return type:

AppealDocumentData

to_dict()

Converts the AppealDocumentData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.AppealMetaData(appeal_filing_date=None, appeal_last_modified_date=None, appeal_last_modified_date_time=None, application_type_category=None, docket_notice_mailed_date=None, file_download_uri=None)

Bases: object

Appeal metadata.

appeal_filing_date

Date the appeal was filed.

appeal_last_modified_date

Last modification date.

appeal_last_modified_date_time

Last modification timestamp.

application_type_category

Type of application.

docket_notice_mailed_date

Date the docket notice was mailed.

file_download_uri

URI to download ZIP of appeal documents.

appeal_filing_date: date | None = None

appeal_last_modified_date: date | None = None

appeal_last_modified_date_time: datetime | None = None

application_type_category: str | None = None

docket_notice_mailed_date: date | None = None

file_download_uri: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an AppealMetaData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing appeal metadata from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AppealMetaData.

Return type:

AppealMetaData

to_dict()

Converts the AppealMetaData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.AppellantData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Appellant party data in PTAB appeals.

Inherits all attributes from PartyData. Used in appeal proceedings to represent the party appealing an examiner decision.

class pyUSPTO.models.ptab.DecisionData(appeal_outcome_category=None, statute_and_rule_bag=<factory>, decision_issue_date=None, decision_type_category=None, issue_type_bag=<factory>)

Bases: object

Appeal decision information.

appeal_outcome_category

Outcome of the appeal.

statute_and_rule_bag

List of applicable statutes and rules.

decision_issue_date

Date the decision was issued.

decision_type_category

Type of decision.

issue_type_bag

List of issue types.

appeal_outcome_category: str | None = None

decision_issue_date: date | None = None

decision_type_category: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a DecisionData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing decision data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of DecisionData.

Return type:

DecisionData

issue_type_bag: List[str]

statute_and_rule_bag: List[str]

to_dict()

Converts the DecisionData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.DerivationPetitionerData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Derivation petitioner data in derivation proceedings.

Inherits all attributes from PartyData. Used in DER proceedings to represent the petitioning party claiming derivation.

class pyUSPTO.models.ptab.InterferenceDocumentData(document_identifier=None, document_name=None, document_size_quantity=None, document_ocr_text=None, document_title_text=None, interference_outcome_category=None, document_filing_date=None, decision_issue_date=None, decision_type_category=None, file_download_uri=None, statute_and_rule_bag=<factory>, issue_type_bag=<factory>)

Bases: object

Interference document metadata.

document_identifier

Unique identifier for the document.

document_name

Name of the document.

document_size_quantity

Size of the document in bytes.

document_ocr_text

Full OCR text of the document.

document_title_text

Title of the document.

interference_outcome_category

Outcome of the interference.

document_filing_date

Date the document was filed.

decision_issue_date

Date the decision was issued.

decision_type_category

Type of decision.

file_download_uri

URI to download the document.

statute_and_rule_bag

List of applicable statutes and rules.

issue_type_bag

List of issues addressed.

decision_issue_date: date | None = None

decision_type_category: str | None = None

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_title_text: str | None = None

file_download_uri: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an InterferenceDocumentData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing document data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of InterferenceDocumentData.

Return type:

InterferenceDocumentData

interference_outcome_category: str | None = None

issue_type_bag: List[str]

statute_and_rule_bag: List[str]

to_dict()

Converts the InterferenceDocumentData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.InterferenceMetaData(interference_style_name=None, interference_last_modified_date=None, interference_last_modified_date_time=None, declaration_date=None, file_download_uri=None)

Bases: object

Interference metadata.

interference_style_name

Style name of the interference.

interference_last_modified_date

Last modification date.

interference_last_modified_date_time

Last modification datetime.

declaration_date

Declaration date.

file_download_uri

URI to download ZIP of interference documents.

declaration_date: date | None = None

file_download_uri: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates an InterferenceMetaData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing interference metadata from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of InterferenceMetaData.

Return type:

InterferenceMetaData

interference_last_modified_date: date | None = None

interference_last_modified_date_time: datetime | None = None

interference_style_name: str | None = None

to_dict()

Converts the InterferenceMetaData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.JuniorPartyData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Junior party information in PTAB interference proceedings.

Inherits all attributes from PartyData. Represents the party with the later effective filing date in an interference.

class pyUSPTO.models.ptab.PTABAppealDecision(appeal_number=None, last_modified_date_time=None, appeal_document_category=None, appeal_meta_data=None, appellant_data=None, requestor_data=None, document_data=None, decision_data=None, raw_data=None)

Bases: object

Individual PTAB appeal decision record.

appeal_number

Appeal number.

last_modified_date_time

Last modification timestamp.

appeal_document_category

Document category.

appeal_meta_data

Appeal metadata.

appellant_data

Appellant information.

requestor_data

Third party requestor information.

document_data

Document metadata.

decision_data

Decision information.

raw_data

Raw JSON response data (if include_raw_data=True).

appeal_document_category: str | None = None

appeal_meta_data: AppealMetaData | None = None

appeal_number: str | None = None

appellant_data: AppellantData | None = None

decision_data: DecisionData | None = None

document_data: AppealDocumentData | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a PTABAppealDecision instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing appeal decision data from API response.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABAppealDecision.

Return type:

PTABAppealDecision

last_modified_date_time: datetime | None = None

raw_data: Dict[str, Any] | None = None

requestor_data: RequestorData | None = None

to_dict()

Converts the PTABAppealDecision instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PTABAppealResponse(count=0, request_identifier=None, patent_appeal_data_bag=<factory>, raw_data=None)

Bases: object

Response container for PTAB appeals search.

count

Total number of matching results.

request_identifier

UUID for the API request.

patent_appeal_data_bag

List of appeal decisions.

raw_data

Raw JSON response data (if include_raw_data=True).

count: int = 0

classmethod from_dict(data, include_raw_data=False)

Creates a PTABAppealResponse instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing response data from API.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABAppealResponse.

Return type:

PTABAppealResponse

patent_appeal_data_bag: List[PTABAppealDecision]

raw_data: Dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()

Converts the PTABAppealResponse instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PTABInterferenceDecision(interference_number=None, last_modified_date_time=None, interference_meta_data=None, senior_party_data=None, junior_party_data=None, additional_party_data_bag=<factory>, document_data=None, raw_data=None)

Bases: object

Individual PTAB interference decision record.

interference_number

Interference number.

last_modified_date_time

Last modification timestamp.

interference_meta_data

Interference metadata.

senior_party_data

Senior party information.

junior_party_data

Junior party information.

additional_party_data_bag

List of additional parties.

document_data

Document metadata.

raw_data

Raw JSON response data (if include_raw_data=True).

additional_party_data_bag: List[AdditionalPartyData]

document_data: InterferenceDocumentData | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a PTABInterferenceDecision instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing interference decision data from API response.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABInterferenceDecision.

Return type:

PTABInterferenceDecision

interference_meta_data: InterferenceMetaData | None = None

interference_number: str | None = None

junior_party_data: JuniorPartyData | None = None

last_modified_date_time: datetime | None = None

raw_data: Dict[str, Any] | None = None

senior_party_data: SeniorPartyData | None = None

to_dict()

Converts the PTABInterferenceDecision instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PTABInterferenceResponse(count=0, request_identifier=None, patent_interference_data_bag=<factory>, raw_data=None)

Bases: object

Response container for PTAB interferences search.

count

Total number of matching results.

request_identifier

UUID for the API request.

patent_interference_data_bag

List of interference decisions.

raw_data

Raw JSON response data (if include_raw_data=True).

count: int = 0

classmethod from_dict(data, include_raw_data=False)

Creates a PTABInterferenceResponse instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing response data from API.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABInterferenceResponse.

Return type:

PTABInterferenceResponse

patent_interference_data_bag: List[PTABInterferenceDecision]

raw_data: Dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()

Converts the PTABInterferenceResponse instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PTABTrialDocument(trial_document_category=None, last_modified_date_time=None, trial_number=None, trial_type_code=None, trial_meta_data=None, patent_owner_data=None, regular_petitioner_data=None, respondent_data=None, derivation_petitioner_data=None, document_data=None, decision_data=None, raw_data=None)

Bases: object

Individual trial document or decision record from PTAB document/decision search APIs.

Used by search_documents() and search_decisions() endpoints. Contains document-specific metadata (documentData) or decision information (decisionData), plus trial context. Differs from PTABTrialProceeding which represents the entire proceeding rather than individual documents within it.

trial_document_category

Category (Document or Decision).

last_modified_date_time

Last modification timestamp.

trial_number

Trial number (e.g., “IPR2023-00123”).

trial_type_code

Type of trial (IPR, PGR, CBM, DER).

trial_meta_data

Trial metadata.

patent_owner_data

Patent owner information.

regular_petitioner_data

Regular petitioner information.

respondent_data

Respondent information.

derivation_petitioner_data

Derivation petitioner information.

document_data

Document metadata (if document).

decision_data

Decision information (if decision).

raw_data

Raw JSON response data (if include_raw_data=True).

decision_data: TrialDecisionData | None = None

derivation_petitioner_data: DerivationPetitionerData | None = None

document_data: TrialDocumentData | None = None

classmethod from_dict(data, include_raw_data=False)

Return type:

PTABTrialDocument

last_modified_date_time: datetime | None = None

patent_owner_data: PatentOwnerData | None = None

raw_data: Dict[str, Any] | None = None

regular_petitioner_data: RegularPetitionerData | None = None

respondent_data: RespondentData | None = None

to_dict()

Converts the PTABTrialDocument instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

trial_document_category: str | None = None

trial_meta_data: TrialMetaData | None = None

trial_number: str | None = None

trial_type_code: str | None = None

class pyUSPTO.models.ptab.PTABTrialDocumentResponse(count=0, request_identifier=None, patent_trial_document_data_bag=<factory>, raw_data=None)

Bases: object

Response container for PTAB trial documents/decisions search.

count: int = 0

classmethod from_dict(data, include_raw_data=False)

Return type:

PTABTrialDocumentResponse

patent_trial_document_data_bag: List[PTABTrialDocument]

raw_data: Dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()

Converts the PTABTrialDocumentResponse instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PTABTrialProceeding(trial_number=None, last_modified_date_time=None, trial_meta_data=None, patent_owner_data=None, regular_petitioner_data=None, respondent_data=None, derivation_petitioner_data=None, raw_data=None)

Bases: object

Individual PTAB trial proceeding record.

trial_number

Trial number (e.g., “IPR2023-00123”).

trial_record_identifier

UUID identifier for the trial record.

last_modified_date_time

Last modification timestamp.

trial_meta_data

Trial metadata.

patent_owner_data

Patent owner information.

regular_petitioner_data

Regular petitioner information.

respondent_data

Respondent information.

derivation_petitioner_data

Derivation petitioner information.

raw_data

Raw JSON response data (if include_raw_data=True).

derivation_petitioner_data: DerivationPetitionerData | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a PTABTrialProceeding instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing trial proceeding data from API response.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABTrialProceeding.

Return type:

PTABTrialProceeding

last_modified_date_time: datetime | None = None

patent_owner_data: PatentOwnerData | None = None

raw_data: Dict[str, Any] | None = None

regular_petitioner_data: RegularPetitionerData | None = None

respondent_data: RespondentData | None = None

to_dict()

Converts the PTABTrialProceeding instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

trial_meta_data: TrialMetaData | None = None

trial_number: str | None = None

class pyUSPTO.models.ptab.PTABTrialProceedingResponse(count=0, request_identifier=None, patent_trial_proceeding_data_bag=<factory>, raw_data=None)

Bases: object

Response container for PTAB trial proceedings search.

count

Total number of matching results.

request_identifier

UUID for the API request.

patent_trial_proceeding_data_bag

List of trial proceedings.

raw_data

Raw JSON response data (if include_raw_data=True).

count: int = 0

classmethod from_dict(data, include_raw_data=False)

Creates a PTABTrialProceedingResponse instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing response data from API.

• include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABTrialProceedingResponse.

Return type:

PTABTrialProceedingResponse

patent_trial_proceeding_data_bag: List[PTABTrialProceeding]

raw_data: Dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()

Converts the PTABTrialProceedingResponse instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.PatentOwnerData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Party data for a patent owner in PTAB trial proceedings.

Inherits all attributes from PartyData. Used in IPR, PGR, CBM, and DER proceedings to represent the patent holder.

class pyUSPTO.models.ptab.RegularPetitionerData(counsel_name=None, real_party_in_interest_name=None)

Bases: object

Regular petitioner information.

counsel_name

Name of counsel.

real_party_in_interest_name

Real party in interest name.

counsel_name: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a RegularPetitionerData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing petitioner data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of RegularPetitionerData.

Return type:

RegularPetitionerData

real_party_in_interest_name: str | None = None

to_dict()

Converts the RegularPetitionerData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.RequestorData(third_party_name=None)

Bases: object

Third party requestor information.

third_party_name

Name of the third party.

classmethod from_dict(data, include_raw_data=False)

Creates a RequestorData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing requestor data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of RequestorData.

Return type:

RequestorData

third_party_name: str | None = None

to_dict()

Converts the RequestorData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.RespondentData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Respondent party data in derivation proceedings.

Inherits all attributes from PartyData. Used in DER proceedings to represent the responding party.

class pyUSPTO.models.ptab.SeniorPartyData(application_number_text=None, counsel_name=None, grant_date=None, group_art_unit_number=None, inventor_name=None, real_party_in_interest_name=None, patent_number=None, patent_owner_name=None, technology_center_number=None, publication_date=None, publication_number=None)

Bases: PartyData

Senior party information in PTAB interference proceedings.

Inherits all attributes from PartyData. Represents the party with the earlier effective filing date in an interference.

class pyUSPTO.models.ptab.TrialDecisionData(statute_and_rule_bag=<factory>, decision_issue_date=None, decision_type_category=None, issue_type_bag=<factory>, trial_outcome_category=None)

Bases: object

Metadata for a decision in a PTAB trial.

statute_and_rule_bag

List of applicable statutes and rules.

decision_issue_date

Date issued.

decision_type_category

Type of decision (e.g. “Final Written Decision”).

issue_type_bag

List of issues addressed.

trial_outcome_category

Outcome (e.g., “Denied”).

decision_issue_date: date | None = None

decision_type_category: str | None = None

classmethod from_dict(data)

Return type:

TrialDecisionData

issue_type_bag: List[str]

statute_and_rule_bag: List[str]

to_dict()

Converts the TrialDecisionData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

trial_outcome_category: str | None = None

class pyUSPTO.models.ptab.TrialDocumentData(document_filing_date=None, document_identifier=None, document_name=None, document_number=None, document_size_quantity=None, document_ocr_text=None, document_title_text=None, document_type_description_text=None, file_download_uri=None, filing_party_category=None)

Bases: object

Metadata for a document in a PTAB trial.

document_category

Category of the document.

document_filing_date

Filing date.

document_identifier

Unique ID.

document_name

Filename.

document_number

Document number in the proceeding.

document_size_quantity

Size in bytes.

document_ocr_text

OCR text content.

document_title_text

Title of the document.

document_type_description_text

Description of document type.

file_download_uri

URL to download the file.

filing_party_category

Who filed (e.g., “Petitioner”).

mime_type_identifier

MIME type (e.g., “application/pdf”).

document_status

Public status.

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_number: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_title_text: str | None = None

document_type_description_text: str | None = None

file_download_uri: str | None = None

filing_party_category: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a TrialDocumentData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing document data from API response.

• include_raw_data (bool) – Ignored for this model.

Returns:

An instance of TrialDocumentData.

Return type:

TrialDocumentData

to_dict()

Converts the TrialDocumentData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

class pyUSPTO.models.ptab.TrialMetaData(petition_filing_date=None, accorded_filing_date=None, trial_last_modified_date_time=None, trial_last_modified_date=None, trial_status_category=None, trial_type_code=None, file_download_uri=None, termination_date=None, latest_decision_date=None, institution_decision_date=None)

Bases: object

Trial metadata including status, dates, and download URI.

petition_filing_date

Date the petition was filed.

accorded_filing_date

The filing date accorded to the petition.

trial_last_modified_date_time

Last modification timestamp.

trial_last_modified_date

Last modification date.

trial_status_category

Status of the trial (e.g., “Institution Denied”, “Instituted”).

trial_type_code

Type of trial (IPR, PGR, CBM, DER).

file_download_uri

URI to download ZIP of all trial documents.

termination_date

Date the trial was terminated.

latest_decision_date

Date of the most recent decision.

institution_decision_date

Date of the institution decision.

accorded_filing_date: date | None = None

file_download_uri: str | None = None

classmethod from_dict(data, include_raw_data=False)

Creates a TrialMetaData instance from a dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary containing trial metadata from API response.

• include_raw_data (bool) – Ignored for this model (no raw_data field).

Returns:

An instance of TrialMetaData.

Return type:

TrialMetaData

institution_decision_date: date | None = None

latest_decision_date: date | None = None

petition_filing_date: date | None = None

termination_date: date | None = None

to_dict()

Converts the TrialMetaData instance to a dictionary.

Returns:

Dictionary with camelCase keys and None values filtered.

Return type:

Dict[str, Any]

trial_last_modified_date: date | None = None

trial_last_modified_date_time: datetime | None = None

trial_status_category: str | None = None

trial_type_code: str | None = None

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

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

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

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

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

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

Serializes 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]

pyUSPTO.models.utils.serialize_datetime_as_naive(dt)

Return type:

str

pyUSPTO.models.utils.to_camel_case(snake_str)

Converts 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