Patent Data

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)[source]

Bases: Enum

Represent 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)[source]

Bases: object

Represent 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. Deprecated: USPTO ODP Release 3.6 (2026-04-10) removed this field from the Patent Assignment API response. Read geographic_region_code instead; this attribute will be None for responses from updated endpoints.

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)[source]

Create 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()[source]

Convert 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>)[source]

Bases: Person

Represent 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)[source]

Create 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()[source]

Convert 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>)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert 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>)[source]

Bases: Person

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

Bases: Continuity

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

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()[source]

Convert 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>)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

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>)[source]

Bases: object

Represent 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.

__repr__()[source]

Return a developer-friendly string representation of the Document.

Returns:: A string showing the document ID, code, and date.
Return type:: str

__str__()[source]

Return a human-readable string representation of the Document.

Returns:: A description including document ID, code, description, and date.
Return type:: str

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)[source]

Create 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

get_format(format)[source]

Get the DocumentFormat object for a specific format.

Parameters:: format (str | DocumentMimeType) – The format to retrieve. Can be a string (e.g., “XML”, “PDF”) or a DocumentMimeType enum value.
Return type:: DocumentFormat | None
Returns:: The DocumentFormat object if found, None otherwise.

Example

>>> xml_format = doc.get_format("XML")
>>> if xml_format:
>>>     print(f"XML has {xml_format.page_total_quantity} pages")

has_format(format)[source]

Check if this document has a specific format available.

Parameters:: format (str | DocumentMimeType) – The format to check for. Can be a string (e.g., “XML”, “PDF”) or a DocumentMimeType enum value.
Return type:: bool
Returns:: True if the document has the specified format, False otherwise.

Example

>>> if doc.has_format("XML"):
>>>     client.download_document(doc, format="XML")

official_date: datetime | None = None

to_dict()[source]

Convert 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)[source]

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

__getitem__(index)[source]

Return the document at the specified index.

Parameters:: index (int) – The index of the document to retrieve.
Returns:: The document at the specified index.
Return type:: Document

__init__(documents)[source]

Initialize a DocumentBag with a list of documents.

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

__iter__()[source]

Return an iterator over the documents in the collection.

Returns:: An iterator of Document instances.
Return type:: Iterator[Document]

__len__()[source]

Return the number of documents in the collection.

Returns:: The count of documents.
Return type:: int

__repr__()[source]

Return a detailed string representation for debugging.

Returns:: Detailed representation of the DocumentBag.
Return type:: str

__str__()[source]

Return a string representation showing document count and summary.

Returns:: Human-readable summary of the DocumentBag.
Return type:: str

property documents: tuple[Document, ...]: Provide access to the tuple of documents.

filter_by_format(format)[source]

Filter documents to only include those with a specific format.

Parameters:: format (str | DocumentMimeType) – The format to filter by. Can be a string (e.g., “XML”, “PDF”) or a DocumentMimeType enum value.
Return type:: DocumentBag
Returns:: A new DocumentBag containing only documents that have the specified format.

Example

>>> all_docs = client.get_application_documents(app_no)
>>> xml_docs = all_docs.filter_by_format("XML")
>>> for doc in xml_docs:
>>>     client.download_document(doc, format="XML")

classmethod from_dict(data, include_raw_data=False)[source]

Create 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.
include_raw_data (bool) – Unused. Present for FromDictProtocol conformance.

Returns:

An instance of DocumentBag.

Return type:

DocumentBag

to_dict()[source]

Convert 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)[source]

Bases: object

Represent 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.

__repr__()[source]

Return a developer-friendly string representation of the DocumentFormat.

Returns:: A string showing the mime type and page count.
Return type:: str

__str__()[source]

Return a human-readable string representation of the DocumentFormat.

Returns:: A description of the format type and page count.
Return type:: str

download_url: str | None = None

classmethod from_dict(data)[source]

Create 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()[source]

Convert 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.DocumentMimeType(*values)[source]

Bases: str, Enum

MIME types for document downloads from USPTO.

MS_WORD = 'MS_WORD'

PDF = 'PDF'

XML = 'XML'

class pyUSPTO.models.patent_data.EntityStatus(small_entity_status_indicator=None, business_entity_status_category=None)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert the ForeignPriority instance to a dictionary.

Returns:: Dictionary representation with camelCase keys.
Return type:: dict[str, Any]

class pyUSPTO.models.patent_data.IFWResult(wrapper, output_path, downloaded_documents)[source]

Bases: object

Result of a get_IFW call: metadata wrapper, output path, and document map.

wrapper: The PatentFileWrapper containing all IFW metadata and document_bag.

output_path: Absolute path to the ZIP archive (when as_zip=True) or the output directory (when as_zip=False).

downloaded_documents: Maps document_identifier to the filename of the downloaded file — the arcname inside the ZIP (as_zip=True) or the basename inside the output directory (as_zip=False). Documents that were skipped (no PDF/DOCX URL) or failed to download are absent.

downloaded_documents: dict[str, str]

output_path: str

wrapper: PatentFileWrapper

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>)[source]

Bases: Person

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

Bases: Continuity

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

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)[source]

Create 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()[source]

Convert 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()[source]

Convert the PatentDataResponse instance to a dictionary.

Returns:: Dictionary representation.
Return type:: dict[str, Any]

class pyUSPTO.models.patent_data.PatentFileWrapper(application_number_text, 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, document_bag=None)[source]

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

document_bag: DocumentBag containing associated documents and their metadata.

application_meta_data: ApplicationMetaData | None = None

application_number_text: str

assignment_bag: list[Assignment]

child_continuity_bag: list[ChildContinuity]

correspondence_address_bag: list[Address]

document_bag: DocumentBag | None = None

event_data_bag: list[EventData]

foreign_priority_bag: list[ForeignPriority]

classmethod from_dict(data, include_raw_data=False)[source]

Create 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()[source]

Convert 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>)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert 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)[source]

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()[source]

Convert 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)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent metadata for associated documents such as PGPUB and Grant publications.

Note

PGPUB refers to a Pre-Grant Publication.

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)[source]

Create 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()[source]

Convert 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>)[source]

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)[source]

Create 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()[source]

Convert 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)[source]

Bases: object

Represent a USPTO application status code and its textual description.

code: The numeric status code.

description: The textual description of the status code.

__str__()[source]

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

Return type:: str

code: int | None = None

description: str | None = None

classmethod from_dict(data)[source]

Create 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()[source]

Convert 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)[source]

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

__getitem__(index)[source]

Return the status code at the specified index.

Parameters:: index (int) – The index of the status code to retrieve.
Returns:: The status code at the specified index.
Return type:: StatusCode

__init__(status_codes)[source]

Initialize a StatusCodeCollection with a list of status codes.

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

__iter__()[source]

Return an iterator over the status codes in the collection.

Returns:: An iterator of StatusCode instances.
Return type:: Iterator[StatusCode]

__len__()[source]

Return the number of status codes in the collection.

Returns:: The count of status codes.
Return type:: int

__repr__()[source]

Return a developer-friendly string representation of the StatusCodeCollection.

Returns:: A string showing the collection size and sample status codes.
Return type:: str

__str__()[source]

Return a human-readable string representation of the StatusCodeCollection.

Returns:: A description of the collection size.
Return type:: str

find_by_code(code_to_find)[source]

Find 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:: StatusCode | None

search_by_description(text)[source]

Search 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()[source]

Convert 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)[source]

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, include_raw_data=False)[source]

Create a StatusCodeSearchResponse instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary with API response data for status codes.
include_raw_data (bool) – Unused. Present for FromDictProtocol conformance.

Returns:

An instance of StatusCodeSearchResponse.

Return type:

StatusCodeSearchResponse

request_identifier: str | None = None

status_code_bag: StatusCodeCollection

to_dict()[source]

Convert 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)[source]

Bases: object

Represent 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)[source]

Create 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()[source]

Convert the Telecommunication instance to a dictionary.

Returns:: Dictionary representation with camelCase keys.
Return type:: dict[str, Any]