pyUSPTO 0.5.4__tar.gz → 0.5.6__tar.gz

pyuspto-0.5.6/.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.4 → pyuspto-0.5.6}/.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.4 → pyuspto-0.5.6}/.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.4 → pyuspto-0.5.6}/.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.4 → pyuspto-0.5.6}/.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.4 → pyuspto-0.5.6}/CHANGELOG.md

@@ -5,16 +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).
 
-## [Unreleased]
+## [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.4 → pyuspto-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.5.4
+Version: 0.5.6
 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.4 → pyuspto-0.5.6}/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.4 → pyuspto-0.5.6}/requirements-dev.txt

@@ -8,22 +8,22 @@ alabaster==1.0.0
     # via sphinx
 babel==2.18.0
     # via sphinx
-certifi==2026.5.20
+certifi==2026.7.22
     # via requests
-charset-normalizer==3.4.7
+charset-normalizer==3.5.1
     # via requests
 colorama==0.4.6
     # via
     #   pytest
     #   sphinx
-coverage==7.14.1
+coverage==7.15.4
     # via pytest-cov
 docutils==0.22.4
     # via
     #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
-idna==3.16
+idna==3.19
     # 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.15.0
     # via mypy
 markdown-it-py==4.2.0
     # via
@@ -45,13 +45,13 @@ mdit-py-plugins==0.6.1
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-mypy==2.1.0
+mypy==2.3.1
     # via pyuspto
 mypy-extensions==1.1.0
     # via mypy
 myst-parser==5.1.0
     # via pyuspto
-packaging==26.2
+packaging==26.3
     # via
     #   pytest
     #   sphinx
@@ -61,11 +61,11 @@ pluggy==1.6.0
     # via
     #   pytest
     #   pytest-cov
-pygments==2.20.0
+pygments==2.21.0
     # via
     #   pytest
     #   sphinx
-pytest==9.0.3
+pytest==9.1.1
     # via
     #   pytest-cov
     #   pytest-mock
@@ -83,9 +83,9 @@ requests==2.34.2
     #   sphinx
 roman-numerals==4.1.0
     # via sphinx
-ruff==0.15.14
+ruff==0.16.4
     # via pyuspto
-snowballstemmer==3.1.0
+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.2
     # 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.20260518
+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.4 → pyuspto-0.5.6}/requirements.txt

@@ -4,15 +4,15 @@
 #
 #    pip-compile --output-file=requirements.txt --strip-extras pyproject.toml
 #
-certifi==2026.5.20
+certifi==2026.7.22
     # via requests
-charset-normalizer==3.4.7
+charset-normalizer==3.5.1
     # via requests
-idna==3.16
+idna==3.19
     # via requests
 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.4 → pyuspto-0.5.6}/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",

{pyuspto-0.5.4 → pyuspto-0.5.6}/src/pyUSPTO/clients/patent_data.py

@@ -39,6 +39,57 @@ from pyUSPTO.models.patent_data import (
 from pyUSPTO.warnings import USPTODataMismatchWarning
 
 
+def _or_clause(field: str, value: int | str | list[int | str]) -> str:
+    """Build a Lucene clause for a single value or a list of values.
+
+    Single value → ``field:val``. List → ``field:(v1 OR v2 ...)``.
+    """
+    if isinstance(value, list):
+        return f"{field}:({' OR '.join(str(v) for v in value)})"
+    return f"{field}:{value}"
+
+
+FIELD_PRESETS: dict[str, list[str]] = {
+    "minimal": [
+        "applicationNumberText",
+        "applicationMetaData.customerNumber",
+        "applicationMetaData.applicationStatusCode",
+        "applicationMetaData.applicationStatusDate",
+        "applicationMetaData.filingDate",
+        "applicationMetaData.firstApplicantName",
+        "applicationMetaData.firstInventorName",
+        "applicationMetaData.docketNumber",
+    ],
+    "portfolio": [
+        "applicationNumberText",
+        "applicationMetaData.customerNumber",
+        "applicationMetaData.applicationStatusCode",
+        "applicationMetaData.applicationStatusDescriptionText",
+        "applicationMetaData.applicationStatusDate",
+        "applicationMetaData.filingDate",
+        "applicationMetaData.effectiveFilingDate",
+        "applicationMetaData.patentNumber",
+        "applicationMetaData.grantDate",
+        "applicationMetaData.inventionTitle",
+        "applicationMetaData.firstApplicantName",
+        "applicationMetaData.firstInventorName",
+        "applicationMetaData.docketNumber",
+        "applicationMetaData.examinerNameText",
+        "applicationMetaData.applicationTypeCode",
+        "applicationMetaData.applicationTypeLabelName",
+    ],
+    # ``full_meta`` uses the USPTO API's top-level shorthand: passing
+    # ``applicationMetaData`` returns the entire 27-key object.
+    # ``applicationNumberText`` is added explicitly because it lives at the
+    # wrapper top level (outside applicationMetaData) and would otherwise be
+    # stripped. Payload is roughly 7.5x smaller than the un-fielded default.
+    "full_meta": [
+        "applicationNumberText",
+        "applicationMetaData",
+    ],
+}
+
+
 class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
     """Client for interacting with the USPTO Patent Data API."""
 
@@ -267,10 +318,14 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         inventor_name_q: str | None = None,
         applicant_name_q: str | None = None,
         assignee_name_q: str | None = None,
+        customer_number_q: int | str | list[int | str] | None = None,
+        status_code_q: int | str | list[int | str] | None = None,
         filing_date_from_q: str | None = None,
         filing_date_to_q: str | None = None,
         grant_date_from_q: str | None = None,
         grant_date_to_q: str | None = None,
+        status_date_from_q: str | None = None,
+        status_date_to_q: str | None = None,
         classification_q: str | None = None,
         earliestPublicationNumber_q: str | None = None,
         pctPublicationNumber_q: str | None = None,
@@ -279,6 +334,11 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         """Search for patent applications.
 
         Can perform a GET request based on OpenAPI query parameters or a POST request if post_body is specified.
+
+        ``customer_number_q`` and ``status_code_q`` accept a single value or a list;
+        a list builds a Lucene ``field:(a OR b)`` clause. ``status_date_from_q`` /
+        ``status_date_to_q`` follow the same date-range pattern as
+        ``filing_date_from_q`` / ``filing_date_to_q``.
         """
         endpoint = self.ENDPOINTS["search_applications"]
 
@@ -325,6 +385,18 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                         else assignee_name_q
                     )
                     q_parts.append(f"assignmentBag.assigneeBag.assigneeNameText:{v}")
+                if customer_number_q is not None:
+                    q_parts.append(
+                        _or_clause(
+                            "applicationMetaData.customerNumber", customer_number_q
+                        )
+                    )
+                if status_code_q is not None:
+                    q_parts.append(
+                        _or_clause(
+                            "applicationMetaData.applicationStatusCode", status_code_q
+                        )
+                    )
                 if classification_q:
                     v = (
                         f'"{classification_q}"'
@@ -364,6 +436,19 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                 elif grant_date_to_q:
                     q_parts.append(f"applicationMetaData.grantDate:<={grant_date_to_q}")
 
+                if status_date_from_q and status_date_to_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:[{status_date_from_q} TO {status_date_to_q}]"
+                    )
+                elif status_date_from_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:>={status_date_from_q}"
+                    )
+                elif status_date_to_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:<={status_date_to_q}"
+                    )
+
                 if q_parts:
                     final_q = " AND ".join(q_parts)
 
@@ -409,10 +494,14 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         inventor_name_q: str | None = None,
         applicant_name_q: str | None = None,
         assignee_name_q: str | None = None,
+        customer_number_q: int | str | list[int | str] | None = None,
+        status_code_q: int | str | list[int | str] | None = None,
         filing_date_from_q: str | None = None,
         filing_date_to_q: str | None = None,
         grant_date_from_q: str | None = None,
         grant_date_to_q: str | None = None,
+        status_date_from_q: str | None = None,
+        status_date_to_q: str | None = None,
         classification_q: str | None = None,
         additional_query_params: dict[str, Any] | None = None,
     ) -> list[ApplicationMetaData]:
@@ -468,6 +557,18 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                         else assignee_name_q
                     )
                     q_parts.append(f"assignmentBag.assigneeBag.assigneeNameText:{v}")
+                if customer_number_q is not None:
+                    q_parts.append(
+                        _or_clause(
+                            "applicationMetaData.customerNumber", customer_number_q
+                        )
+                    )
+                if status_code_q is not None:
+                    q_parts.append(
+                        _or_clause(
+                            "applicationMetaData.applicationStatusCode", status_code_q
+                        )
+                    )
                 if classification_q:
                     v = (
                         f'"{classification_q}"'
@@ -500,6 +601,19 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                 elif grant_date_to_q:
                     q_parts.append(f"applicationMetaData.grantDate:<={grant_date_to_q}")
 
+                if status_date_from_q and status_date_to_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:[{status_date_from_q} TO {status_date_to_q}]"
+                    )
+                elif status_date_from_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:>={status_date_from_q}"
+                    )
+                elif status_date_to_q:
+                    q_parts.append(
+                        f"applicationMetaData.applicationStatusDate:<={status_date_to_q}"
+                    )
+
                 if q_parts:
                     final_q = " AND ".join(q_parts)
 
@@ -924,6 +1038,91 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
             **kwargs,
         )
 
+    def get_firm_portfolio(
+        self,
+        customer_numbers: list[int | str],
+        status_codes: list[int | str] | None = None,
+        status_date_from: str | None = None,
+        status_date_to: str | None = None,
+        filing_date_from: str | None = None,
+        filing_date_to: str | None = None,
+        fields: str | list[str] = "portfolio",
+        sort: str | None = None,
+        offset: int | None = 0,
+        limit: int | None = 25,
+    ) -> PatentDataResponse:
+        """Search a law firm's portfolio across one or more USPTO Customer Numbers.
+
+        A USPTO Customer Number identifies a registered practitioner or firm's
+        correspondence group. Firms typically have multiple Customer Numbers
+        (small firms ~10; large firms 30+), so this helper accepts a list and
+        builds a single Lucene ``OR`` query.
+
+        For per-application drill-down, see the drill hierarchy:
+
+        1. ``get_firm_portfolio(...)`` — firm-wide list with ``minimal`` /
+           ``portfolio`` / ``full_meta`` field presets.
+        2. ``get_application_metadata(app_number)`` — one application, full
+           ``ApplicationMetaData`` (same shape as one ``full_meta`` row).
+        3. ``get_application_by_number(app_number)`` — one application, full
+           ``PatentFileWrapper`` including wrapper-level bags (assignment,
+           continuity, transactions, attorney of record, foreign priority,
+           event data).
+
+        Args:
+            customer_numbers: Non-empty list of Customer Numbers (ints or strings).
+            status_codes: Optional filter to specific application status codes
+                (single value or list). Useful for narrowing to "moving" cases
+                such as non-final / final Office Actions.
+            status_date_from: Lower bound (inclusive) on
+                ``applicationMetaData.applicationStatusDate``, e.g. ``"2025-01-01"``.
+                Pair with a sort like ``"applicationMetaData.applicationStatusDate desc"``
+                to surface cases whose deadline is coming due.
+            status_date_to: Upper bound on the status date.
+            filing_date_from: Lower bound on ``applicationMetaData.filingDate``.
+            filing_date_to: Upper bound on the filing date.
+            fields: Polymorphic. A preset name from :data:`FIELD_PRESETS`
+                (``"minimal"``, ``"portfolio"``, or ``"full_meta"``), a list of
+                dotted field paths, or a comma-joined string. Defaults to
+                ``"portfolio"``. Power users wanting bulk full metadata can pass
+                ``"applicationMetaData,applicationNumberText"`` directly — the
+                API accepts ``applicationMetaData`` as a shorthand for the
+                entire 27-key object.
+            sort: Optional Lucene sort string. No default; a common choice is
+                ``"applicationMetaData.applicationStatusDate desc"``.
+            offset: Pagination offset.
+            limit: Page size.
+
+        Returns:
+            PatentDataResponse: The same response shape as
+            :meth:`search_applications`. Pagination is the caller's responsibility.
+
+        Raises:
+            ValueError: If ``customer_numbers`` is empty.
+        """
+        if not customer_numbers:
+            raise ValueError("customer_numbers must be a non-empty list")
+
+        if isinstance(fields, str) and fields in FIELD_PRESETS:
+            resolved_fields: str = ",".join(FIELD_PRESETS[fields])
+        elif isinstance(fields, list):
+            resolved_fields = ",".join(fields)
+        else:
+            resolved_fields = fields
+
+        return self.search_applications(
+            customer_number_q=list(customer_numbers),
+            status_code_q=list(status_codes) if status_codes else None,
+            status_date_from_q=status_date_from,
+            status_date_to_q=status_date_to,
+            filing_date_from_q=filing_date_from,
+            filing_date_to_q=filing_date_to,
+            fields=resolved_fields,
+            sort=sort,
+            offset=offset,
+            limit=limit,
+        )
+
     def get_status_codes(
         self, params: dict[str, Any] | None = None
     ) -> StatusCodeSearchResponse:

{pyuspto-0.5.4 → pyuspto-0.5.6}/src/pyUSPTO.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.5.4
+Version: 0.5.6
 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.4 → pyuspto-0.5.6}/src/pyUSPTO.egg-info/SOURCES.txt

@@ -96,6 +96,8 @@ src/pyUSPTO.egg-info/PKG-INFO
 src/pyUSPTO.egg-info/SOURCES.txt
 src/pyUSPTO.egg-info/dependency_links.txt
 src/pyUSPTO.egg-info/requires.txt
+src/pyUSPTO.egg-info/scm_file_list.json
+src/pyUSPTO.egg-info/scm_version.json
 src/pyUSPTO.egg-info/top_level.txt
 src/pyUSPTO.egg-info/zip-safe
 src/pyUSPTO/clients/__init__.py