pyUSPTO 0.5.3__tar.gz → 0.5.5__tar.gz

pyuspto-0.5.5/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,19 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "1.3.5",
+      "resolved": "ghcr.io/devcontainers/features/git@sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251",
+      "integrity": "sha256:27905dc196c01f77d6ba8709cb82eeaf330b3b108772e2f02d1cd0d826de1251"
+    },
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "2.1.0",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857",
+      "integrity": "sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857"
+    },
+    "ghcr.io/devcontainers/features/powershell:2.0.2": {
+      "version": "2.0.2",
+      "resolved": "ghcr.io/devcontainers/features/powershell@sha256:82ea3880c5706ac3963f1b5e940a7f5871835393a5472f80008148b995d58d61",
+      "integrity": "sha256:82ea3880c5706ac3963f1b5e940a7f5871835393a5472f80008148b995d58d61"
+    }
+  }
+}

{pyuspto-0.5.3 → pyuspto-0.5.5}/.devcontainer/devcontainer.json

@@ -3,7 +3,10 @@
   "build": { "dockerfile": "Dockerfile" },
   "features": {
     "ghcr.io/devcontainers/features/git:1": {},
-    "ghcr.io/devcontainers/features/node:2": {}
+    "ghcr.io/devcontainers/features/node:2": {},
+    "ghcr.io/devcontainers/features/powershell:2.0.2": {
+        "version": "latest"
+    }
   },
   "mounts": [
     "source=pyuspto-claude-home,target=/home/vscode/.claude,type=volume"

{pyuspto-0.5.3 → pyuspto-0.5.5}/.github/workflows/codeql.yml

@@ -55,7 +55,7 @@ jobs:
         # 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
+      uses: actions/checkout@v7
 
     # Add any setup steps before running the `github/codeql-action/init` action.
     # This includes steps like installing compilers or runtimes (`actions/setup-node`

{pyuspto-0.5.3 → pyuspto-0.5.5}/.github/workflows/publish-docs.yaml

@@ -15,9 +15,9 @@ jobs:
     name: Build documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: "3.14"
       - name: Install dependencies

{pyuspto-0.5.3 → pyuspto-0.5.5}/.github/workflows/publish-to-test-pypi.yml

@@ -16,11 +16,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         persist-credentials: false
     - name: Set up Python
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: "3.x"
     - name: Install pypa/build

{pyuspto-0.5.3 → pyuspto-0.5.5}/.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@v6
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -32,7 +32,7 @@ jobs:
           pytest tests/ --cov=src/pyUSPTO
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           fail_ci_if_error: false
 
@@ -40,10 +40,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: "3.14"
 

{pyuspto-0.5.3 → pyuspto-0.5.5}/.gitignore

@@ -23,3 +23,4 @@ run_integration_tests.py
 CLAUDE.md
 docs/build/
 .devcontainer/Dockerfile
+.claude/skills/

{pyuspto-0.5.3 → pyuspto-0.5.5}/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.5.5] - 2026-07-22
+
+### Added
+
+- `PatentDataClient.get_firm_portfolio(customer_numbers, ...)` — helper that searches a law firm's portfolio across one or more USPTO Customer Numbers. Builds a single Lucene `OR` query, applies a named field preset by default, and returns a `PatentDataResponse`. Pairs with `get_application_metadata` / `get_application_by_number` for per-application drill-down.
+- `FIELD_PRESETS` constant (exported from `pyUSPTO`) — three named field sets for `get_firm_portfolio`'s `fields` argument: `"minimal"` (8 firm-internal identifiers), `"portfolio"` (16 fields for status + deadline derivation, default), and `"full_meta"` (uses the API's `applicationMetaData` shorthand for the entire 27-key metadata object, ~7.5× payload reduction vs. the un-fielded default).
+- Multi-value `customer_number_q` and `status_code_q` on `search_applications` and `get_search_results` — accept a single value or a list; lists are OR-joined as `field:(a OR b)`.
+- New `status_date_from_q` / `status_date_to_q` on `search_applications` and `get_search_results` — date-range filters against `applicationMetaData.applicationStatusDate`, mirroring the existing `filing_date` and `grant_date` range params. Useful for bounding the deadline-coming-due horizon.
+
+## [0.5.4] - 2026-05-27
+
+### Changed
+
+- **Breaking**: `sanitize_application_number` now emits the standardized 15-character PCT format (`PCT` + 2-char country + 4-digit year + 6-digit zero-padded serial, e.g. `PCTUS2024012345`) per USPTO ODP Release 3.6 (2026-04-10). Previously emitted a non-standard 12-character form (e.g. `PCTUS2412345`). Affects every endpoint that takes a PCT application number, including `get_pct`, `get_application_by_number`, and `get_IFW_metadata(PCT_app_number=...)`. 2-digit year inputs are expanded via a sliding window (YY≥78 → 19YY, else 20YY). Legacy 12-character PCT strings are no longer accepted as input.
+- `USPTOConfig` now applies user > env > default precedence uniformly across all fields. Previously only `api_key` fell back to its environment variable; base URLs and `HTTPConfig` ignored env in the constructor. Env reading is consolidated in an internal `_env_values()` helper shared by `__init__` and `from_env`.
+
+### Deprecated
+
+- `Address.country_or_state_code` — USPTO ODP Release 3.6 removed `countryOrStateCode` from the Patent Assignment API response; the location data now lives in `geographicRegionCode` (already exposed as `Address.geographic_region_code`). The attribute remains for backward compatibility and will be `None` for responses from updated endpoints.
+
+### Fixed
+
+- `USPTO_API_KEY=""` was stored as `""` instead of `None`, breaking `is None` checks. Empty-string constructor arguments are now treated as no-value and fall back to env.
+
+## [0.5.3] - 2026-05-13
+
+### Changed
+
+- Maintenance release: dependency updates only (including urllib3 v2.7.0 security update); no library code changes.
+
+## [0.5.2] - 2026-04-16
+
+### Added
+
+- `PatentDataClient.stream_document(document, format)` — returns a streaming `requests.Response` the caller consumes via `iter_content()` or `iter_lines()`. Accepts the same `format` argument (`DocumentMimeType` enum or MIME string) as `download_document` and raises the same `FormatNotAvailableError` on an unavailable format. The returned response is the caller's responsibility — use as a context manager or call `.close()` when finished.
+- Streaming download example in `examples/patent_data_example.py`
+- Bulk Data product identifier reference table in the documentation
+
+### Changed
+
+- `stream_document` and `download_document` now share format resolution through an internal `_resolve_document_format` helper, so both methods raise identical errors for missing formats or missing download URLs. No changes to existing `download_document` behavior.
+
+## [0.5.1] - 2026-03-30
+
+### Added
+
+- `OAActionsClient` — Office Action Text Retrieval API (v1): full-text office action documents including body text and structured section data (§101/102/103/112 rejections, citations, etc.)
+- `OARejectionsClient` — Office Action Rejections API (v2): rejection-level records with rejection type indicators (`hasRej101/102/103/112/DP`), claim arrays, and examiner classification metadata
+- `OACitationsClient` — Office Action Citations API: enriched citation records from office actions including cited document identifiers, legal section codes, and examiner-cited indicators
+- Config and environment variable support for the three new base URLs (`USPTO_OA_ACTIONS_BASE_URL`, `USPTO_OA_REJECTIONS_BASE_URL`, `USPTO_OA_CITATIONS_BASE_URL`)
+
+## [0.5.0] - 2026-03-27
+
+### Added
+
+- `EnrichedCitationsClient` for the USPTO Enriched Cited Reference Metadata API (v3) — citation data extracted from patent office actions using AI/NLP, including citation category codes (X/Y/A/etc.), passage locations in the prior art, rejected claims, and examiner vs. applicant citation indicators
+- Client methods: `search_citations()` (POST-based search with convenience parameters), `paginate_citations()` (auto-paginating iterator), and `get_fields()`
+- Models: `EnrichedCitation` (21 fields), `EnrichedCitationResponse`, `EnrichedCitationFieldsResponse`
+
 ## [0.4.5] - 2026-03-11
 
 ### Changed

{pyuspto-0.5.3 → pyuspto-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.5.3
+Version: 0.5.5
 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
@@ -201,7 +201,7 @@ if app.application_meta_data:
 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")
+wrapper = client.get_IFW_metadata(PCT_app_number="PCT/US2024/012345")
 
 # Look up USPTO status codes
 status_codes = client.get_status_codes()

{pyuspto-0.5.3 → pyuspto-0.5.5}/README.md

@@ -134,7 +134,7 @@ if app.application_meta_data:
 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")
+wrapper = client.get_IFW_metadata(PCT_app_number="PCT/US2024/012345")
 
 # Look up USPTO status codes
 status_codes = client.get_status_codes()

{pyuspto-0.5.3 → pyuspto-0.5.5}/examples/patent_data_example.py

@@ -315,3 +315,31 @@ print(
 )
 for code_obj in status_code_response.status_code_bag:
     print(f"  - Code: {code_obj.code}, Description: {code_obj.description}")
+
+print("-" * 40)
+print("Example 9: Firm portfolio across multiple Customer Numbers")
+print("-" * 40)
+
+# get_firm_portfolio builds one Lucene OR query across all provided Customer
+# Numbers, applies the "portfolio" field preset by default, and returns a
+# PatentDataResponse. Combine with status_date_from to bound the deadline
+# horizon ("show me cases whose status changed since X").
+from collections import Counter
+
+portfolio_response = client.get_firm_portfolio(
+    customer_numbers=[30589, 174793],
+    status_date_from="2025-01-01",
+    sort="applicationMetaData.applicationStatusDate desc",
+    limit=25,
+)
+print(f"Total matching applications across both Customer Numbers: {portfolio_response.count}")
+
+status_counter: Counter[str] = Counter()
+for wrapper in portfolio_response.patent_file_wrapper_data_bag:
+    meta = wrapper.application_meta_data
+    if meta and meta.application_status_code is not None:
+        status_counter[str(meta.application_status_code)] += 1
+
+print("Status-code tally for the page:")
+for code, n in status_counter.most_common():
+    print(f"  {code}: {n}")

{pyuspto-0.5.3 → pyuspto-0.5.5}/requirements-dev.txt

@@ -8,22 +8,22 @@ alabaster==1.0.0
     # via sphinx
 babel==2.18.0
     # via sphinx
-certifi==2026.4.22
+certifi==2026.6.17
     # via requests
-charset-normalizer==3.4.7
+charset-normalizer==3.4.9
     # via requests
 colorama==0.4.6
     # via
     #   pytest
     #   sphinx
-coverage==7.14.0
+coverage==7.15.2
     # via pytest-cov
 docutils==0.22.4
     # via
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.15
+idna==3.18
     # via requests
 imagesize==2.0.0
     # via sphinx
@@ -33,7 +33,7 @@ jinja2==3.1.6
     # via
     #   myst-parser
     #   sphinx
-librt==0.11.0
+librt==0.13.0
     # via mypy
 markdown-it-py==4.2.0
     # via
@@ -45,7 +45,7 @@ mdit-py-plugins==0.6.1
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-mypy==2.1.0
+mypy==2.3.0
     # via pyuspto
 mypy-extensions==1.1.0
     # via mypy
@@ -65,7 +65,7 @@ pygments==2.20.0
     # via
     #   pytest
     #   sphinx
-pytest==9.0.3
+pytest==9.1.1
     # via
     #   pytest-cov
     #   pytest-mock
@@ -76,16 +76,16 @@ pytest-mock==3.15.1
     # via pyuspto
 pyyaml==6.0.3
     # via myst-parser
-requests==2.34.0
+requests==2.34.2
     # via
     #   pyUSPTO (pyproject.toml)
     #   pyuspto
     #   sphinx
 roman-numerals==4.1.0
     # via sphinx
-ruff==0.15.12
+ruff==0.15.22
     # via pyuspto
-snowballstemmer==3.0.1
+snowballstemmer==3.1.1
     # via sphinx
 sphinx==9.1.0
     # via
@@ -95,7 +95,7 @@ sphinx==9.1.0
     #   sphinx-copybutton
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-autodoc-typehints==3.10.2
+sphinx-autodoc-typehints==3.13.0
     # via pyuspto
 sphinx-copybutton==0.5.2
     # via pyuspto
@@ -115,13 +115,13 @@ sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
-types-requests==2.33.0.20260513
+types-requests==2.33.0.20260712
     # via pyuspto
-typing-extensions==4.15.0
+typing-extensions==4.16.0
     # via
     #   mypy
     #   pyuspto
-tzdata==2026.2
+tzdata==2026.3
     # via
     #   pyUSPTO (pyproject.toml)
     #   pyuspto

{pyuspto-0.5.3 → pyuspto-0.5.5}/requirements.txt

@@ -4,15 +4,15 @@
 #
 #    pip-compile --output-file=requirements.txt --strip-extras pyproject.toml
 #
-certifi==2026.4.22
+certifi==2026.6.17
     # via requests
-charset-normalizer==3.4.7
+charset-normalizer==3.4.9
     # via requests
-idna==3.15
+idna==3.18
     # via requests
-requests==2.34.0
+requests==2.34.2
     # via pyUSPTO (pyproject.toml)
-tzdata==2026.2
+tzdata==2026.3
     # via pyUSPTO (pyproject.toml)
 urllib3==2.7.0
     # via

{pyuspto-0.5.3 → pyuspto-0.5.5}/src/pyUSPTO/__init__.py

@@ -16,7 +16,7 @@ from pyUSPTO.clients.enriched_citations import EnrichedCitationsClient
 from pyUSPTO.clients.oa_actions import OAActionsClient
 from pyUSPTO.clients.oa_citations import OACitationsClient
 from pyUSPTO.clients.oa_rejections import OARejectionsClient
-from pyUSPTO.clients.patent_data import PatentDataClient
+from pyUSPTO.clients.patent_data import FIELD_PRESETS, PatentDataClient
 from pyUSPTO.clients.petition_decisions import FinalPetitionDecisionsClient
 from pyUSPTO.clients.ptab_appeals import PTABAppealsClient
 from pyUSPTO.clients.ptab_interferences import PTABInterferencesClient
@@ -138,6 +138,7 @@ __all__ = [
     "FileData",
     # Patent Data API
     "PatentDataClient",
+    "FIELD_PRESETS",
     "ApplicationContinuityData",
     "PatentDataResponse",
     "PatentFileWrapper",