pyUSPTO 0.4.5__tar.gz → 0.5.0__tar.gz

pyuspto-0.5.0/.github/workflows/codeql.yml

@@ -0,0 +1,99 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '41 13 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        queries: security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

{pyuspto-0.4.5 → pyuspto-0.5.0}/.readthedocs.yaml

@@ -7,7 +7,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.10"
+    python: "3.14"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

{pyuspto-0.4.5 → pyuspto-0.5.0}/CHANGELOG.md

@@ -5,7 +5,119 @@ All notable changes to the pyUSPTO package will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.3.0] - TBD
+## [0.4.5] - 2026-03-11
+
+### Changed
+
+- **Refactor**: Split `_make_request` into three typed request methods:
+  - `_get_model` — returns parsed model `T`
+  - `_get_json` — returns `dict[str, Any]`
+  - `_stream_request` — returns `requests.Response`
+- Removed all `assert isinstance` runtime checks and `# type: ignore` annotations at 28 call sites
+- `DocumentBag`, `StatusCodeSearchResponse`, and `PetitionDecisionDownloadResponse` now conform to `FromDictProtocol` (`include_raw_data` parameter added to `from_dict`)
+
+### Fixed
+
+- PTAB appeals integration test query (`Appeal` → `REGULAR` for `applicationTypeCategory`)
+- Read the Docs build: updated Python from 3.10 to 3.14 to satisfy `myst-parser>=3.11` requirement
+
+## [0.4.4] - 2026-03-08
+
+### Added
+
+- `get_patent(patent_number)` — lookup `PatentFileWrapper` by granted patent number
+- `get_publication(publication_number)` — lookup by publication number
+- `get_pct(pct_number)` — lookup by PCT application or publication number (auto-detected)
+
+### Fixed
+
+- `sanitize_application_number` now strips leading zeros from PCT serial numbers
+
+## [0.4.3] - 2026-03-05
+
+### Added
+
+- `get_IFW` method for bulk downloading all documents in an application's IFW
+- `IFWResult` model with document map and optional ZIP output
+- `get_IFW_metadata` now populates `document_bag` on the returned `PatentFileWrapper`
+- Example: searching CPC codes (#102)
+
+### Fixed
+
+- Auto-quote `classification_q` values containing spaces or slashes (#101)
+- Missing `typing_extensions` dependency
+- CI refactor to exclude dev requirements from install
+
+## [0.4.2] - 2026-02-26
+
+### Fixed
+
+- Quote multi-word values in query convenience parameters
+
+## [0.4.1] - 2026-02-25
+
+### Added
+
+- Download path validation and zip-bomb protection
+- Sanitize download filenames to prevent path traversal
+- Skip symlinks during archive extraction
+- Session lifecycle and extraction safety documentation
+
+### Changed
+
+- Enable retries for POST requests
+- Remove unused `utils.http` module and `ALLOWED_METHODS`
+- Enforce keyword-only arguments in `get_IFW_metadata`
+- Optimize tox deps and enable parallel
+
+## [0.4.0] - 2026-02-23
+
+### Changed
+
+- **Refactor**: Centralize session management in `USPTOConfig`
+- `FileData.file_date` changed to `datetime` type
+
+### Fixed
+
+- Prevent path traversal in archive extraction
+- Fix #79
+
+## [0.3.4] - 2026-01-11
+
+### Added
+
+- JSON parsing error handling
+- Pagination validation
+- Documentation for HTTP method restrictions and `include_raw_data` flag
+
+### Changed
+
+- Aligned backoff factor default
+
+## [0.3.3] - 2026-01-08
+
+### Changed
+
+- Bulk data client refactor (#40)
+
+## [0.3.2] - 2025-12-31
+
+### Changed
+
+- Refactor downloads (#35)
+- Configurable download chunk size
+- Session sharing across clients
+
+## [0.3.1] - 2025-12-15
+
+### Added
+
+- `paginate_decisions` POST support
+- Configurable download chunk size
+- Session sharing across clients
+- Bulk data endpoint updates
+
+## [0.3.0] - 2025-12-09
 
 ### Added
 

{pyuspto-0.4.5 → pyuspto-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.4.5
+Version: 0.5.0
 Summary: A Modern Python client for accessing the United States Patent and Trademark Office (USPTO) Open Data Portal (ODP) APIs.
 Author-email: Andrew Piechocki <apiechocki@dunlapcodding.com>
 License-Expression: MIT

pyuspto-0.5.0/docs/source/api/clients/enriched_citations.rst

@@ -0,0 +1,7 @@
+Enriched Citations Client
+=========================
+
+.. automodule:: pyUSPTO.clients.enriched_citations
+   :members:
+   :undoc-members:
+   :show-inheritance:

{pyuspto-0.4.5 → pyuspto-0.5.0}/docs/source/api/clients/index.rst

@@ -5,6 +5,7 @@ Clients
    :maxdepth: 2
 
    bulk_data
+   enriched_citations
    patent_data
    petition_decisions
    ptab_appeals

pyuspto-0.5.0/docs/source/api/models/enriched_citations.rst

@@ -0,0 +1,7 @@
+Enriched Citations
+==================
+
+.. automodule:: pyUSPTO.models.enriched_citations
+   :members:
+   :undoc-members:
+   :show-inheritance:

{pyuspto-0.4.5 → pyuspto-0.5.0}/docs/source/api/models/index.rst

@@ -6,6 +6,7 @@ Models
 
    base
    bulk_data
+   enriched_citations
    patent_data
    petition_decisions
    ptab

pyuspto-0.5.0/docs/source/examples/enriched_citations.rst

@@ -0,0 +1,6 @@
+Enriched Citations Example
+==========================
+
+.. literalinclude:: ../../../examples/enriched_citations_example.py
+   :language: python
+   :linenos:

{pyuspto-0.4.5 → pyuspto-0.5.0}/docs/source/examples/index.rst

@@ -5,6 +5,7 @@ Examples
    :maxdepth: 2
 
    bulk_data
+   enriched_citations
    patent_data
    ifw_example
    petition_decisions

pyuspto-0.5.0/examples/bulk_data_example.py

@@ -0,0 +1,133 @@
+"""Example usage of pyUSPTO for bulk data products.
+
+Demonstrates the BulkDataClient for searching products, listing files,
+and downloading bulk data archives.
+"""
+
+import os
+
+from pyUSPTO import BulkDataClient, FileData, USPTOConfig
+
+DEST_PATH = "./notes/download-example"
+
+
+def format_size(size_bytes: int | float) -> str:
+    """Format a size in bytes to a human-readable string (KB, MB, GB, etc.)."""
+    if size_bytes == 0:
+        return "0 B"
+
+    size_names = ["B", "KB", "MB", "GB", "TB", "PB"]
+    i = 0
+    while size_bytes >= 1024 and i < len(size_names) - 1:
+        size_bytes /= 1024
+        i += 1
+
+    return f"{size_bytes:.2f} {size_names[i]}"
+
+
+# --- Client Initialization ---
+api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
+if api_key == "YOUR_API_KEY_HERE":
+    raise ValueError(
+        "API key is not set. Set the USPTO_API_KEY environment variable."
+    )
+config = USPTOConfig(api_key=api_key)
+client = BulkDataClient(config=config)
+
+print("-" * 40)
+print("Example 1: Search for products")
+print("-" * 40)
+
+response = client.search_products(query="patent", limit=5)
+print(f"Found {response.count} products matching 'patent'")
+
+for product in response.bulk_data_product_bag:
+    print(f"\n  Product: {product.product_title_text}")
+    print(f"  ID: {product.product_identifier}")
+    print(f"  Description: {product.product_description_text[:100]}...")
+    print(f"  Total files: {product.product_file_total_quantity}")
+    print(f"  Total size: {format_size(product.product_total_file_size)}")
+
+print("-" * 40)
+print("Example 2: Paginate through products")
+print("-" * 40)
+
+max_items = 20
+count = 0
+for product in client.paginate_products(query="trademark", limit=10):
+    count += 1
+    print(f"  {count}. {product.product_title_text} ({product.product_identifier})")
+    if count >= max_items:
+        print(f"  ... (stopping at {max_items} products)")
+        break
+
+print("-" * 40)
+print("Example 3: Get product by ID")
+print("-" * 40)
+
+product_id = "PTGRXML"  # Patent Grant Full-Text Data (No Images) - XML
+product = client.get_product_by_id(product_id, include_files=True, latest=True)
+
+print(f"Product: {product.product_title_text}")
+print(f"Description: {product.product_description_text}")
+print(f"Frequency: {product.product_frequency_text}")
+print(f"Labels: {product.product_label_array_text}")
+print(f"Categories: {product.product_dataset_category_array_text}")
+print(f"Date range: {product.product_from_date} to {product.product_to_date}")
+
+print("-" * 40)
+print("Example 4: List files for a product")
+print("-" * 40)
+
+if product.product_file_bag and product.product_file_bag.file_data_bag:
+    print(f"Found {len(product.product_file_bag.file_data_bag)} file(s):")
+
+    for file_data in product.product_file_bag.file_data_bag:
+        print(f"\n  File: {file_data.file_name}")
+        print(f"  Size: {format_size(file_data.file_size)}")
+        print(f"  Type: {file_data.file_type_text}")
+        print(
+            f"  Data range: {file_data.file_data_from_date} to {file_data.file_data_to_date}"
+        )
+        print(f"  Released: {file_data.file_release_date}")
+        print(f"  Download URI: {file_data.file_download_uri}")
+else:
+    print("No files found for this product")
+
+print("-" * 40)
+print("Example 5: Download a file (with extraction)")
+print("-" * 40)
+
+min_file: FileData | None = None
+last_bytes: float = float("inf")
+
+if product.product_file_bag and product.product_file_bag.file_data_bag:
+    for file_data in product.product_file_bag.file_data_bag:
+        if file_data.file_size < last_bytes:
+            last_bytes = file_data.file_size
+            min_file = file_data
+
+if min_file:
+    print(f"Downloading smallest file: {min_file.file_name}")
+    print(f"Size: {format_size(min_file.file_size)}")
+
+    downloaded_path = client.download_file(
+        file_data=min_file,
+        destination=DEST_PATH,
+        overwrite=True,
+        extract=True,
+    )
+    print(f"Downloaded to {downloaded_path}")
+
+print("-" * 40)
+print("Example 6: Download without extraction")
+print("-" * 40)
+
+if product.product_file_bag and product.product_file_bag.file_data_bag and min_file:
+    downloaded_path = client.download_file(
+        file_data=min_file,
+        destination=DEST_PATH,
+        overwrite=True,
+        extract=False,
+    )
+    print(f"Archive saved to {downloaded_path}")

pyuspto-0.5.0/examples/enriched_citations_example.py

@@ -0,0 +1,132 @@
+"""Example usage of pyUSPTO for Enriched Cited Reference Metadata.
+
+Demonstrates the EnrichedCitationsClient for searching citation data
+extracted from patent office actions, filtering by various criteria,
+and paginating through results.
+"""
+
+import os
+
+from pyUSPTO import EnrichedCitationsClient, USPTOConfig
+
+# --- Client Initialization ---
+api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
+if api_key == "YOUR_API_KEY_HERE":
+    raise ValueError(
+        "API key is not set. Set the USPTO_API_KEY environment variable."
+    )
+config = USPTOConfig(api_key=api_key)
+client = EnrichedCitationsClient(config=config)
+
+print("-" * 40)
+print("Example 1: Search by application number")
+print("-" * 40)
+
+response = client.search_citations(patent_application_number_q="15061308")
+print(f"Found {response.num_found} citations for application 15061308.")
+for citation in response.docs[:5]:
+    print(f"\n  Cited Document: {citation.cited_document_identifier}")
+    print(f"  Category Code: {citation.citation_category_code}")
+    print(f"  Office Action Date: {citation.office_action_date}")
+    print(f"  Office Action Type: {citation.office_action_category}")
+    if citation.examiner_cited_reference_indicator:
+        print("  Cited by: Examiner")
+    if citation.passage_location_text:
+        print(f"  Passages: {citation.passage_location_text}")
+
+print("-" * 40)
+print("Example 2: Search by tech center and citation category")
+print("-" * 40)
+
+response = client.search_citations(
+    tech_center_q="2800",
+    citation_category_code_q="X",
+    rows=5,
+)
+print(f"Found {response.num_found} 'X' citations in tech center 2800.")
+for citation in response.docs:
+    print(
+        f"  App {citation.patent_application_number}: "
+        f"{citation.cited_document_identifier} "
+        f"(claims: {citation.related_claim_number_text})"
+    )
+
+print("-" * 40)
+print("Example 3: Search by date range")
+print("-" * 40)
+
+response = client.search_citations(
+    office_action_date_from_q="2019-01-01",
+    office_action_date_to_q="2019-12-31",
+    rows=5,
+)
+print(f"Found {response.num_found} citations from 2019.")
+
+print("-" * 40)
+print("Example 4: Combined filters")
+print("-" * 40)
+
+response = client.search_citations(
+    tech_center_q="2800",
+    citation_category_code_q="Y",
+    examiner_cited_q=True,
+    rows=5,
+)
+print(
+    f"Found {response.num_found} examiner-cited 'Y' citations in tech center 2800."
+)
+for citation in response.docs:
+    print(
+        f"  App {citation.patent_application_number}: "
+        f"{citation.cited_document_identifier} "
+        f"(art unit: {citation.group_art_unit_number})"
+    )
+
+print("-" * 40)
+print("Example 5: Search with sort")
+print("-" * 40)
+
+response = client.search_citations(
+    tech_center_q="2800",
+    sort="officeActionDate desc",
+    rows=5,
+)
+print(f"Found {response.num_found} citations, sorted by date descending.")
+for citation in response.docs:
+    print(f"  {citation.office_action_date}: {citation.cited_document_identifier}")
+
+print("-" * 40)
+print("Example 6: Search by cited document identifier")
+print("-" * 40)
+
+response = client.search_citations(
+    cited_document_identifier_q="US 20190165601 A1",
+    rows=5,
+)
+print(f"Found {response.num_found} citations of US 20190165601 A1.")
+
+print("-" * 40)
+print("Example 7: Paginate through results")
+print("-" * 40)
+
+max_items = 30
+count = 0
+for citation in client.paginate_citations(
+    tech_center_q="2800", rows=10
+):
+    count += 1
+    if count >= max_items:
+        print(f"  ... (stopping at {max_items} items)")
+        break
+
+print(f"Retrieved {count} citations via pagination")
+
+print("-" * 40)
+print("Example 8: Get available fields")
+print("-" * 40)
+
+fields_response = client.get_fields()
+print(f"API Status: {fields_response.api_status}")
+print(f"Field Count: {fields_response.field_count}")
+print(f"Fields: {fields_response.fields}")
+print(f"Last Updated: {fields_response.last_data_updated_date}")

{pyuspto-0.4.5 → pyuspto-0.5.0}/examples/error_handling_example.py

@@ -1,64 +1,68 @@
-"""Error handling example for pyUSPTO.
+"""Example usage of pyUSPTO for error handling patterns.
 
-This example demonstrates how to handle common errors when using the USPTO API clients.
+Demonstrates how to handle common errors when using the USPTO API clients.
 """
 
 import os
 import time
 
-from pyUSPTO.clients import PatentDataClient
-from pyUSPTO.config import USPTOConfig
-from pyUSPTO.exceptions import (
+from pyUSPTO import (
+    HTTPConfig,
+    PatentDataClient,
     USPTOApiAuthError,
     USPTOApiNotFoundError,
     USPTOApiRateLimitError,
+    USPTOConfig,
     USPTOConnectionError,
     USPTOTimeout,
 )
-from pyUSPTO.http_config import HTTPConfig
 
-# Initialize client
+# --- Client Initialization ---
 api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
 config = USPTOConfig(api_key=api_key)
 client = PatentDataClient(config=config)
 
-# Example 1: Handle authentication errors
+print("-" * 40)
 print("Example 1: Authentication errors")
+print("-" * 40)
+
 try:
-    # This will fail with invalid API key
     bad_client = PatentDataClient(config=config)
     bad_client.search_applications(limit=1)
 except USPTOApiAuthError as e:
     print(f"Authentication failed: {e}")
     print("Check your API key and try again.")
 
-# Example 2: Handle not found errors
-print("\nExample 2: Not found errors")
+print("-" * 40)
+print("Example 2: Not found errors")
+print("-" * 40)
+
 try:
-    # Try to get a non-existent application
     client.get_application_by_number("99999999")
 except USPTOApiNotFoundError as e:
     print(f"Resource not found: {e}")
     print("The application number may be invalid or not in the system.")
 
-# Example 3: Handle rate limiting with retry
-print("\nExample 3: Rate limiting")
+print("-" * 40)
+print("Example 3: Rate limiting")
+print("-" * 40)
+
 try:
-    # If you hit rate limits, the API returns 429
     results = client.search_applications(limit=100)
     print(f"Retrieved {results.count} results")
 except USPTOApiRateLimitError as e:
     print(f"Rate limit exceeded: {e}")
     print("Waiting 60 seconds before retry...")
     time.sleep(60)
-    # Retry the request
     results = client.search_applications(limit=100)
     print(f"Retry successful: {results.count} results")
 
-# Example 4: Handle timeouts with custom configuration
-print("\nExample 4: Timeout handling")
+print("-" * 40)
+print("Example 4: Timeout handling")
+print("-" * 40)
+
 # Configure shorter timeout for demonstration
-http_config = HTTPConfig(timeout=1)  # Very short timeout
+http_config = HTTPConfig(timeout=1)
 config = USPTOConfig(api_key=api_key, http_config=http_config)
 timeout_client = PatentDataClient(config=config)
 
@@ -68,17 +72,20 @@ except USPTOTimeout as e:
     print(f"Request timed out: {e}")
     print("Consider increasing timeout or checking network connection.")
 
-# Example 5: Handle connection errors
-print("\nExample 5: Connection errors")
+print("-" * 40)
+print("Example 5: Connection errors")
+print("-" * 40)
+
 try:
-    # This might fail due to network issues
     client.search_applications(limit=10)
 except USPTOConnectionError as e:
     print(f"Connection error: {e}")
     print("Check your network connection and try again.")
 
-# Example 6: Catch-all for unexpected errors
-print("\nExample 6: General error handling")
+print("-" * 40)
+print("Example 6: General error handling")
+print("-" * 40)
+
 try:
     results = client.search_applications(patent_number_q="10000000", limit=5)
     if results.count > 0:
@@ -94,5 +101,4 @@ except USPTOTimeout:
 except USPTOConnectionError:
     print("Connection failed - check network")
 except Exception as e:
-    # Catch any other unexpected errors
     print(f"Unexpected error: {e}")