pyUSPTO 0.3.4__tar.gz → 0.4.1__tar.gz

{pyuspto-0.3.4 → pyuspto-0.4.1}/.github/workflows/publish-docs.yaml

@@ -15,9 +15,9 @@ jobs:
     name: Build documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v6
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
       - name: Install dependencies
@@ -31,7 +31,7 @@ jobs:
           cd docs
           make html
       - name: Archive documentation
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v6
         with:
           name: documentation
           path: docs/build/html/

{pyuspto-0.3.4 → pyuspto-0.4.1}/.github/workflows/publish-to-test-pypi.yml

@@ -16,11 +16,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         persist-credentials: false
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -32,7 +32,7 @@ jobs:
     - name: Build a binary wheel and a source tarball
       run: python3 -m build
     - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v6
       with:
         name: python-package-distributions
         path: dist/
@@ -53,7 +53,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: python-package-distributions
         path: dist/
@@ -76,7 +76,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v7
       with:
         name: python-package-distributions
         path: dist/

{pyuspto-0.3.4 → pyuspto-0.4.1}/.github/workflows/python-tests.yml

@@ -14,10 +14,10 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -33,7 +33,7 @@ jobs:
           pytest tests/ --cov=src/pyUSPTO
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v5
         with:
           fail_ci_if_error: false
 
@@ -41,10 +41,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
 

{pyuspto-0.3.4 → pyuspto-0.4.1}/ADVANCED.md

@@ -31,7 +31,28 @@ config = USPTOConfig(
 client = PatentDataClient(config=config)
 ```
 
-Configure HTTP settings via environment variables:
+## Session Lifecycle
+
+`USPTOConfig` manages an underlying `requests.Session`. For short-lived scripts this is cleaned up automatically, but for long-running applications or tests you may close it explicitly:
+
+```python
+from pyUSPTO import PatentDataClient, USPTOConfig
+
+# Option 1: Context manager
+with USPTOConfig(api_key="your_key") as config:
+    client = PatentDataClient(config=config)
+    response = client.search_applications(limit=1)
+
+# Option 2: Explicit close
+config = USPTOConfig(api_key="your_key")
+try:
+    client = PatentDataClient(config=config)
+    response = client.search_applications(limit=1)
+finally:
+    config.close()
+```
+
+## HTTP Configuration via Environment Variables
 
 ```bash
 export USPTO_REQUEST_TIMEOUT=60.0       # Read timeout
@@ -75,24 +96,32 @@ All clients support configuration via environment variables. This is the recomme
 | `USPTO_PATENT_DATA_BASE_URL`        | Base URL for Patent Data API                   | `https://api.uspto.gov` |
 | `USPTO_PETITION_DECISIONS_BASE_URL` | Base URL for Petition Decisions API            | `https://api.uspto.gov` |
 | `USPTO_PTAB_BASE_URL`               | Base URL for PTAB APIs                         | `https://api.uspto.gov` |
-| `USPTO_DOWNLOAD_CHUNK_SIZE`         | Chunk size in bytes for file downloads         | `8192`                  |
+
+> [!NOTE]
+> The base URL variables are provided in case the USPTO introduces alternate environments (e.g., a development or testing endpoint) in the future. Currently there are no such endpoints, and these defaults should not be changed.
 
 ### HTTP Transport Configuration
 
-| Environment Variable       | Description                                | Default  |
-| -------------------------- | ------------------------------------------ | -------- |
-| `USPTO_REQUEST_TIMEOUT`  | Read timeout in seconds                    | `30.0` |
-| `USPTO_CONNECT_TIMEOUT`  | Connection timeout in seconds              | `10.0` |
-| `USPTO_MAX_RETRIES`      | Maximum number of retry attempts           | `3`    |
-| `USPTO_BACKOFF_FACTOR`   | Exponential backoff multiplier for retries | `2.0`  |
-| `USPTO_POOL_CONNECTIONS` | Number of connection pools to cache        | `10`   |
-| `USPTO_POOL_MAXSIZE`     | Maximum connections per pool               | `10`   |
+| Environment Variable          | Description                                | Default         |
+| ----------------------------- | ------------------------------------------ | --------------- |
+| `USPTO_REQUEST_TIMEOUT`     | Read timeout in seconds                    | `30.0`        |
+| `USPTO_CONNECT_TIMEOUT`     | Connection timeout in seconds              | `10.0`        |
+| `USPTO_MAX_RETRIES`         | Maximum number of retry attempts           | `3`           |
+| `USPTO_BACKOFF_FACTOR`      | Exponential backoff multiplier for retries | `2.0`         |
+| `USPTO_POOL_CONNECTIONS`    | Number of connection pools to cache        | `10`          |
+| `USPTO_POOL_MAXSIZE`        | Maximum connections per pool               | `10`          |
+| `USPTO_DOWNLOAD_CHUNK_SIZE` | Chunk size in bytes for file downloads     | `8192`        |
+| `USPTO_MAX_EXTRACT_SIZE`    | Maximum bytes to extract from archives     | None (no limit) |
 
 ### Example: Configuration
 
 ```bash
 # API Configuration
 export USPTO_API_KEY="your_api_key"
+export USPTO_BULK_DATA_BASE_URL="https://api.uspto.gov"
+export USPTO_PATENT_DATA_BASE_URL="https://api.uspto.gov"
+export USPTO_PETITION_DECISIONS_BASE_URL="https://api.uspto.gov"
+export USPTO_PTAB_BASE_URL="https://api.uspto.gov"
 
 # Increase timeouts for large downloads
 export USPTO_REQUEST_TIMEOUT=120.0
@@ -108,6 +137,9 @@ export USPTO_POOL_MAXSIZE=20
 
 # Larger chunk size for faster downloads
 export USPTO_DOWNLOAD_CHUNK_SIZE=65536
+
+# Limit total bytes extracted from archives
+export USPTO_MAX_EXTRACT_SIZE=10737418240
 ```
 
 ## Debugging with Raw Data Preservation
@@ -150,7 +182,7 @@ if response.raw_data:
 - Raw data is stored in the `raw_data` attribute of response objects
 - This increases memory usage as both parsed and raw data are kept
 - Only enable when needed for debugging - disable for better performance
-- All response models support `raw_data` when this flag is enabled
+- Response models support `raw_data` when this flag is enabled (except StatusCodeSearchResponse)
 
 **Example: Debugging a missing field**
 
@@ -180,6 +212,7 @@ All warnings inherit from `USPTODataWarning`:
 - `USPTOBooleanParseWarning`: Y/N boolean string parsing failures
 - `USPTOTimezoneWarning`: Timezone-related issues
 - `USPTOEnumParseWarning`: Enum value parsing failures
+- `USPTODataMismatchWarning`: API returns data with different identifier than requested
 
 **Controlling Warnings**
 
@@ -190,7 +223,8 @@ from pyUSPTO.warnings import (
     USPTODateParseWarning,
     USPTOBooleanParseWarning,
     USPTOTimezoneWarning,
-    USPTOEnumParseWarning
+    USPTOEnumParseWarning,
+    USPTODataMismatchWarning
 )
 
 # Suppress all pyUSPTO data warnings
@@ -210,3 +244,31 @@ warnings.filterwarnings('always', category=USPTODataWarning)
 ```
 
 The library's permissive parsing philosophy returns `None` for fields that cannot be parsed, allowing you to retrieve partial data even when some fields have issues. Warnings inform you when this happens without stopping execution.
+
+## Archive Extraction Safety
+
+Download methods that accept `extract=True` (e.g., `BulkDataClient.download_file`) automatically extract archive files (tar.gz, zip). The extraction includes the following protections:
+
+- **Path traversal protection**: Archive members with paths that resolve outside the extraction directory are rejected.
+- **Size limits**: Set `max_extract_size` on `HTTPConfig` to cap the total bytes extracted, protecting against zip bombs or file system size limitations.
+
+```python
+from pyUSPTO import USPTOConfig, HTTPConfig, BulkDataClient
+
+http_config = HTTPConfig(
+    max_extract_size=10 * 1024 * 1024 * 1024  # 10 GB
+)
+config = USPTOConfig(api_key="your_key", http_config=http_config)
+client = BulkDataClient(config=config)
+
+# Extraction will raise ValueError if total extracted size exceeds 10 GB
+client.download_file(product_file, destination="/tmp", extract=True)
+```
+
+Or via environment variable:
+
+```bash
+export USPTO_MAX_EXTRACT_SIZE=10737418240  # 10 GB
+```
+
+By default, `extract` is `False` on `BulkDataClient.download_file` and there is no size limit.

{pyuspto-0.3.4 → pyuspto-0.4.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.3.4
-Summary: A Modern Python client for accessing United Stated Patent and Trademark Office (USPTO) Open Data Portal (ODP) APIs.
+Version: 0.4.1
+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
 Project-URL: GitHub, https://github.com/DunlapCoddingPC/pyUSPTO
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.32.5
 Requires-Dist: typing-extensions>=4.15.0; python_version < "3.11"
-Requires-Dist: tzdata>=2025.2
+Requires-Dist: tzdata>=2025.3
 Provides-Extra: dev
 Requires-Dist: pytest>=9.0.2; extra == "dev"
 Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
@@ -55,7 +55,7 @@ Requires-Dist: sphinx-copybutton>=0.5.2; extra == "dev"
 Requires-Dist: myst-parser>=4.0.1; extra == "dev"
 Requires-Dist: mypy>=1.19.0; extra == "dev"
 Requires-Dist: types-requests>=2.32.4; extra == "dev"
-Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: ruff>=0.15.0; extra == "dev"
 Dynamic: license-file
 
 # pyUSPTO
@@ -70,7 +70,7 @@ A Python client library for interacting with the United Stated Patent and Tradem
 This package provides clients for interacting with the USPTO Bulk Data API, Patent Data API, Final Petition Decisions API, and PTAB (Patent Trial and Appeal Board) APIs.
 
 > [!IMPORTANT]
-> The USPTO is in the process of moving their API. This package is only concerned with the new API. The [old API](https://developer.uspto.gov/) will be retired at the end of 2025.
+> The USPTO is in the process of moving their Developer API. This package is only concerned with the new API. The [old API](https://developer.uspto.gov/) was officially retired at the end of 2025; however, some products have not yet been fully transitioned to the Open Data Portal API. The USPTO expects the remaining products to be transitioned to the Open Data Portal in early 2026.
 
 ## Quick Start
 
@@ -84,10 +84,11 @@ pip install pyUSPTO
 > You must have an API key for the [USPTO Open Data Portal API](https://data.uspto.gov/myodp/landing).
 
 ```python
-from pyUSPTO import PatentDataClient
+from pyUSPTO import PatentDataClient, USPTOConfig
 
-# Initialize with your API key
-client = PatentDataClient(api_key="your_api_key_here")
+# Initialize with config
+config = USPTOConfig(api_key="your_api_key_here")
+client = PatentDataClient(config=config)
 
 # Search for patent applications
 results = client.search_applications(inventor_name_q="Smith", limit=10)
@@ -96,56 +97,12 @@ print(f"Found {results.count} applications")
 
 ## Configuration
 
-All clients can be configured using one of three methods:
-
-### Method 1: Direct API Key Initialization
-
-> [!NOTE]
-> This method is convenient for quick scripts but not recommended. Consider using environment variables instead.
+All clients require a `USPTOConfig` object. You can create one from environment variables (recommended) or by passing the API key directly.
 
-```python
-from pyUSPTO import (
-    BulkDataClient,
-    PatentDataClient,
-    FinalPetitionDecisionsClient,
-    PTABTrialsClient,
-    PTABAppealsClient,
-    PTABInterferencesClient
-)
-
-patent_client = PatentDataClient(api_key="your_api_key_here")
-bulk_client = BulkDataClient(api_key="your_api_key_here")
-petition_client = FinalPetitionDecisionsClient(api_key="your_api_key_here")
-trials_client = PTABTrialsClient(api_key="your_api_key_here")
-appeals_client = PTABAppealsClient(api_key="your_api_key_here")
-interferences_client = PTABInterferencesClient(api_key="your_api_key_here")
-```
-
-### Method 2: Using USPTOConfig
-
-```python
-from pyUSPTO import (
-    BulkDataClient,
-    PatentDataClient,
-    FinalPetitionDecisionsClient,
-    PTABTrialsClient,
-    PTABAppealsClient,
-    PTABInterferencesClient
-)
-
-from pyUSPTO.config import USPTOConfig
-
-config = USPTOConfig(api_key="your_api_key_here")
-
-patent_client = PatentDataClient(config=config)
-bulk_client = BulkDataClient(config=config)
-petition_client = FinalPetitionDecisionsClient(config=config)
-trials_client = PTABTrialsClient(config=config)
-appeals_client = PTABAppealsClient(config=config)
-interferences_client = PTABInterferencesClient(config=config)
-```
+> [!TIP]
+> `USPTOConfig` manages an underlying HTTP session. For long-running applications, use it as a context manager (`with USPTOConfig(...) as config:`) or call `config.close()` when done. See [ADVANCED.md](ADVANCED.md#session-lifecycle) for details.
 
-### Method 3: Environment Variables (Recommended)
+### Environment Variables (Recommended)
 
 Set the environment variable in your shell:
 
@@ -162,9 +119,9 @@ from pyUSPTO import (
     FinalPetitionDecisionsClient,
     PTABTrialsClient,
     PTABAppealsClient,
-    PTABInterferencesClient
+    PTABInterferencesClient,
+    USPTOConfig,
 )
-from pyUSPTO.config import USPTOConfig
 
 # Load configuration from environment
 config = USPTOConfig.from_env()
@@ -177,7 +134,17 @@ appeals_client = PTABAppealsClient(config=config)
 interferences_client = PTABInterferencesClient(config=config)
 ```
 
-## API Usage Examples
+### Direct API Key
+
+Alternatively, you can pass your API key directly when creating the config:
+
+```python
+from pyUSPTO import USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+```
+
+## Client Usage Examples
 
 > [!TIP]
 > For comprehensive examples with detailed explanations, see the [`examples/`](examples/) directory.
@@ -185,9 +152,10 @@ interferences_client = PTABInterferencesClient(config=config)
 ### Patent Data API
 
 ```python
-from pyUSPTO import PatentDataClient
+from pyUSPTO import PatentDataClient, USPTOConfig
 
-client = PatentDataClient(api_key="your_api_key_here")
+config = USPTOConfig(api_key="your_api_key_here")
+client = PatentDataClient(config=config)
 
 # Search for applications by inventor name
 response = client.search_applications(inventor_name_q="Smith", limit=2)
@@ -199,14 +167,50 @@ if app.application_meta_data:
     print(f"Title: {app.application_meta_data.invention_title}")
 ```
 
+`PatentDataClient` also provides convenience methods for common lookups:
+
+```python
+# Look up a patent wrapper by any identifier type (you must use keyword names).
+wrapper = client.get_IFW_metadata(application_number="18/045,436")
+wrapper = client.get_IFW_metadata(patent_number="11,234,567")
+wrapper = client.get_IFW_metadata(publication_number="2023/0012345")
+wrapper = client.get_IFW_metadata(PCT_app_number="PCT/US24/12345")
+
+# Look up USPTO status codes
+status_codes = client.get_status_codes()
+```
+
 See [`examples/patent_data_example.py`](examples/patent_data_example.py) for detailed examples including downloading documents and publications.
 
+### Bulk Data API
+
+```python
+from pyUSPTO import BulkDataClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = BulkDataClient(config=config)
+
+# Search for bulk data products
+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"  {product.product_title_text} ({product.product_identifier})")
+
+# Get a specific product with its files
+product = client.get_product_by_id("PTGRXML", include_files=True, latest=True)
+print(f"Product: {product.product_title_text}")
+```
+
+See [`examples/bulk_data_example.py`](examples/bulk_data_example.py) for detailed examples including file downloads and archive extraction.
+
 ### Final Petition Decisions API
 
 ```python
-from pyUSPTO import FinalPetitionDecisionsClient
+from pyUSPTO import FinalPetitionDecisionsClient, USPTOConfig
 
-client = FinalPetitionDecisionsClient(api_key="your_api_key_here")
+config = USPTOConfig(api_key="your_api_key_here")
+client = FinalPetitionDecisionsClient(config=config)
 
 # Search for petition decisions
 response = client.search_decisions(
@@ -227,9 +231,10 @@ See [`examples/petition_decisions_example.py`](examples/petition_decisions_examp
 ### PTAB Trials API
 
 ```python
-from pyUSPTO import PTABTrialsClient
+from pyUSPTO import PTABTrialsClient, USPTOConfig
 
-client = PTABTrialsClient(api_key="your_api_key_here")
+config = USPTOConfig(api_key="your_api_key_here")
+client = PTABTrialsClient(config=config)
 
 # Search for IPR proceedings
 response = client.search_proceedings(
@@ -254,9 +259,10 @@ See [`examples/ptab_trials_example.py`](examples/ptab_trials_example.py) for det
 ### PTAB Appeals API
 
 ```python
-from pyUSPTO import PTABAppealsClient
+from pyUSPTO import PTABAppealsClient, USPTOConfig
 
-client = PTABAppealsClient(api_key="your_api_key_here")
+config = USPTOConfig(api_key="your_api_key_here")
+client = PTABAppealsClient(config=config)
 
 # Search for appeal decisions
 response = client.search_decisions(
@@ -273,9 +279,10 @@ See [`examples/ptab_appeals_example.py`](examples/ptab_appeals_example.py) for d
 ### PTAB Interferences API
 
 ```python
-from pyUSPTO import PTABInterferencesClient
+from pyUSPTO import PTABInterferencesClient, USPTOConfig
 
-client = PTABInterferencesClient(api_key="your_api_key_here")
+config = USPTOConfig(api_key="your_api_key_here")
+client = PTABInterferencesClient(config=config)
 
 # Search for interference decisions
 response = client.search_decisions(
@@ -293,60 +300,7 @@ Full documentation may be found on [Read the Docs](https://pyuspto.readthedocs.i
 
 ## Data Models
 
-The library uses Python dataclasses to represent API responses. All data models include type annotations for attributes and methods, making them fully compatible with static type checkers.
-
-#### Bulk Data API
-
-- `BulkDataResponse`: Top-level response from the API
-- `BulkDataProduct`: Information about a specific product
-- `ProductFileBag`: Container for file data elements
-- `FileData`: Information about an individual file
-
-#### Patent Data API
-
-- `PatentDataResponse`: Top-level response from the API
-- `PatentFileWrapper`: Information about a patent application
-- `ApplicationMetaData`: Metadata about a patent application
-- `Address`: Represents an address in the patent data
-- `Person`, `Applicant`, `Inventor`, `Attorney`: Person-related data classes
-- `Assignment`, `Assignor`, `Assignee`: Assignment-related data classes
-- `Continuity`, `ParentContinuity`, `ChildContinuity`: Continuity-related data classes
-- `PatentTermAdjustmentData`: Patent term adjustment information
-- And many more specialized classes for different aspects of patent data
-
-#### Final Petition Decisions API
-
-- `PetitionDecisionResponse`: Top-level response from the API
-- `PetitionDecision`: Complete information about a petition decision
-- `PetitionDecisionDocument`: Document associated with a petition decision
-- `DocumentDownloadOption`: Download options for petition documents
-- `DecisionTypeCode`: Enum for petition decision types
-- `DocumentDirectionCategory`: Enum for document direction categories
-
-#### PTAB Trials API
-
-- `PTABTrialProceedingResponse`: Top-level response from the API
-- `PTABTrialProceeding`: Information about a PTAB trial proceeding (IPR, PGR, CBM, DER)
-- `PTABTrialDocument`: Document associated with a trial proceeding
-- `PTABTrialDecision`: Decision information for a trial proceeding
-- `RegularPetitionerData`, `RespondentData`, `DerivationPetitionerData`: Party data for different trial types
-- `PTABTrialMetaData`: Trial metadata and status information
-
-#### PTAB Appeals API
-
-- `PTABAppealResponse`: Top-level response from the API
-- `PTABAppealDecision`: Ex parte appeal decision information
-- `AppellantData`: Appellant information and application details
-- `PTABAppealMetaData`: Appeal metadata and filing information
-- `PTABAppealDocumentData`: Document and decision details
-
-#### PTAB Interferences API
-
-- `PTABInterferenceResponse`: Top-level response from the API
-- `PTABInterferenceDecision`: Interference proceeding decision information
-- `SeniorPartyData`, `JuniorPartyData`, `AdditionalPartyData`: Party data classes
-- `PTABInterferenceMetaData`: Interference metadata and status information
-- `PTABInterferenceDocumentData`: Document and outcome details
+The library uses Python dataclasses to represent API responses. All data models include type annotations and are fully compatible with static type checkers. For a complete list of all data models, see the [API Reference documentation](https://pyuspto.readthedocs.io/en/latest/api/models/index.html).
 
 ## Advanced Topics