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

Bases: object

Represents a product in the bulk data API.

days_of_week_text: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[ProductFileBag] = 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)[source]

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

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: Optional[str] = None

to_dict()[source]

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

Bases: object

Represents a file in the bulk data API.

file_data_from_date: str

file_data_to_date: str

file_date: Optional[str] = None

file_download_uri: Optional[str] = None

file_last_modified_date_time: Optional[str] = None

file_name: str

file_release_date: str

file_size: int

file_type_text: str

classmethod from_dict(data)[source]

Create a FileData object from a dictionary.

Return type:: FileData

class pyUSPTO.models.bulk_data.ProductFileBag(count, file_data_bag)[source]

Bases: object

Container for file data elements.

count: int

file_data_bag: List[FileData]

classmethod from_dict(data)[source]

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

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

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.

address_line_four_text: Optional[str] = None

address_line_one_text: Optional[str] = None

address_line_three_text: Optional[str] = None

address_line_two_text: Optional[str] = None

city_name: Optional[str] = None

correspondent_name_text: Optional[str] = None

country_code: Optional[str] = None

country_name: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

geographic_region_name: Optional[str] = None

name_line_one_text: Optional[str] = None

name_line_two_text: Optional[str] = None

postal_address_category: Optional[str] = None

postal_code: Optional[str] = None

to_dict()[source]

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

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: Optional[str] = None

correspondence_address_bag: List[Address]

classmethod from_dict(data)[source]

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

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

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

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

Bases: object

Represents the comprehensive 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: Optional[int] = None

application_status_code: Optional[int] = None

application_status_date: Optional[date] = None

application_status_description_text: Optional[str] = None

application_type_category: Optional[str] = None

application_type_code: Optional[str] = None

application_type_label_name: Optional[str] = None

class_field: Optional[str] = None

cpc_classification_bag: List[str]

customer_number: Optional[int] = None

docket_number: Optional[str] = None

earliest_publication_date: Optional[date] = None

earliest_publication_number: Optional[str] = None

effective_filing_date: Optional[date] = None

entity_status_data: Optional[EntityStatus] = None

examiner_name_text: Optional[str] = None

filing_date: Optional[date] = None

first_applicant_name: Optional[str] = None

first_inventor_name: Optional[str] = None

first_inventor_to_file_indicator: Optional[bool] = None

classmethod from_dict(data)[source]

Creates an ApplicationMetaData instance from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with application metadata.
Returns:: An instance of ApplicationMetaData.
Return type:: ApplicationMetaData

grant_date: Optional[date] = None

group_art_unit_number: Optional[str] = None

international_registration_number: Optional[str] = None

international_registration_publication_date: Optional[date] = None

invention_title: Optional[str] = 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: Optional[bool] = None

patent_number: Optional[str] = None

pct_publication_date: Optional[date] = None

pct_publication_number: Optional[str] = None

publication_category_bag: List[str]

publication_date_bag: List[date]

publication_sequence_number_bag: List[str]

raw_data: Optional[str] = None

subclass: Optional[str] = None

to_dict()[source]

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: Optional[str] = None

class pyUSPTO.models.patent_data.Assignee(assignee_name_text=None, assignee_address=None)[source]

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: Optional[Address] = None

assignee_name_text: Optional[str] = None

classmethod from_dict(data)[source]

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

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, assignor_bag=<factory>, assignee_bag=<factory>, correspondence_address_bag=<factory>)[source]

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, and correspondence addresses.

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.

assignor_bag: List of Assignor objects.

assignee_bag: List of Assignee objects.

correspondence_address_bag: List of Address objects for correspondence.

assignee_bag: List[Assignee]

assignment_document_location_uri: Optional[str] = None

assignment_mailed_date: Optional[date] = None

assignment_received_date: Optional[date] = None

assignment_recorded_date: Optional[date] = None

assignor_bag: List[Assignor]

conveyance_text: Optional[str] = None

correspondence_address_bag: List[Address]

frame_number: Optional[int] = None

classmethod from_dict(data)[source]

Creates an Assignment instance from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with assignment data.
Returns:: An instance of Assignment.
Return type:: Assignment

page_total_quantity: Optional[int] = None

reel_and_frame_number: Optional[str] = None

reel_number: Optional[int] = None

to_dict()[source]

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

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: Optional[str] = None

execution_date: Optional[date] = None

classmethod from_dict(data)[source]

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

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

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: Optional[str] = None

attorney_address_bag: List[Address]

classmethod from_dict(data)[source]

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: Optional[str] = None

registration_number: Optional[str] = None

telecommunication_address_bag: List[Telecommunication]

to_dict()[source]

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

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: Optional[date] = None

child_application_number_text: Optional[str] = None

child_application_status_code: Optional[int] = None

child_application_status_description_text: Optional[str] = None

child_patent_number: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

to_dict()[source]

Converts the ChildContinuity instance to a dictionary.

Maps attributes to specific camelCase keys expected by the API for child continuity.

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: Optional[str] = None

claim_parentage_type_code: Optional[str] = None

claim_parentage_type_code_description_text: Optional[str] = None

filing_date: Optional[date] = None

first_inventor_to_file_indicator: Optional[bool] = 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: Optional[str] = None

status_code: Optional[int] = None

status_description_text: Optional[str] = None

to_dict()[source]

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

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: Optional[str] = None

patron_identifier: Optional[int] = None

power_of_attorney_address_bag: List[Address]

telecommunication_address_bag: List[Telecommunication]

to_dict()[source]

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(value)[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

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: Optional[str] = None

direction_category: Optional[DirectionCategory] = None

document_code: Optional[str] = None

document_code_description_text: Optional[str] = None

document_formats: List[DocumentFormat]

document_identifier: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[datetime] = None

to_dict()[source]

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)[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, ...]

__init__(documents)[source]

Initializes the DocumentBag with a list of documents.

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

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

classmethod from_dict(data)[source]

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

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

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: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

page_total_quantity: Optional[int] = None

to_dict()[source]

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)[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: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[bool] = None

to_dict()[source]

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

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: Optional[str] = None

event_date: Optional[date] = None

event_description_text: Optional[str] = None

classmethod from_dict(data)[source]

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

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

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: Optional[str] = None

filing_date: Optional[date] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

to_dict()[source]

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

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

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: Optional[str] = None

to_dict()[source]

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

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: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[date] = None

parent_application_number_text: Optional[str] = None

parent_application_status_code: Optional[int] = None

parent_application_status_description_text: Optional[str] = None

parent_patent_number: Optional[str] = None

to_dict()[source]

Converts the ParentContinuity instance to a dictionary.

Maps attributes to specific camelCase keys expected by the API for parent continuity.

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

class pyUSPTO.models.patent_data.PatentDataResponse(count, patent_file_wrapper_data_bag=<factory>, 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.

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

count: int

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

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: Optional[str] = None

to_csv()[source]

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

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

application_meta_data: Optional[ApplicationMetaData] = None

application_number_text: Optional[str] = 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)[source]

Creates a PatentFileWrapper instance from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with patent file wrapper data.
Returns:: An instance of PatentFileWrapper.
Return type:: PatentFileWrapper

grant_document_meta_data: Optional[PrintedMetaData] = None

last_ingestion_date_time: Optional[datetime] = None

parent_continuity_bag: List[ParentContinuity]

patent_term_adjustment_data: Optional[PatentTermAdjustmentData] = None

pgpub_document_meta_data: Optional[PrintedMetaData] = None

record_attorney: Optional[RecordAttorney] = None

to_dict()[source]

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, filing_date=None, grant_date=None, non_overlapping_day_quantity=None, overlapping_day_quantity=None, ip_office_day_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.

filing_date: The filing date of the application.

grant_date: The grant date of the patent.

non_overlapping_day_quantity: Number of non-overlapping delay days.

overlapping_day_quantity: Number of overlapping delay days.

ip_office_day_delay_quantity: Total days of delay attributable to the IP office.

patent_term_adjustment_history_data_bag: List of PatentTermAdjustmentHistoryData events.

a_delay_quantity: Optional[float] = None

adjustment_total_quantity: Optional[float] = None

applicant_day_delay_quantity: Optional[float] = None

b_delay_quantity: Optional[float] = None

c_delay_quantity: Optional[float] = None

filing_date: Optional[date] = None

classmethod from_dict(data)[source]

Creates a PatentTermAdjustmentData instance from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with PTA data.
Returns:: An instance of PatentTermAdjustmentData.
Return type:: PatentTermAdjustmentData

grant_date: Optional[date] = None

ip_office_day_delay_quantity: Optional[float] = None

non_overlapping_day_quantity: Optional[float] = None

overlapping_day_quantity: Optional[float] = None

patent_term_adjustment_history_data_bag: List[PatentTermAdjustmentHistoryData]

to_dict()[source]

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, ip_office_day_delay_quantity=None, originating_event_sequence_number=None, pta_pte_code=None)[source]

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.

ip_office_day_delay_quantity: Number of days of delay attributable to the IP office for this event.

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

applicant_day_delay_quantity: Optional[float] = None

event_date: Optional[date] = None

event_description_text: Optional[str] = None

event_sequence_number: Optional[float] = None

classmethod from_dict(data)[source]

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: Optional[float] = None

originating_event_sequence_number: Optional[float] = None

pta_pte_code: Optional[str] = None

to_dict()[source]

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)[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: Optional[str] = None

first_name: Optional[str] = None

last_name: Optional[str] = None

middle_name: Optional[str] = None

name_prefix: Optional[str] = None

name_suffix: Optional[str] = None

preferred_name: Optional[str] = None

to_dict()[source]

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)[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: Optional[datetime] = None

file_location_uri: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

to_dict()[source]

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: Optional[str] = None

zip_file_name: Optional[str] = None

class pyUSPTO.models.patent_data.PrintedPublication(pgpub_document_meta_data=None, grant_document_meta_data=None)[source]

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

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: Optional[PrintedMetaData] = None

pgpub_document_meta_data: Optional[PrintedMetaData] = None

to_dict()[source]

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=<factory>, 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: List of CustomerNumberCorrespondence objects.

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: List[CustomerNumberCorrespondence]

classmethod from_dict(data)[source]

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

Converts the RecordAttorney 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.StatusCode(code=None, description=None)[source]

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

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

Return type:: str

code: Optional[int] = None

description: Optional[str] = None

classmethod from_dict(data)[source]

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

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)[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, ...]

__init__(status_codes)[source]

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

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

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

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

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: Optional[str] = None

status_code_bag: StatusCodeCollection

to_dict()[source]

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

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: Optional[str] = None

classmethod from_dict(data)[source]

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: Optional[str] = None

telecommunication_number: Optional[str] = None

to_dict()[source]

Converts the Telecommunication instance to a dictionary.

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