Bulk Data

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: Datetime 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: datetime | None = None

file_download_uri: str | None = None

file_last_modified_date_time: datetime | None = None

file_name: str

file_release_date: datetime | 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(*values)[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(*values)[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'