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=<factory>, product_dataset_array_text=<factory>, product_dataset_category_array_text=<factory>, product_from_date=None, product_to_date=None, product_total_file_size=0, product_file_total_quantity=0, last_modified_date_time=None, mime_type_identifier_array_text=<factory>, product_file_bag=None, days_of_week_text=None, raw_data=None)[source]

Bases: object

Represent a product in the bulk data API.

product_identifier: Unique identifier for the product.

product_description_text: Description of the product.

product_title_text: Title of the product.

product_frequency_text: Update frequency description.

product_label_array_text: Labels associated with the product.

product_dataset_array_text: Datasets included in the product.

product_dataset_category_array_text: Categories of datasets.

product_from_date: Start date of data in the product.

product_to_date: End date of data in the product.

product_total_file_size: Total size of all files in bytes.

product_file_total_quantity: Number of files in the product.

last_modified_date_time: Last modification timestamp.

mime_type_identifier_array_text: MIME types of files in the product.

product_file_bag: Container with file data.

days_of_week_text: Days of the week for updates (if applicable).

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

days_of_week_text: str | None = None

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

Create a BulkDataProduct object from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing product data from API response.
include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of BulkDataProduct.

Return type:

BulkDataProduct

last_modified_date_time: datetime | None = None

mime_type_identifier_array_text: list[str]

product_dataset_array_text: list[str]

product_dataset_category_array_text: list[str]

product_description_text: str

product_file_bag: ProductFileBag | None = None

product_file_total_quantity: int = 0

product_frequency_text: str

product_from_date: date | None = None

product_identifier: str

product_label_array_text: list[str]

product_title_text: str

product_to_date: date | None = None

product_total_file_size: int = 0

raw_data: str | None = None

to_dict()[source]

Convert the BulkDataProduct object to a dictionary.

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

class pyUSPTO.models.bulk_data.BulkDataResponse(count, bulk_data_product_bag=<factory>, 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 and propagate to nested models.

Returns:

An instance of BulkDataResponse.

Return type:

BulkDataResponse

raw_data: str | None = None

to_dict()[source]

Convert the BulkDataResponse object to a dictionary.

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

class pyUSPTO.models.bulk_data.FileData(file_name, file_size, product_identifier, 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, raw_data=None)[source]

Bases: object

Represent a file in the bulk data API.

file_name: The name of the file.

file_size: Size of the file in bytes.

product_identifier: The identifier of the product this file belongs to.

file_data_from_date: Start date of data covered in the file.

file_data_to_date: End date of data covered in the file.

file_type_text: Description of the file type.

file_release_date: Date when the file was released.

file_download_uri: URL for downloading the file.

file_date: Additional file date information.

file_last_modified_date_time: Last modification timestamp.

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

file_data_from_date: date | None

file_data_to_date: date | None

file_date: date | None = None

file_download_uri: str | None = None

file_last_modified_date_time: datetime | None = None

file_name: str

file_release_date: date | None

file_size: int

file_type_text: str

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

Create a FileData object from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing file data from API response.
product_identifier (str) – The identifier of the product this file belongs to.
include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of FileData.

Return type:

FileData

product_identifier: str

raw_data: str | None = None

to_dict()[source]

Convert the FileData object to a dictionary.

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

class pyUSPTO.models.bulk_data.FileTypeCategory(value)[source]

Bases: Enum

File type categories in bulk data.

This enum provides type-safe representations of file types commonly found in USPTO bulk data products.

CSV = 'CSV'

JSON = 'JSON'

TAR = 'TAR'

TAR_GZ = 'TAR_GZ'

TGZ = 'TGZ'

XML = 'XML'

ZIP = 'ZIP'

class pyUSPTO.models.bulk_data.ProductFileBag(count, file_data_bag=<factory>, raw_data=None)[source]

Bases: object

Container for file data elements.

count: The number of files in the bag.

file_data_bag: List of FileData objects.

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

count: int

file_data_bag: list[FileData]

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

Create a ProductFileBag object from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing product file bag data.
product_identifier (str) – The identifier of the product this bag belongs to.
include_raw_data (bool) – If True, store the raw JSON for debugging.

Returns:

An instance of ProductFileBag.

Return type:

ProductFileBag

raw_data: str | None = None

to_dict()[source]

Convert the ProductFileBag object to a dictionary.

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

class pyUSPTO.models.bulk_data.ProductFrequency(value)[source]

Bases: Enum

Product update frequency categories.

Represents how often a bulk data product is updated.

AD_HOC = 'AD_HOC'

ANNUALLY = 'ANNUALLY'

DAILY = 'DAILY'

MONTHLY = 'MONTHLY'

QUARTERLY = 'QUARTERLY'

WEEKLY = 'WEEKLY'

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

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.

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(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

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

Bases: str, Enum

MIME types for document downloads from USPTO.

MS_WORD = 'MS_WORD'

PDF = 'PDF'

XML = 'XML'

__format__(format_spec): Returns format using actual value type unless __str__ has been overridden.

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.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)[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: ApplicationMetaData | None = None

application_number_text: str

assignment_bag: list[Assignment]

child_continuity_bag: list[ChildContinuity]

correspondence_address_bag: list[Address]

event_data_bag: list[EventData]

foreign_priority_bag: list[ForeignPriority]

classmethod from_dict(data, include_raw_data=False)[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:: Optional[StatusCode]

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

Create a StatusCodeSearchResponse instance from a dictionary.

Parameters:: data (Dict[str, Any]) – Dictionary with API response data for status codes.
Returns:: An instance of StatusCodeSearchResponse.
Return type:: StatusCodeSearchResponse

request_identifier: str | None = None

status_code_bag: StatusCodeCollection

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

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

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

class pyUSPTO.models.ptab.AdditionalPartyData(application_number_text=None, inventor_name=None, patent_number=None, additional_party_name=None)[source]

Bases: object

Additional party information in an interference.

application_number_text: Application number.

inventor_name: Name of inventor.

patent_number: Patent number.

additional_party_name: Name of additional party.

additional_party_name: str | None = None

application_number_text: str | None = None

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

Create an AdditionalPartyData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing additional party data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AdditionalPartyData.

Return type:

AdditionalPartyData

inventor_name: str | None = None

patent_number: str | None = None

to_dict()[source]

Convert the AdditionalPartyData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Appeal document metadata.

document_filing_date: Date the document was filed.

document_identifier: Unique identifier for the document.

document_name: Name of the document.

document_size_quantity: Size of the document in bytes.

document_ocr_text: Full OCR text of the document.

document_type_description_text: Description of the document type.

file_download_uri: URI to download the document.

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_type_description_text: str | None = None

file_download_uri: str | None = None

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

Create an AppealDocumentData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing document data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AppealDocumentData.

Return type:

AppealDocumentData

to_dict()[source]

Convert the AppealDocumentData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Appeal metadata.

appeal_filing_date: Date the appeal was filed.

appeal_last_modified_date: Last modification date.

appeal_last_modified_date_time: Last modification timestamp.

application_type_category: Type of application.

docket_notice_mailed_date: Date the docket notice was mailed.

file_download_uri: URI to download ZIP of appeal documents.

appeal_filing_date: date | None = None

appeal_last_modified_date: date | None = None

appeal_last_modified_date_time: datetime | None = None

application_type_category: str | None = None

docket_notice_mailed_date: date | None = None

file_download_uri: str | None = None

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

Create an AppealMetaData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing appeal metadata from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of AppealMetaData.

Return type:

AppealMetaData

to_dict()[source]

Convert the AppealMetaData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: PartyData

Appellant party data in PTAB appeals.

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

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

Bases: object

Appeal decision information.

appeal_outcome_category: Outcome of the appeal.

statute_and_rule_bag: List of applicable statutes and rules.

decision_issue_date: Date the decision was issued.

decision_type_category: Type of decision.

issue_type_bag: List of issue types.

appeal_outcome_category: str | None = None

decision_issue_date: date | None = None

decision_type_category: str | None = None

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

Create a DecisionData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing decision data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of DecisionData.

Return type:

DecisionData

issue_type_bag: list[str]

statute_and_rule_bag: list[str]

to_dict()[source]

Convert the DecisionData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: PartyData

Derivation petitioner data in derivation proceedings.

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

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

Bases: object

Interference document metadata.

document_identifier: Unique identifier for the document.

document_name: Name of the document.

document_size_quantity: Size of the document in bytes.

document_ocr_text: Full OCR text of the document.

document_title_text: Title of the document.

interference_outcome_category: Outcome of the interference.

document_filing_date: Date the document was filed.

decision_issue_date: Date the decision was issued.

decision_type_category: Type of decision.

file_download_uri: URI to download the document.

statute_and_rule_bag: List of applicable statutes and rules.

issue_type_bag: List of issues addressed.

decision_issue_date: date | None = None

decision_type_category: str | None = None

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_title_text: str | None = None

file_download_uri: str | None = None

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

Create an InterferenceDocumentData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing document data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of InterferenceDocumentData.

Return type:

InterferenceDocumentData

interference_outcome_category: str | None = None

issue_type_bag: list[str]

statute_and_rule_bag: list[str]

to_dict()[source]

Convert the InterferenceDocumentData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Interference metadata.

interference_style_name: Style name of the interference.

interference_last_modified_date: Last modification date.

interference_last_modified_date_time: Last modification datetime.

declaration_date: Declaration date.

file_download_uri: URI to download ZIP of interference documents.

declaration_date: date | None = None

file_download_uri: str | None = None

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

Create an InterferenceMetaData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing interference metadata from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of InterferenceMetaData.

Return type:

InterferenceMetaData

interference_last_modified_date: date | None = None

interference_last_modified_date_time: datetime | None = None

interference_style_name: str | None = None

to_dict()[source]

Convert the InterferenceMetaData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: PartyData

Junior party information in PTAB interference proceedings.

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

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

Bases: object

Individual PTAB appeal decision record.

appeal_number: Appeal number.

last_modified_date_time: Last modification timestamp.

appeal_document_category: Document category.

appeal_meta_data: Appeal metadata.

appellant_data: Appellant information.

requestor_data: Third party requestor information.

document_data: Document metadata.

decision_data: Decision information.

raw_data: Raw JSON response data (if include_raw_data=True).

appeal_document_category: str | None = None

appeal_meta_data: AppealMetaData | None = None

appeal_number: str | None = None

appellant_data: AppellantData | None = None

decision_data: DecisionData | None = None

document_data: AppealDocumentData | None = None

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

Create a PTABAppealDecision instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing appeal decision data from API response.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABAppealDecision.

Return type:

PTABAppealDecision

last_modified_date_time: datetime | None = None

raw_data: dict[str, Any] | None = None

requestor_data: RequestorData | None = None

to_dict()[source]

Convert the PTABAppealDecision instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Response container for PTAB appeals search.

count: Total number of matching results.

request_identifier: UUID for the API request.

patent_appeal_data_bag: List of appeal decisions.

raw_data: Raw JSON response data (if include_raw_data=True).

count: int = 0

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

Create a PTABAppealResponse instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing response data from API.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABAppealResponse.

Return type:

PTABAppealResponse

patent_appeal_data_bag: list[PTABAppealDecision]

raw_data: dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()[source]

Convert the PTABAppealResponse instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Individual PTAB interference decision record.

interference_number: Interference number.

last_modified_date_time: Last modification timestamp.

interference_meta_data: Interference metadata.

senior_party_data: Senior party information.

junior_party_data: Junior party information.

additional_party_data_bag: List of additional parties.

document_data: Document metadata.

raw_data: Raw JSON response data (if include_raw_data=True).

additional_party_data_bag: list[AdditionalPartyData]

document_data: InterferenceDocumentData | None = None

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

Create a PTABInterferenceDecision instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing interference decision data from API response.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABInterferenceDecision.

Return type:

PTABInterferenceDecision

interference_meta_data: InterferenceMetaData | None = None

interference_number: str | None = None

junior_party_data: JuniorPartyData | None = None

last_modified_date_time: datetime | None = None

raw_data: dict[str, Any] | None = None

senior_party_data: SeniorPartyData | None = None

to_dict()[source]

Convert the PTABInterferenceDecision instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Response container for PTAB interferences search.

count: Total number of matching results.

request_identifier: UUID for the API request.

patent_interference_data_bag: List of interference decisions.

raw_data: Raw JSON response data (if include_raw_data=True).

count: int = 0

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

Create a PTABInterferenceResponse instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing response data from API.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABInterferenceResponse.

Return type:

PTABInterferenceResponse

patent_interference_data_bag: list[PTABInterferenceDecision]

raw_data: dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()[source]

Convert the PTABInterferenceResponse instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

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

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

trial_document_category: Category (Document or Decision).

last_modified_date_time: Last modification timestamp.

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

trial_type_code: Type of trial (IPR, PGR, CBM, DER).

trial_meta_data: Trial metadata.

patent_owner_data: Patent owner information.

regular_petitioner_data: Regular petitioner information.

respondent_data: Respondent information.

derivation_petitioner_data: Derivation petitioner information.

document_data: Document metadata (if document).

decision_data: Decision information (if decision).

raw_data: Raw JSON response data (if include_raw_data=True).

decision_data: TrialDecisionData | None = None

derivation_petitioner_data: DerivationPetitionerData | None = None

document_data: TrialDocumentData | None = None

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

Create a PTABTrialDocument instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary with API response data containing PTAB trial document information.
include_raw_data (bool) – If True, includes the raw API response data in the instance.

Returns:

A new instance populated with data from the dictionary.

Return type:

PTABTrialDocument

last_modified_date_time: datetime | None = None

patent_owner_data: PatentOwnerData | None = None

raw_data: dict[str, Any] | None = None

regular_petitioner_data: RegularPetitionerData | None = None

respondent_data: RespondentData | None = None

to_dict()[source]

Convert the PTABTrialDocument instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

trial_document_category: str | None = None

trial_meta_data: TrialMetaData | None = None

trial_number: str | None = None

trial_type_code: str | None = None

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

Bases: object

Response container for PTAB trial documents/decisions search.

count: int = 0

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

Create a PTABTrialDocumentResponse instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary with API response data containing PTAB trial document response information.
include_raw_data (bool) – If True, includes the raw API response data in the instance.

Returns:

A new instance populated with data from the dictionary.

Return type:

PTABTrialDocumentResponse

patent_trial_document_data_bag: list[PTABTrialDocument]

raw_data: dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()[source]

Convert the PTABTrialDocumentResponse instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Individual PTAB trial proceeding record.

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

trial_record_identifier: UUID identifier for the trial record.

last_modified_date_time: Last modification timestamp.

trial_meta_data: Trial metadata.

patent_owner_data: Patent owner information.

regular_petitioner_data: Regular petitioner information.

respondent_data: Respondent information.

derivation_petitioner_data: Derivation petitioner information.

raw_data: Raw JSON response data (if include_raw_data=True).

derivation_petitioner_data: DerivationPetitionerData | None = None

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

Create a PTABTrialProceeding instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing trial proceeding data from API response.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABTrialProceeding.

Return type:

PTABTrialProceeding

last_modified_date_time: datetime | None = None

patent_owner_data: PatentOwnerData | None = None

raw_data: dict[str, Any] | None = None

regular_petitioner_data: RegularPetitionerData | None = None

respondent_data: RespondentData | None = None

to_dict()[source]

Convert the PTABTrialProceeding instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

trial_meta_data: TrialMetaData | None = None

trial_number: str | None = None

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

Bases: object

Response container for PTAB trial proceedings search.

count: Total number of matching results.

request_identifier: UUID for the API request.

patent_trial_proceeding_data_bag: List of trial proceedings.

raw_data: Raw JSON response data (if include_raw_data=True).

count: int = 0

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

Create a PTABTrialProceedingResponse instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing response data from API.
include_raw_data (bool) – Whether to include raw JSON data in the instance.

Returns:

An instance of PTABTrialProceedingResponse.

Return type:

PTABTrialProceedingResponse

patent_trial_proceeding_data_bag: list[PTABTrialProceeding]

raw_data: dict[str, Any] | None = None

request_identifier: str | None = None

to_dict()[source]

Convert the PTABTrialProceedingResponse instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: PartyData

Party data for a patent owner in PTAB trial proceedings.

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

class pyUSPTO.models.ptab.RegularPetitionerData(counsel_name=None, real_party_in_interest_name=None)[source]

Bases: object

Regular petitioner information.

counsel_name: Name of counsel.

real_party_in_interest_name: Real party in interest name.

counsel_name: str | None = None

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

Create a RegularPetitionerData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing petitioner data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of RegularPetitionerData.

Return type:

RegularPetitionerData

real_party_in_interest_name: str | None = None

to_dict()[source]

Convert the RegularPetitionerData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

class pyUSPTO.models.ptab.RequestorData(third_party_name=None)[source]

Bases: object

Third party requestor information.

third_party_name: Name of the third party.

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

Create a RequestorData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing requestor data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of RequestorData.

Return type:

RequestorData

third_party_name: str | None = None

to_dict()[source]

Convert the RequestorData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: PartyData

Respondent party data in derivation proceedings.

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

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

Bases: PartyData

Senior party information in PTAB interference proceedings.

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

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

Bases: object

Metadata for a decision in a PTAB trial.

statute_and_rule_bag: List of applicable statutes and rules.

decision_issue_date: Date issued.

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

issue_type_bag: List of issues addressed.

trial_outcome_category: Outcome (e.g., “Denied”).

decision_issue_date: date | None = None

decision_type_category: str | None = None

classmethod from_dict(data)[source]

Create a TrialDecisionData instance from a dictionary.

Parameters:: data (dict[str, Any]) – Dictionary with API response data containing trial decision information.
Returns:: A new instance populated with data from the dictionary.
Return type:: TrialDecisionData

issue_type_bag: list[str]

statute_and_rule_bag: list[str]

to_dict()[source]

Convert the TrialDecisionData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

trial_outcome_category: str | None = None

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

Bases: object

Metadata for a document in a PTAB trial.

document_category: Category of the document.

document_filing_date: Filing date.

document_identifier: Unique ID.

document_name: Filename.

document_number: Document number in the proceeding.

document_size_quantity: Size in bytes.

document_ocr_text: OCR text content.

document_title_text: Title of the document.

document_type_description_text: Description of document type.

file_download_uri: URL to download the file.

filing_party_category: Who filed (e.g., “Petitioner”).

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

document_status: Public status.

document_category: str | None = None

document_filing_date: date | None = None

document_identifier: str | None = None

document_name: str | None = None

document_number: str | None = None

document_ocr_text: str | None = None

document_size_quantity: int | None = None

document_title_text: str | None = None

document_type_description_text: str | None = None

file_download_uri: str | None = None

filing_party_category: str | None = None

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

Create a TrialDocumentData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing document data from API response.
include_raw_data (bool) – Ignored for this model.

Returns:

An instance of TrialDocumentData.

Return type:

TrialDocumentData

to_dict()[source]

Convert the TrialDocumentData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

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

Bases: object

Trial metadata including status, dates, and download URI.

petition_filing_date: Date the petition was filed.

accorded_filing_date: The filing date accorded to the petition.

trial_last_modified_date_time: Last modification timestamp.

trial_last_modified_date: Last modification date.

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

trial_type_code: Type of trial (IPR, PGR, CBM, DER).

file_download_uri: URI to download ZIP of all trial documents.

termination_date: Date the trial was terminated.

latest_decision_date: Date of the most recent decision.

institution_decision_date: Date of the institution decision.

accorded_filing_date: date | None = None

file_download_uri: str | None = None

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

Create a TrialMetaData instance from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing trial metadata from API response.
include_raw_data (bool) – Ignored for this model (no raw_data field).

Returns:

An instance of TrialMetaData.

Return type:

TrialMetaData

institution_decision_date: date | None = None

latest_decision_date: date | None = None

petition_filing_date: date | None = None

termination_date: date | None = None

to_dict()[source]

Convert the TrialMetaData instance to a dictionary.

Returns:: Dictionary with camelCase keys and None values filtered.
Return type:: Dict[str, Any]

trial_last_modified_date: date | None = None

trial_last_modified_date_time: datetime | None = None

trial_status_category: str | None = None

trial_type_code: str | None = None

models.utils - Utility functions for USPTO data models.

This module provides utility functions for parsing, serializing, and converting data used across USPTO API data models. These utilities handle date/datetime conversions, boolean string representations, and string transformations.

pyUSPTO.models.utils.parse_to_date(date_str, fmt='%Y-%m-%d')[source]

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

Parameters:

date_str (Optional[str]) – The string to parse as a date.
fmt (str, optional) – The expected strptime format string for parsing the date. Defaults to “%Y-%m-%d”.

Returns:

A date object if parsing is successful and date_str: is not None. Returns None if date_str is None or if parsing fails.

Return type:

Optional[date]

Warns:

USPTODateParseWarning – If the date string cannot be parsed.

pyUSPTO.models.utils.parse_to_datetime_utc(datetime_str)[source]

Parse a string representation of a datetime into a UTC datetime object.

Attempts to parse ISO format strings. If the input string contains timezone information, it’s used. If the string is a naive datetime (no timezone), it’s assumed to be in the ASSUMED_NAIVE_TIMEZONE_STR (e.g., “America/New_York”) and then converted to UTC.

Parameters:

datetime_str (Optional[str]) – The string to parse as a datetime. Supports ISO 8601 format, including those ending with “Z”.

Returns:

A timezone-aware datetime object in UTC if parsing: is successful and datetime_str is not None. Returns None if datetime_str is None or if parsing/conversion fails.

Return type:

Optional[datetime]

Warns:

USPTODateParseWarning – If the datetime string cannot be parsed.
USPTOTimezoneWarning – If timezone localization fails.

pyUSPTO.models.utils.parse_yn_to_bool(value)[source]

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

Parameters:

value (Optional[str]) – The string value to convert. Expected to be ‘Y’, ‘y’, ‘N’, or ‘n’.

Returns:

True if value is ‘Y’ or ‘y’, False if value is: ’N’ or ‘n’. Returns None if value is None or any other string.

Return type:

Optional[bool]

Warns:

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

pyUSPTO.models.utils.serialize_bool_to_yn(value)[source]

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

Parameters:

value (Optional[bool]) – The boolean value to convert.

Returns:

“Y” if value is True, “N” if value is False.: Returns None if value is None.

Return type:

Optional[str]

pyUSPTO.models.utils.serialize_date(d)[source]

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

Parameters:

d (Optional[date]) – The date object to serialize.

Returns:

The date as an ISO 8601 formatted string, or None: if the input is None.

Return type:

Optional[str]

pyUSPTO.models.utils.serialize_datetime_as_iso(dt)[source]

Serialize a datetime object to a local-timezone ISO 8601 string.

If the input datetime object is timezone-aware, it is converted to the assumed local timezone defined by ASSUMED_NAIVE_TIMEZONE. If it is naive (lacks timezone information), it is first assigned that assumed local timezone.

The resulting datetime is formatted as:: YYYY-MM-DDTHH:MM:SS.000±HHMM

(e.g., “2024-12-10T00:00:00.000-0500”)

Parameters:

dt (Optional[datetime]) – The datetime object to serialize. Can be naive or timezone-aware.

Returns:

The datetime formatted in the assumed local timezone,: or None if the input dt is None.

Return type:

Optional[str]

pyUSPTO.models.utils.serialize_datetime_as_naive(dt)[source]

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

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

Parameters:: dt (datetime) – The datetime object to serialize.
Returns:: ISO formatted datetime string without timezone information.
Return type:: str

pyUSPTO.models.utils.to_camel_case(snake_str)[source]

Convert a snake_case string to lowerCamelCase.

For example, “example_snake_string” becomes “exampleSnakeString”.

Parameters:: snake_str (str) – The input string in snake_case.
Returns:: The converted string in lowerCamelCase.
Return type:: str