Bulk improvements

[dpieski]

Architecture Improvements: Enhanced Resiliency, Efficiency, and Documentation

Overview

This PR implements improvements to the pyUSPTO client library, enhancing connection management, retry behavior, session handling, and download performance. README examples have also been updated.

Key Improvements

1. Connection Lifecycle Management

All clients now support Python's with statement for automatic resource cleanup and explicit close() method.

with PatentDataClient(api_key="...") as client:
    results = client.search_applications(...)

2. Enhanced Retry Behavior

POST requests now retry on transient failures (429, 500, 502, 503, 504).

3. Session Sharing/Injection

Multiple clients can share a single requests.Session for better connection reuse and resource efficiency.

shared_session = requests.Session()
patent_client = PatentDataClient(api_key="...", session=shared_session)
bulk_client = BulkDataClient(api_key="...", session=shared_session)

4. Configurable Download Chunk Size

Adjust download chunk size via HTTPConfig.download_chunk_size or USPTO_DOWNLOAD_CHUNK_SIZE environment variable.

5. POST Support in Pagination

All paginate_*() methods now accept post_body parameter, supporting both flat and nested pagination structures.

for app in client.paginate_applications(
    post_body={"q": "applicationMetaData.inventionTitle:AI", "pagination": {"limit": 100}}
):
    process(app)

6. README Examples Update

All README examples now use code from the examples/ directory.

Testing

• 602 tests passing
• 100% coverage maintained

Files Changed

• Core: base.py (+208), http_config.py (+26), config.py (+7)
• Clients: All 6 client files updated (patent_data, bulk_data, petition_decisions, ptab_trials, ptab_appeals, ptab_interferences)
• Docs: README.md (265 changes), example files
• Tests: Updated all test files with comprehensive coverage