Add Document Filtering to Patent File Wrapper API

[dpieski]

Overview

USPTO API Release 2.0 (May 2025) added the capability to filter Patent File Wrapper documents by document codes and official dates. The current get_application_documents() method does not support these filter parameters.

Current Implementation

Location: src/pyUSPTO/clients/patent_data.py:606

Required Changes

1. Update Method Signature

Add optional filter parameters:

• document_codes: Optional[List[str]] = None
• official_date_from: Optional[str] = None
• official_date_to: Optional[str] = None

2. Implementation Details

• Add query parameters to API request for filters
• Document expected date format (verify with API, likely YYYY-MM-DD)
• Handle empty/None filter values appropriately
• Maintain backward compatibility (all filters optional)

3. Documentation Updates

• Update docstring with detailed parameter descriptions
• Document available document codes (if documented by USPTO)
• Add examples of filtered document retrieval
• Update API reference in Sphinx docs
• Add to examples/patent_data_example.py

4. Testing Updates

Add tests for:

• Filtering by document codes (single and multiple)
• Filtering by date ranges
• Combined filters (codes + dates)
• Invalid/empty filter values
• Backward compatibility

API Information

• Release Version: 2.0 (2025-05-15)
• Filter Parameters: documentCodes, officialDates

Priority

Medium

Estimated Effort

Small-Medium (few hours to 1 day)