Models — pyUSPTO 0.2.3.dev1+g2c5d89b38.d20251125 documentation

# Models

models.bulk_data - Data models for USPTO bulk data API

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

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

  Bases: `object`

  Represents a product in the bulk data API.

  days_of_week_text: `str` | `None` = None
  classmethod from_dict(data)

    Create a BulkDataProduct object from a dictionary.

    Return type:

      `BulkDataProduct`

  last_modified_date_time: `str`
  mime_type_identifier_array_text: `List`[`str`]
  product_dataset_array_text: `List`[`str`]
  product_dataset_category_array_text: `List`[`str`]
  product_description_text: `str`
  product_file_bag: `ProductFileBag` | `None` = None
  product_file_total_quantity: `int`
  product_frequency_text: `str`
  product_from_date: `str`
  product_identifier: `str`
  product_label_array_text: `List`[`str`]
  product_title_text: `str`
  product_to_date: `str`
  product_total_file_size: `int`

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

  Bases: `object`

  Top-level response from the bulk data API.

  count

    The number of bulk data products in the response.

  bulk_data_product_bag

    List of bulk data products.

  raw_data

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

  bulk_data_product_bag: `List`[`BulkDataProduct`]
  count: `int`
  classmethod from_dict(data, include_raw_data=False)

    Create a BulkDataResponse object from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of BulkDataResponse.

    Return type:

      BulkDataResponse

  raw_data: `str` | `None` = None
  to_dict()

    Convert the BulkDataResponse object to a dictionary.

    Return type:

      `Dict`[`str`, `Any`]

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

  Bases: `object`

  Represents a file in the bulk data API.

  file_data_from_date: `str`
  file_data_to_date: `str`
  file_date: `str` | `None` = None
  file_download_uri: `str` | `None` = None
  file_last_modified_date_time: `str` | `None` = None
  file_name: `str`
  file_release_date: `str`
  file_size: `int`
  file_type_text: `str`
  classmethod from_dict(data)

    Create a FileData object from a dictionary.

    Return type:

      `FileData`

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

  Bases: `object`

  Container for file data elements.

  count: `int`
  file_data_bag: `List`[`FileData`]
  classmethod from_dict(data)

    Create a ProductFileBag object from a dictionary.

    Return type:

      `ProductFileBag`

models.patent_data - Data models for USPTO patent data API

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

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

  Bases: `Enum`

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

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

  ACTIVE = 'Active'
  FALSE = 'false'
  NO = 'N'
  TRUE = 'true'
  YES = 'Y'

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

  Bases: `object`

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

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

  name_line_one_text

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

  name_line_two_text

    Second line of the name.

  address_line_one_text

    First line of the street address.

  address_line_two_text

    Second line of the street address.

  address_line_three_text

    Third line of the street address.

  address_line_four_text

    Fourth line of the street address.

  geographic_region_name

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

  geographic_region_code

    Code for the geographic region.

  postal_code

    Postal or ZIP code.

  city_name

    Name of the city.

  country_code

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

  country_name

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

  postal_address_category

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

  correspondent_name_text

    Name of the correspondent at this address.

  country_or_state_code

    Country or state code.

  ict_state_code

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

  ict_country_code

    International code for the country (USPTO format).

  address_line_four_text: `str` | `None` = None
  address_line_one_text: `str` | `None` = None
  address_line_three_text: `str` | `None` = None
  address_line_two_text: `str` | `None` = None
  city_name: `str` | `None` = None
  correspondent_name_text: `str` | `None` = None
  country_code: `str` | `None` = None
  country_name: `str` | `None` = None
  country_or_state_code: `str` | `None` = None
  classmethod from_dict(data)

    Creates an Address instance from a dictionary representation.

    Maps camelCase keys from API data to class attributes.

    Parameters:

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

    Returns:

      An instance of Address.

    Return type:

      Address

  geographic_region_code: `str` | `None` = None
  geographic_region_name: `str` | `None` = None
  ict_country_code: `str` | `None` = None
  ict_state_code: `str` | `None` = None
  name_line_one_text: `str` | `None` = None
  name_line_two_text: `str` | `None` = None
  postal_address_category: `str` | `None` = None
  postal_code: `str` | `None` = None
  to_dict()

    Converts the Address instance to a dictionary with camelCase keys.

    Returns:

      A dictionary representation of the address.

    Return type:

      Dict[str, Any]

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

  Bases: `Person`

  Represents an applicant for a patent, inheriting from Person.

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

  applicant_name_text

    The full name of the applicant as a single string.

  correspondence_address_bag

    A list of Address objects for the applicant.

  applicant_name_text: `str` | `None` = None
  correspondence_address_bag: `List`[`Address`]
  classmethod from_dict(data)

    Creates an Applicant instance from a dictionary.

    Inherits person fields and adds applicant-specific fields.

    Parameters:

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

    Returns:

      An instance of Applicant.

    Return type:

      Applicant

  to_dict()

    Converts the Applicant instance to a dictionary.

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

    Returns:

      Dictionary representation of the applicant.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  parent_continuity_bag

    List of ParentContinuity objects.

  child_continuity_bag

    List of ChildContinuity objects.

  child_continuity_bag: `List`[`ChildContinuity`]
  classmethod from_wrapper(wrapper)

    Creates an ApplicationContinuityData instance from a PatentFileWrapper.

    Extracts parent and child continuity bags from the wrapper.

    Parameters:

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

    Returns:

      An instance of ApplicationContinuityData.

    Return type:

      ApplicationContinuityData

  parent_continuity_bag: `List`[`ParentContinuity`]
  to_dict()

    Converts the ApplicationContinuityData instance to a dictionary.

    Returns:

      Dictionary representation with “parentContinuityBag”

        and “childContinuityBag” keys.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents the metadata associated with a patent application.

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

  national_stage_indicator

    Indicates if the application is a national stage entry.

  entity_status_data

    EntityStatus object detailing applicant’s entity status.

  publication_date_bag

    List of publication dates.

  publication_sequence_number_bag

    List of publication sequence numbers.

  publication_category_bag

    List of publication categories.

  docket_number

    Applicant’s or attorney’s docket number.

  first_inventor_to_file_indicator

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

  first_applicant_name

    Name of the first listed applicant.

  first_inventor_name

    Name of the first listed inventor.

  application_confirmation_number

    USPTO confirmation number for the application.

  application_status_date

    Date the current application status was set.

  application_status_description_text

    Textual description of the current application status.

  filing_date

    Official filing date of the application.

  effective_filing_date

    Effective filing date, considering priority claims.

  grant_date

    Date the patent was granted, if applicable.

  group_art_unit_number

    USPTO Group Art Unit number.

  application_type_code

    Code for the application type.

  application_type_label_name

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

  application_type_category

    Category of the application type.

  invention_title

    Title of the invention.

  patent_number

    USPTO patent number, if granted.

  application_status_code

    Numeric code for the application status.

  earliest_publication_number

    Number of the earliest pre-grant publication.

  earliest_publication_date

    Date of the earliest pre-grant publication.

  pct_publication_number

    PCT publication number, if applicable.

  pct_publication_date

    PCT publication date, if applicable.

  international_registration_publication_date

    Date of international registration publication.

  international_registration_number

    International registration number.

  examiner_name_text

    Name of the patent examiner.

  class_field

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

  subclass

    USPC subclass.

  uspc_symbol_text

    Full USPC classification symbol.

  customer_number

    USPTO customer number associated with the application.

  cpc_classification_bag

    List of CPC classification symbols.

  applicant_bag

    List of Applicant objects.

  inventor_bag

    List of Inventor objects.

  raw_data

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

  applicant_bag: `List`[`Applicant`]
  application_confirmation_number: `int` | `None` = None
  application_status_code: `int` | `None` = None
  application_status_date: `date` | `None` = None
  application_status_description_text: `str` | `None` = None
  application_type_category: `str` | `None` = None
  application_type_code: `str` | `None` = None
  application_type_label_name: `str` | `None` = None
  class_field: `str` | `None` = None
  cpc_classification_bag: `List`[`str`]
  customer_number: `int` | `None` = None
  docket_number: `str` | `None` = None
  earliest_publication_date: `date` | `None` = None
  earliest_publication_number: `str` | `None` = None
  effective_filing_date: `date` | `None` = None
  entity_status_data: `EntityStatus` | `None` = None
  examiner_name_text: `str` | `None` = None
  filing_date: `date` | `None` = None
  first_applicant_name: `str` | `None` = None
  first_inventor_name: `str` | `None` = None
  first_inventor_to_file_indicator: `bool` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an ApplicationMetaData instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of ApplicationMetaData.

    Return type:

      ApplicationMetaData

  grant_date: `date` | `None` = None
  group_art_unit_number: `str` | `None` = None
  international_registration_number: `str` | `None` = None
  international_registration_publication_date: `date` | `None` = None
  invention_title: `str` | `None` = None
  inventor_bag: `List`[`Inventor`]
  property is_aia: bool | None

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

  property is_pre_aia: bool | None

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

  national_stage_indicator: `bool` | `None` = None
  patent_number: `str` | `None` = None
  pct_publication_date: `date` | `None` = None
  pct_publication_number: `str` | `None` = None
  publication_category_bag: `List`[`str`]
  publication_date_bag: `List`[`date`]
  publication_sequence_number_bag: `List`[`str`]
  raw_data: `str` | `None` = None
  subclass: `str` | `None` = None
  to_dict()

    Converts the ApplicationMetaData instance to a dictionary.

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

    Returns:

      Dictionary representation of the application metadata.

    Return type:

      Dict[str, Any]

  uspc_symbol_text: `str` | `None` = None

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

  Bases: `object`

  Represents an assignee in a patent assignment.

  assignee_name_text

    The name of the party receiving the assignment.

  assignee_address

    The Address of the assignee.

  assignee_address: `Address` | `None` = None
  assignee_name_text: `str` | `None` = None
  classmethod from_dict(data)

    Creates an Assignee instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of Assignee.

    Return type:

      Assignee

  to_dict()

    Converts the Assignee instance to a dictionary.

    Omits keys with None values.

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents a patent assignment, detailing the transfer of rights.

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

  reel_number

    Reel number for the assignment record.

  frame_number

    Frame number for the assignment record.

  reel_and_frame_number

    Combined reel and frame number.

  page_total_quantity

    Total number of pages in the assignment document.

  assignment_document_location_uri

    URI for the assignment document.

  assignment_received_date

    Date the assignment was received by USPTO.

  assignment_recorded_date

    Date the assignment was recorded by USPTO.

  assignment_mailed_date

    Date the assignment notification was mailed.

  conveyance_text

    Text describing the nature of the conveyance.

  image_available_status_code

    Code to indicate the availability of the image.

  attorney_docket_number

    Attorney docket number for the assignment.

  assignor_bag

    List of Assignor objects.

  assignee_bag

    List of Assignee objects.

  correspondence_address

    Address object for correspondence (single object).

  domestic_representative

    Address object for the domestic representative.

  assignee_bag: `List`[`Assignee`]
  assignment_document_location_uri: `str` | `None` = None
  assignment_mailed_date: `date` | `None` = None
  assignment_received_date: `date` | `None` = None
  assignment_recorded_date: `date` | `None` = None
  assignor_bag: `List`[`Assignor`]
  attorney_docket_number: `str` | `None` = None
  conveyance_text: `str` | `None` = None
  correspondence_address: `Address` | `None` = None
  domestic_representative: `Address` | `None` = None
  frame_number: `int` | `None` = None
  classmethod from_dict(data)

    Creates an Assignment instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of Assignment.

    Return type:

      Assignment

  image_available_status_code: `bool` | `None` = None
  page_total_quantity: `int` | `None` = None
  reel_and_frame_number: `str` | `None` = None
  reel_number: `int` | `None` = None
  to_dict()

    Converts the Assignment instance to a dictionary.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents an assignor in a patent assignment.

  assignor_name

    The name of the assigning party.

  execution_date

    The date the assignment was executed.

  assignor_name: `str` | `None` = None
  execution_date: `date` | `None` = None
  classmethod from_dict(data)

    Creates an Assignor instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of Assignor.

    Return type:

      Assignor

  to_dict()

    Converts the Assignor instance to a dictionary.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

  Bases: `Person`

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

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

  registration_number

    The attorney’s USPTO registration number.

  active_indicator

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

  registered_practitioner_category

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

  attorney_address_bag

    List of Address objects for the attorney.

  telecommunication_address_bag

    List of Telecommunication objects for the attorney.

  active_indicator: `str` | `None` = None
  attorney_address_bag: `List`[`Address`]
  classmethod from_dict(data)

    Creates an Attorney instance from a dictionary.

    Inherits person fields and adds attorney-specific details.

    Parameters:

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

    Returns:

      An instance of Attorney.

    Return type:

      Attorney

  registered_practitioner_category: `str` | `None` = None
  registration_number: `str` | `None` = None
  telecommunication_address_bag: `List`[`Telecommunication`]
  to_dict()

    Converts the Attorney instance to a dictionary.

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

    Returns:

      Dictionary representation of the attorney.

    Return type:

      Dict[str, Any]

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

  Bases: `Continuity`

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

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

  child_application_status_code

    Status code of the child application.

  parent_application_number_text

    Application number of the parent (current) application.

  child_application_number_text

    Application number of the child application.

  child_application_status_description_text

    Status description of the child application.

  child_application_filing_date

    Filing date of the child application.

  child_patent_number

    Patent number of the child application, if granted.

  child_application_filing_date: `date` | `None` = None
  child_application_number_text: `str` | `None` = None
  child_application_status_code: `int` | `None` = None
  child_application_status_description_text: `str` | `None` = None
  child_patent_number: `str` | `None` = None
  classmethod from_dict(data)

    Creates a ChildContinuity instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of ChildContinuity.

    Return type:

      ChildContinuity

  parent_application_number_text: `str` | `None` = None
  to_dict()

    Converts the ChildContinuity instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Base class representing continuity data for a patent application.

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

  first_inventor_to_file_indicator

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

  application_number_text

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

  filing_date

    The filing date of the related application.

  status_code

    The status code of the related application.

  status_description_text

    The status description of the related application.

  patent_number

    The patent number if the related application is granted.

  claim_parentage_type_code

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

  claim_parentage_type_code_description_text

    Description of the continuity claim type.

  application_number_text: `str` | `None` = None
  claim_parentage_type_code: `str` | `None` = None
  claim_parentage_type_code_description_text: `str` | `None` = None
  filing_date: `date` | `None` = None
  first_inventor_to_file_indicator: `bool` | `None` = None
  property is_aia: bool | None

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

  property is_pre_aia: bool | None

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

  patent_number: `str` | `None` = None
  status_code: `int` | `None` = None
  status_description_text: `str` | `None` = None
  to_dict()

    Converts the Continuity instance to a dictionary.

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

    Returns:

      A dictionary representation of the continuity data.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents correspondence data associated with a USPTO customer number.

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

  patron_identifier

    The USPTO customer number.

  organization_standard_name

    The name of the organization associated with the customer number.

  power_of_attorney_address_bag

    List of Address objects for power of attorney.

  telecommunication_address_bag

    List of Telecommunication objects.

  classmethod from_dict(data)

    Creates a CustomerNumberCorrespondence instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of CustomerNumberCorrespondence.

    Return type:

      CustomerNumberCorrespondence

  organization_standard_name: `str` | `None` = None
  patron_identifier: `int` | `None` = None
  power_of_attorney_address_bag: `List`[`Address`]
  telecommunication_address_bag: `List`[`Telecommunication`]
  to_dict()

    Converts the CustomerNumberCorrespondence instance to a dictionary.

    Omits keys with None values or empty lists.

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `Enum`

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

  INCOMING = 'INCOMING'
  OUTGOING = 'OUTGOING'

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

  Bases: `object`

  Represents a single document associated with a patent application.

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

  application_number_text

    The application number this document belongs to.

  official_date

    The official date of the document.

  document_identifier

    A unique identifier for this document.

  document_code

    A code representing the type of document.

  document_code_description_text

    A textual description of the document code.

  direction_category

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

  document_formats

    A list of available download formats for this document.

  application_number_text: `str` | `None` = None
  direction_category: `DirectionCategory` | `None` = None
  document_code: `str` | `None` = None
  document_code_description_text: `str` | `None` = None
  document_formats: `List`[`DocumentFormat`]
  document_identifier: `str` | `None` = None
  classmethod from_dict(data)

    Creates a Document instance from a dictionary representation.

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

    Parameters:

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

    Returns:

      An instance of Document.

    Return type:

      Document

  official_date: `datetime` | `None` = None
  to_dict()

    Converts the Document instance to a dictionary for API compatibility.

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

    Returns:

      A dictionary representation of the Document.

    Return type:

      Dict[str, Any]

class pyUSPTO.models.patent_data.DocumentBag(documents)

  Bases: `object`

  A collection of Document objects associated with a patent application.

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

  documents

    An immutable tuple of Document objects.

    Type:

      `tuple[Document`, `]`

  __init__(documents)

    Initializes the DocumentBag with a list of documents.

    Parameters:

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

  __repr__()

    Returns a detailed string representation for debugging.

    Returns:

      Detailed representation of the DocumentBag.

    Return type:

      str

  __str__()

    Returns a string representation showing document count and summary.

    Returns:

      Human-readable summary of the DocumentBag.

    Return type:

      str

  property documents: tuple[Document, ...]

    Provides access to the tuple of documents.

  classmethod from_dict(data)

    Creates a DocumentBag instance from a dictionary representation.

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

    Parameters:

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

    Returns:

      An instance of DocumentBag.

    Return type:

      DocumentBag

  to_dict()

    Converts the DocumentBag instance to a dictionary.

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

    Returns:

      A dictionary representation of the DocumentBag.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents an available download format for a specific document.

  mime_type_identifier

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

  download_url

    The URL from which the document format can be downloaded.

  page_total_quantity

    The total number of pages in this document format.

  download_url: `str` | `None` = None
  classmethod from_dict(data)

    Creates a DocumentFormat instance from a dictionary representation.

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

    Parameters:

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

    Returns:

      An instance of DocumentFormat initialized with

        data from the input dictionary.

    Return type:

      DocumentFormat

  mime_type_identifier: `str` | `None` = None
  page_total_quantity: `int` | `None` = None
  to_dict()

    Converts the DocumentFormat instance to a dictionary.

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

    Returns:

      A dictionary representation of the DocumentFormat

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

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

  small_entity_status_indicator

    Boolean indicating if the applicant qualifies for small entity status.

  business_entity_status_category

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

  business_entity_status_category: `str` | `None` = None
  classmethod from_dict(data)

    Creates an EntityStatus instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of EntityStatus.

    Return type:

      EntityStatus

  small_entity_status_indicator: `bool` | `None` = None
  to_dict()

    Converts the EntityStatus instance to a dictionary.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

  event_code

    A code identifying the type of event.

  event_description_text

    A textual description of the event.

  event_date

    The date the event was recorded.

  event_code: `str` | `None` = None
  event_date: `date` | `None` = None
  event_description_text: `str` | `None` = None
  classmethod from_dict(data)

    Creates an EventData instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of EventData.

    Return type:

      EventData

  to_dict()

    Converts the EventData instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents a foreign priority claim for a patent application.

  ip_office_name

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

  filing_date

    The filing date of the priority application.

  application_number_text

    The application number of the priority application.

  application_number_text: `str` | `None` = None
  filing_date: `date` | `None` = None
  classmethod from_dict(data)

    Creates a ForeignPriority instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of ForeignPriority.

    Return type:

      ForeignPriority

  ip_office_name: `str` | `None` = None
  to_dict()

    Converts the ForeignPriority instance to a dictionary.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

  Bases: `Person`

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

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

  inventor_name_text

    The full name of the inventor as a single string.

  correspondence_address_bag

    A list of Address objects for the inventor.

  correspondence_address_bag: `List`[`Address`]
  classmethod from_dict(data)

    Creates an Inventor instance from a dictionary.

    Inherits person fields and adds inventor-specific fields.

    Parameters:

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

    Returns:

      An instance of Inventor.

    Return type:

      Inventor

  inventor_name_text: `str` | `None` = None
  to_dict()

    Converts the Inventor instance to a dictionary.

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

    Returns:

      Dictionary representation of the inventor.

    Return type:

      Dict[str, Any]

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

  Bases: `Continuity`

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

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

  parent_application_status_code

    Status code of the parent application.

  parent_patent_number

    Patent number of the parent application, if granted.

  parent_application_status_description_text

    Status description of the parent application.

  parent_application_filing_date

    Filing date of the parent application.

  parent_application_number_text

    Application number of the parent application.

  child_application_number_text

    Application number of the child (current) application.

  child_application_number_text: `str` | `None` = None
  classmethod from_dict(data)

    Creates a ParentContinuity instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of ParentContinuity.

    Return type:

      ParentContinuity

  parent_application_filing_date: `date` | `None` = None
  parent_application_number_text: `str` | `None` = None
  parent_application_status_code: `int` | `None` = None
  parent_application_status_description_text: `str` | `None` = None
  parent_patent_number: `str` | `None` = None
  to_dict()

    Converts the ParentContinuity instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents the overall response from a patent data API request.

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

  count

    The total number of patent applications found matching the query.

  patent_file_wrapper_data_bag

    A list of PatentFileWrapper objects.

  request_identifier

    An identifier for the API request, if provided.

  raw_data

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

  count: `int`
  classmethod from_dict(data, include_raw_data=False)

    Creates a PatentDataResponse instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PatentDataResponse.

    Return type:

      PatentDataResponse

  patent_file_wrapper_data_bag: `List`[`PatentFileWrapper`]
  raw_data: `str` | `None` = None
  request_identifier: `str` | `None` = None
  to_csv()

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

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

    Returns:

      A string containing the data in CSV format.

    Return type:

      str

  to_dict()

    Converts the PatentDataResponse instance to a dictionary.

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents the complete file wrapper for a single patent application.

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

  application_number_text

    The primary application number.

  application_meta_data

    Comprehensive ApplicationMetaData.

  correspondence_address_bag

    List of Address objects for correspondence.

  assignment_bag

    List of Assignment records.

  record_attorney

    Information about the RecordAttorney.

  foreign_priority_bag

    List of ForeignPriority claims.

  parent_continuity_bag

    List of ParentContinuity records.

  child_continuity_bag

    List of ChildContinuity records.

  patent_term_adjustment_data

    PatentTermAdjustmentData details.

  event_data_bag

    List of EventData (transaction history).

  pgpub_document_meta_data

    PrintedMetaData for Pre-Grant Publication.

  grant_document_meta_data

    PrintedMetaData for the granted patent.

  last_ingestion_date_time

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

  application_meta_data: `ApplicationMetaData` | `None` = None
  application_number_text: `str` | `None` = None
  assignment_bag: `List`[`Assignment`]
  child_continuity_bag: `List`[`ChildContinuity`]
  correspondence_address_bag: `List`[`Address`]
  event_data_bag: `List`[`EventData`]
  foreign_priority_bag: `List`[`ForeignPriority`]
  classmethod from_dict(data, include_raw_data=False)

    Creates a PatentFileWrapper instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PatentFileWrapper.

    Return type:

      PatentFileWrapper

  grant_document_meta_data: `PrintedMetaData` | `None` = None
  last_ingestion_date_time: `datetime` | `None` = None
  parent_continuity_bag: `List`[`ParentContinuity`]
  patent_term_adjustment_data: `PatentTermAdjustmentData` | `None` = None
  pgpub_document_meta_data: `PrintedMetaData` | `None` = None
  record_attorney: `RecordAttorney` | `None` = None
  to_dict()

    Converts the PatentFileWrapper instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  a_delay_quantity

    Number of days of ‘A’ delay.

  adjustment_total_quantity

    Total calculated PTA in days.

  applicant_day_delay_quantity

    Total days of delay attributable to the applicant.

  b_delay_quantity

    Number of days of ‘B’ delay.

  c_delay_quantity

    Number of days of ‘C’ delay.

  non_overlapping_day_quantity

    Number of non-overlapping delay days.

  overlapping_day_quantity

    Number of overlapping delay days.

  non_overlapping_day_delay_quantity

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

  ip_office_adjustment_delay_quantity

    Days of IP office delay used in adjustment calculation.

  patent_term_adjustment_history_data_bag

    List of PatentTermAdjustmentHistoryData events.

  a_delay_quantity: `float` | `None` = None
  adjustment_total_quantity: `float` | `None` = None
  applicant_day_delay_quantity: `float` | `None` = None
  b_delay_quantity: `float` | `None` = None
  c_delay_quantity: `float` | `None` = None
  classmethod from_dict(data)

    Creates a PatentTermAdjustmentData instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of PatentTermAdjustmentData.

    Return type:

      PatentTermAdjustmentData

  ip_office_adjustment_delay_quantity: `float` | `None` = None
  non_overlapping_day_delay_quantity: `float` | `None` = None
  non_overlapping_day_quantity: `float` | `None` = None
  overlapping_day_quantity: `float` | `None` = None
  patent_term_adjustment_history_data_bag: `List`[`PatentTermAdjustmentHistoryData`]
  to_dict()

    Converts the PatentTermAdjustmentData instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  event_date

    Date of the PTA event.

  applicant_day_delay_quantity

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

  event_description_text

    Textual description of the PTA event.

  event_sequence_number

    Sequence number of this event in the PTA history.

  originating_event_sequence_number

    Sequence number of an event that originated this event.

  pta_pte_code

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

  ip_office_day_delay_quantity

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

  applicant_day_delay_quantity: `float` | `None` = None
  event_date: `date` | `None` = None
  event_description_text: `str` | `None` = None
  event_sequence_number: `float` | `None` = None
  classmethod from_dict(data)

    Creates a PatentTermAdjustmentHistoryData instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of PatentTermAdjustmentHistoryData.

    Return type:

      PatentTermAdjustmentHistoryData

  ip_office_day_delay_quantity: `float` | `None` = None
  originating_event_sequence_number: `float` | `None` = None
  pta_pte_code: `str` | `None` = None
  to_dict()

    Converts the PatentTermAdjustmentHistoryData instance to a dictionary.

    Omits keys with None values.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  first_name

    The first name of the person.

  middle_name

    The middle name or initial of the person.

  last_name

    The last name or surname of the person.

  name_prefix

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

  name_suffix

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

  preferred_name

    The person’s preferred name, if different.

  country_code

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

  country_code: `str` | `None` = None
  first_name: `str` | `None` = None
  last_name: `str` | `None` = None
  middle_name: `str` | `None` = None
  name_prefix: `str` | `None` = None
  name_suffix: `str` | `None` = None
  preferred_name: `str` | `None` = None
  to_dict()

    Converts the Person instance to a dictionary with camelCase keys.

    Omits attributes that are None.

    Returns:

      A dictionary representation of the person.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

  zip_file_name

    The name of the ZIP archive.

  product_identifier

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

  file_location_uri

    The URI where the document file can be accessed.

  file_create_date_time

    The creation timestamp of the document file (UTC).

  xml_file_name

    The name of the XML file within the ZIP archive.

  file_create_date_time: `datetime` | `None` = None
  file_location_uri: `str` | `None` = None
  classmethod from_dict(data)

    Creates a PrintedMetaData instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of PrintedMetaData.

    Return type:

      PrintedMetaData

  product_identifier: `str` | `None` = None
  to_dict()

    Converts the PrintedMetaData instance to a dictionary.

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

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

  xml_file_name: `str` | `None` = None
  zip_file_name: `str` | `None` = None

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

  Bases: `object`

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

  pgpub_document_meta_data

    PrintedMetaData for the Pre-Grant Publication, if any.

  grant_document_meta_data

    PrintedMetaData for the Grant document, if any.

  classmethod from_wrapper(wrapper)

    Creates a PrintedPublication instance from a PatentFileWrapper.

    Extracts PGPUB and Grant document metadata from the wrapper.

    Parameters:

      wrapper (`PatentFileWrapper`) – The patent file wrapper.

    Returns:

      An instance of PrintedPublication.

    Return type:

      PrintedPublication

  grant_document_meta_data: `PrintedMetaData` | `None` = None
  pgpub_document_meta_data: `PrintedMetaData` | `None` = None
  to_dict()

    Converts the PrintedPublication instance to a dictionary.

    Omits keys if their corresponding metadata is None.

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  customer_number_correspondence_data

    CustomerNumberCorrespondence object with customer number details.

  power_of_attorney_bag

    List of Attorney objects named in a power of attorney.

  attorney_bag

    List of Attorney objects listed as attorneys of record.

  attorney_bag: `List`[`Attorney`]
  customer_number_correspondence_data: `CustomerNumberCorrespondence` | `None` = None
  classmethod from_dict(data)

    Creates a RecordAttorney instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of RecordAttorney.

    Return type:

      RecordAttorney

  power_of_attorney_bag: `List`[`Attorney`]
  to_dict()

    Converts the RecordAttorney instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents a USPTO application status code and its textual description.

  code

    The numeric status code.

  description

    The textual description of the status code.

  __str__()

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

    Return type:

      `str`

  code: `int` | `None` = None
  description: `str` | `None` = None
  classmethod from_dict(data)

    Creates a StatusCode instance from a dictionary.

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

    Parameters:

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

    Returns:

      An instance of StatusCode.

    Return type:

      StatusCode

  to_dict()

    Converts the StatusCode instance to a dictionary.

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

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

class pyUSPTO.models.patent_data.StatusCodeCollection(status_codes)

  Bases: `object`

  A collection of StatusCode objects.

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

  status_codes

    An immutable tuple of StatusCode objects.

    Type:

      `tuple[StatusCode`, `]`

  __init__(status_codes)

    Initializes the StatusCodeCollection with a list of status codes.

    Parameters:

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

  find_by_code(code_to_find)

    Finds a status code by its numeric code.

    Parameters:

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

    Returns:

      The StatusCode object if found, otherwise None.

    Return type:

      Optional[StatusCode]

  search_by_description(text)

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

    Parameters:

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

    Returns:

      A new collection containing matching status codes.

    Return type:

      StatusCodeCollection

  to_dict()

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

    Returns:

      A list where each item is the dictionary

        representation of a StatusCode.

    Return type:

      List[Dict[str, Any]]

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

  Bases: `object`

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

  count

    The total number of status codes found matching the query.

  status_code_bag

    A StatusCodeCollection of the StatusCode objects returned.

  request_identifier

    An identifier for the API request, if provided.

  count: `int`
  classmethod from_dict(data)

    Creates a StatusCodeSearchResponse instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of StatusCodeSearchResponse.

    Return type:

      StatusCodeSearchResponse

  request_identifier: `str` | `None` = None
  status_code_bag: `StatusCodeCollection`
  to_dict()

    Converts the StatusCodeSearchResponse instance to a dictionary.

    Omits keys with None values or empty lists.

    Returns:

      Dictionary representation.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Represents telecommunication details, such as phone or fax numbers.

  telecommunication_number

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

  extension_number

    Any extension associated with the number.

  telecom_type_code

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

  extension_number: `str` | `None` = None
  classmethod from_dict(data)

    Creates a Telecommunication instance from a dictionary.

    Parameters:

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

    Returns:

      An instance of Telecommunication.

    Return type:

      Telecommunication

  telecom_type_code: `str` | `None` = None
  telecommunication_number: `str` | `None` = None
  to_dict()

    Converts the Telecommunication instance to a dictionary.

    Returns:

      Dictionary representation with camelCase keys.

    Return type:

      Dict[str, Any]

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

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

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

  Bases: `object`

  Additional party information in an interference.

  application_number_text

    Application number.

  inventor_name

    Name of inventor.

  patent_number

    Patent number.

  additional_party_name

    Name of additional party.

  additional_party_name: `str` | `None` = None
  application_number_text: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an AdditionalPartyData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of AdditionalPartyData.

    Return type:

      AdditionalPartyData

  inventor_name: `str` | `None` = None
  patent_number: `str` | `None` = None
  to_dict()

    Converts the AdditionalPartyData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Appeal document metadata.

  document_filing_date

    Date the document was filed.

  document_identifier

    Unique identifier for the document.

  document_name

    Name of the document.

  document_size_quantity

    Size of the document in bytes.

  document_ocr_text

    Full OCR text of the document.

  document_type_description_text

    Description of the document type.

  file_download_uri

    URI to download the document.

  document_filing_date: `date` | `None` = None
  document_identifier: `str` | `None` = None
  document_name: `str` | `None` = None
  document_ocr_text: `str` | `None` = None
  document_size_quantity: `int` | `None` = None
  document_type_description_text: `str` | `None` = None
  file_download_uri: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an AppealDocumentData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of AppealDocumentData.

    Return type:

      AppealDocumentData

  to_dict()

    Converts the AppealDocumentData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Appeal metadata.

  appeal_filing_date

    Date the appeal was filed.

  appeal_last_modified_date

    Last modification date.

  appeal_last_modified_date_time

    Last modification timestamp.

  application_type_category

    Type of application.

  docket_notice_mailed_date

    Date the docket notice was mailed.

  file_download_uri

    URI to download ZIP of appeal documents.

  appeal_filing_date: `date` | `None` = None
  appeal_last_modified_date: `date` | `None` = None
  appeal_last_modified_date_time: `datetime` | `None` = None
  application_type_category: `str` | `None` = None
  docket_notice_mailed_date: `date` | `None` = None
  file_download_uri: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an AppealMetaData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of AppealMetaData.

    Return type:

      AppealMetaData

  to_dict()

    Converts the AppealMetaData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `PartyData`

  Appellant party data in PTAB appeals.

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

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

  Bases: `object`

  Appeal decision information.

  appeal_outcome_category

    Outcome of the appeal.

  statute_and_rule_bag

    List of applicable statutes and rules.

  decision_issue_date

    Date the decision was issued.

  decision_type_category

    Type of decision.

  issue_type_bag

    List of issue types.

  appeal_outcome_category: `str` | `None` = None
  decision_issue_date: `date` | `None` = None
  decision_type_category: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a DecisionData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of DecisionData.

    Return type:

      DecisionData

  issue_type_bag: `List`[`str`]
  statute_and_rule_bag: `List`[`str`]
  to_dict()

    Converts the DecisionData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `PartyData`

  Derivation petitioner data in derivation proceedings.

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

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

  Bases: `object`

  Interference document metadata.

  document_identifier

    Unique identifier for the document.

  document_name

    Name of the document.

  document_size_quantity

    Size of the document in bytes.

  document_ocr_text

    Full OCR text of the document.

  document_title_text

    Title of the document.

  interference_outcome_category

    Outcome of the interference.

  document_filing_date

    Date the document was filed.

  decision_issue_date

    Date the decision was issued.

  decision_type_category

    Type of decision.

  file_download_uri

    URI to download the document.

  statute_and_rule_bag

    List of applicable statutes and rules.

  issue_type_bag

    List of issues addressed.

  decision_issue_date: `date` | `None` = None
  decision_type_category: `str` | `None` = None
  document_filing_date: `date` | `None` = None
  document_identifier: `str` | `None` = None
  document_name: `str` | `None` = None
  document_ocr_text: `str` | `None` = None
  document_size_quantity: `int` | `None` = None
  document_title_text: `str` | `None` = None
  file_download_uri: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an InterferenceDocumentData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of InterferenceDocumentData.

    Return type:

      InterferenceDocumentData

  interference_outcome_category: `str` | `None` = None
  issue_type_bag: `List`[`str`]
  statute_and_rule_bag: `List`[`str`]
  to_dict()

    Converts the InterferenceDocumentData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Interference metadata.

  interference_style_name

    Style name of the interference.

  interference_last_modified_date

    Last modification date.

  interference_last_modified_date_time

    Last modification datetime.

  declaration_date

    Declaration date.

  file_download_uri

    URI to download ZIP of interference documents.

  declaration_date: `date` | `None` = None
  file_download_uri: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates an InterferenceMetaData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of InterferenceMetaData.

    Return type:

      InterferenceMetaData

  interference_last_modified_date: `date` | `None` = None
  interference_last_modified_date_time: `datetime` | `None` = None
  interference_style_name: `str` | `None` = None
  to_dict()

    Converts the InterferenceMetaData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `PartyData`

  Junior party information in PTAB interference proceedings.

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

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

  Bases: `object`

  Individual PTAB appeal decision record.

  appeal_number

    Appeal number.

  last_modified_date_time

    Last modification timestamp.

  appeal_document_category

    Document category.

  appeal_meta_data

    Appeal metadata.

  appellant_data

    Appellant information.

  requestor_data

    Third party requestor information.

  document_data

    Document metadata.

  decision_data

    Decision information.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  appeal_document_category: `str` | `None` = None
  appeal_meta_data: `AppealMetaData` | `None` = None
  appeal_number: `str` | `None` = None
  appellant_data: `AppellantData` | `None` = None
  decision_data: `DecisionData` | `None` = None
  document_data: `AppealDocumentData` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABAppealDecision instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABAppealDecision.

    Return type:

      PTABAppealDecision

  last_modified_date_time: `datetime` | `None` = None
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  requestor_data: `RequestorData` | `None` = None
  to_dict()

    Converts the PTABAppealDecision instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Response container for PTAB appeals search.

  count

    Total number of matching results.

  request_identifier

    UUID for the API request.

  patent_appeal_data_bag

    List of appeal decisions.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  count: `int` = 0
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABAppealResponse instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABAppealResponse.

    Return type:

      PTABAppealResponse

  patent_appeal_data_bag: `List`[`PTABAppealDecision`]
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  request_identifier: `str` | `None` = None
  to_dict()

    Converts the PTABAppealResponse instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Individual PTAB interference decision record.

  interference_number

    Interference number.

  last_modified_date_time

    Last modification timestamp.

  interference_meta_data

    Interference metadata.

  senior_party_data

    Senior party information.

  junior_party_data

    Junior party information.

  additional_party_data_bag

    List of additional parties.

  document_data

    Document metadata.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  additional_party_data_bag: `List`[`AdditionalPartyData`]
  document_data: `InterferenceDocumentData` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABInterferenceDecision instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABInterferenceDecision.

    Return type:

      PTABInterferenceDecision

  interference_meta_data: `InterferenceMetaData` | `None` = None
  interference_number: `str` | `None` = None
  junior_party_data: `JuniorPartyData` | `None` = None
  last_modified_date_time: `datetime` | `None` = None
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  senior_party_data: `SeniorPartyData` | `None` = None
  to_dict()

    Converts the PTABInterferenceDecision instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Response container for PTAB interferences search.

  count

    Total number of matching results.

  request_identifier

    UUID for the API request.

  patent_interference_data_bag

    List of interference decisions.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  count: `int` = 0
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABInterferenceResponse instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABInterferenceResponse.

    Return type:

      PTABInterferenceResponse

  patent_interference_data_bag: `List`[`PTABInterferenceDecision`]
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  request_identifier: `str` | `None` = None
  to_dict()

    Converts the PTABInterferenceResponse instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

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

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

  trial_document_category

    Category (Document or Decision).

  last_modified_date_time

    Last modification timestamp.

  trial_number

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

  trial_type_code

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

  trial_meta_data

    Trial metadata.

  patent_owner_data

    Patent owner information.

  regular_petitioner_data

    Regular petitioner information.

  respondent_data

    Respondent information.

  derivation_petitioner_data

    Derivation petitioner information.

  document_data

    Document metadata (if document).

  decision_data

    Decision information (if decision).

  raw_data

    Raw JSON response data (if include_raw_data=True).

  decision_data: `TrialDecisionData` | `None` = None
  derivation_petitioner_data: `DerivationPetitionerData` | `None` = None
  document_data: `TrialDocumentData` | `None` = None
  classmethod from_dict(data, include_raw_data=False)
    Return type:

      `PTABTrialDocument`

  last_modified_date_time: `datetime` | `None` = None
  patent_owner_data: `PatentOwnerData` | `None` = None
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  regular_petitioner_data: `RegularPetitionerData` | `None` = None
  respondent_data: `RespondentData` | `None` = None
  to_dict()

    Converts the PTABTrialDocument instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

  trial_document_category: `str` | `None` = None
  trial_meta_data: `TrialMetaData` | `None` = None
  trial_number: `str` | `None` = None
  trial_type_code: `str` | `None` = None

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

  Bases: `object`

  Response container for PTAB trial documents/decisions search.

  count: `int` = 0
  classmethod from_dict(data, include_raw_data=False)
    Return type:

      `PTABTrialDocumentResponse`

  patent_trial_document_data_bag: `List`[`PTABTrialDocument`]
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  request_identifier: `str` | `None` = None
  to_dict()

    Converts the PTABTrialDocumentResponse instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Individual PTAB trial proceeding record.

  trial_number

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

  trial_record_identifier

    UUID identifier for the trial record.

  last_modified_date_time

    Last modification timestamp.

  trial_meta_data

    Trial metadata.

  patent_owner_data

    Patent owner information.

  regular_petitioner_data

    Regular petitioner information.

  respondent_data

    Respondent information.

  derivation_petitioner_data

    Derivation petitioner information.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  derivation_petitioner_data: `DerivationPetitionerData` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABTrialProceeding instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABTrialProceeding.

    Return type:

      PTABTrialProceeding

  last_modified_date_time: `datetime` | `None` = None
  patent_owner_data: `PatentOwnerData` | `None` = None
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  regular_petitioner_data: `RegularPetitionerData` | `None` = None
  respondent_data: `RespondentData` | `None` = None
  to_dict()

    Converts the PTABTrialProceeding instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

  trial_meta_data: `TrialMetaData` | `None` = None
  trial_number: `str` | `None` = None

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

  Bases: `object`

  Response container for PTAB trial proceedings search.

  count

    Total number of matching results.

  request_identifier

    UUID for the API request.

  patent_trial_proceeding_data_bag

    List of trial proceedings.

  raw_data

    Raw JSON response data (if include_raw_data=True).

  count: `int` = 0
  classmethod from_dict(data, include_raw_data=False)

    Creates a PTABTrialProceedingResponse instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of PTABTrialProceedingResponse.

    Return type:

      PTABTrialProceedingResponse

  patent_trial_proceeding_data_bag: `List`[`PTABTrialProceeding`]
  raw_data: `Dict`[`str`, `Any`] | `None` = None
  request_identifier: `str` | `None` = None
  to_dict()

    Converts the PTABTrialProceedingResponse instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `PartyData`

  Party data for a patent owner in PTAB trial proceedings.

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

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

  Bases: `object`

  Regular petitioner information.

  counsel_name

    Name of counsel.

  real_party_in_interest_name

    Real party in interest name.

  counsel_name: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a RegularPetitionerData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of RegularPetitionerData.

    Return type:

      RegularPetitionerData

  real_party_in_interest_name: `str` | `None` = None
  to_dict()

    Converts the RegularPetitionerData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Third party requestor information.

  third_party_name

    Name of the third party.

  classmethod from_dict(data, include_raw_data=False)

    Creates a RequestorData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of RequestorData.

    Return type:

      RequestorData

  third_party_name: `str` | `None` = None
  to_dict()

    Converts the RequestorData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `PartyData`

  Respondent party data in derivation proceedings.

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

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

  Bases: `PartyData`

  Senior party information in PTAB interference proceedings.

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

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

  Bases: `object`

  Metadata for a decision in a PTAB trial.

  statute_and_rule_bag

    List of applicable statutes and rules.

  decision_issue_date

    Date issued.

  decision_type_category

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

  issue_type_bag

    List of issues addressed.

  trial_outcome_category

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

  decision_issue_date: `date` | `None` = None
  decision_type_category: `str` | `None` = None
  classmethod from_dict(data)
    Return type:

      `TrialDecisionData`

  issue_type_bag: `List`[`str`]
  statute_and_rule_bag: `List`[`str`]
  to_dict()

    Converts the TrialDecisionData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

  trial_outcome_category: `str` | `None` = None

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

  Bases: `object`

  Metadata for a document in a PTAB trial.

  document_category

    Category of the document.

  document_filing_date

    Filing date.

  document_identifier

    Unique ID.

  document_name

    Filename.

  document_number

    Document number in the proceeding.

  document_size_quantity

    Size in bytes.

  document_ocr_text

    OCR text content.

  document_title_text

    Title of the document.

  document_type_description_text

    Description of document type.

  file_download_uri

    URL to download the file.

  filing_party_category

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

  mime_type_identifier

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

  document_status

    Public status.

  document_filing_date: `date` | `None` = None
  document_identifier: `str` | `None` = None
  document_name: `str` | `None` = None
  document_number: `str` | `None` = None
  document_ocr_text: `str` | `None` = None
  document_size_quantity: `int` | `None` = None
  document_title_text: `str` | `None` = None
  document_type_description_text: `str` | `None` = None
  file_download_uri: `str` | `None` = None
  filing_party_category: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a TrialDocumentData instance from a dictionary.

    Parameters:

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

      - include_raw_data (`bool`) – Ignored for this model.

    Returns:

      An instance of TrialDocumentData.

    Return type:

      TrialDocumentData

  to_dict()

    Converts the TrialDocumentData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

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

  Bases: `object`

  Trial metadata including status, dates, and download URI.

  petition_filing_date

    Date the petition was filed.

  accorded_filing_date

    The filing date accorded to the petition.

  trial_last_modified_date_time

    Last modification timestamp.

  trial_last_modified_date

    Last modification date.

  trial_status_category

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

  trial_type_code

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

  file_download_uri

    URI to download ZIP of all trial documents.

  termination_date

    Date the trial was terminated.

  latest_decision_date

    Date of the most recent decision.

  institution_decision_date

    Date of the institution decision.

  accorded_filing_date: `date` | `None` = None
  file_download_uri: `str` | `None` = None
  classmethod from_dict(data, include_raw_data=False)

    Creates a TrialMetaData instance from a dictionary.

    Parameters:

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

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

    Returns:

      An instance of TrialMetaData.

    Return type:

      TrialMetaData

  institution_decision_date: `date` | `None` = None
  latest_decision_date: `date` | `None` = None
  petition_filing_date: `date` | `None` = None
  termination_date: `date` | `None` = None
  to_dict()

    Converts the TrialMetaData instance to a dictionary.

    Returns:

      Dictionary with camelCase keys and None values filtered.

    Return type:

      Dict[str, Any]

  trial_last_modified_date: `date` | `None` = None
  trial_last_modified_date_time: `datetime` | `None` = None
  trial_status_category: `str` | `None` = None
  trial_type_code: `str` | `None` = None

models.utils - Utility functions for USPTO data models

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

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

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

  Parameters:

    - date_str (`Optional[str]`) – The string to parse as a date.

    - fmt (`str`, optional) – The expected strptime format string for parsing the date. Defaults to “%Y-%m-%d”.

  Returns:

    A date object if parsing is successful and date_str

      is not None. Returns None if date_str is None or if parsing fails.

  Return type:

    Optional[date]

  Warns:

    USPTODateParseWarning – If the date string cannot be parsed.

pyUSPTO.models.utils.parse_to_datetime_utc(datetime_str)

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

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

  Parameters:

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

  Returns:

    A timezone-aware datetime object in UTC if parsing

      is successful and datetime_str is not None. Returns None if datetime_str is None or if parsing/conversion fails.

  Return type:

    Optional[datetime]

  Warns:

    - USPTODateParseWarning – If the datetime string cannot be parsed.

    - USPTOTimezoneWarning – If timezone localization fails.

pyUSPTO.models.utils.parse_yn_to_bool(value)

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

  Parameters:

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

  Returns:

    True if value is ‘Y’ or ‘y’, False if value is

      ’N’ or ‘n’. Returns None if value is None or any other string.

  Return type:

    Optional[bool]

  Warns:

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

pyUSPTO.models.utils.serialize_bool_to_yn(value)

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

  Parameters:

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

  Returns:

    “Y” if value is True, “N” if value is False.

      Returns None if value is None.

  Return type:

    Optional[str]

pyUSPTO.models.utils.serialize_date(d)

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

  Parameters:

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

  Returns:

    The date as an ISO 8601 formatted string, or None

      if the input is None.

  Return type:

    Optional[str]

pyUSPTO.models.utils.serialize_datetime_as_iso(dt)

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

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

  The resulting datetime is formatted as:

    YYYY-MM-DDTHH:MM:SS.000±HHMM

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

  Parameters:

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

  Returns:

    The datetime formatted in the assumed local timezone,

      or None if the input dt is None.

  Return type:

    Optional[str]

pyUSPTO.models.utils.serialize_datetime_as_naive(dt)
  Return type:

    `str`

pyUSPTO.models.utils.to_camel_case(snake_str)

  Converts a snake_case string to lowerCamelCase.

  For example, “example_snake_string” becomes “exampleSnakeString”.

  Parameters:

    snake_str (`str`) – The input string in snake_case.

  Returns:

    The converted string in lowerCamelCase.

  Return type:

    str