pyUSPTO 0.6.0__tar.gz → 0.6.2__tar.gz

{pyuspto-0.6.0 → pyuspto-0.6.2}/.github/workflows/publish-docs.yaml

@@ -19,7 +19,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: "3.14"
+          python-version: "3.15"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

{pyuspto-0.6.0 → pyuspto-0.6.2}/.github/workflows/python-tests.yml

@@ -45,7 +45,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: "3.14"
+          python-version: "3.15"
 
       - name: Install dependencies
         run: |

{pyuspto-0.6.0 → pyuspto-0.6.2}/CHANGELOG.md

@@ -5,7 +5,39 @@ 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.6.0]
+## [Unreleased]
+
+### Changed
+
+- `sanitize_application_number` now returns series-code input as 8 digits (`18/511,739` → `18511739`). Previously it kept the slash, so `get_application_by_number` and the other per-application methods requested `.../applications/18/511739`, which the API rejects with HTTP 403. This fixes every method that takes an application number, including `get_IFW_metadata(application_number=...)` and `get_IFW(application_number=...)`.
+- A 403 response with the body `{"message":"Missing Authentication Token"}` now adds to its exception message that USPTO also returns this body when the requested URL path does not exist. It is still raised as `USPTOApiAuthError`.
+- `error_handling_example.py` notes that a "Missing Authentication Token" error can also mean a bad URL path.
+- Every client builds its convenience filters with one shared module, `pyUSPTO.clients.query`. `PTABTrialsClient` and `PTABInterferencesClient` no longer quote a single-word text value. Live, `trialStatusCategory:Instituted` and `trialStatusCategory:"Instituted"` both return 220 proceedings. `PTABInterferencesClient` also wraps each party-name filter's `OR` group in parentheses, which returned the same records as before in live checks.
+
+### Fixed
+
+- `application_number_q` (used by `search_applications` and `get_search_results`) now goes through `sanitize_application_number`, so `14/412875`, `14/412,875`, and `14412875` all match, and `PCT/US2025/047756` is sent as `PCTUS2025047756`. Previously the value was sent verbatim and `14/412875` matched nothing. Values containing `*`, and values the sanitizer rejects (such as range or `OR` expressions), are not sanitized.
+- `application_number_q` values that are not a single application number (wildcards, `OR` and range expressions) are now sent inside parentheses, so the field applies to every term. Previously it applied only to the first term: `14412875 OR 10000000` searched `10000000` as free text and returned 3 applications instead of 1.
+- The application-number filters on the other clients get the same cleanup as `application_number_q`, including the parentheses above: `PetitionDecisionsClient` (`application_number_q`), `PTABAppealsClient` (`application_number_text_q`), `PTABInterferencesClient` (`senior_party_application_number_q`, `junior_party_application_number_q`), `PTABTrialsClient.search_decisions` (`application_number_q`), and `patent_application_number_q` on `OAActionsClient`, `OACitationsClient`, `OARejectionsClient`, and `EnrichedCitationsClient`. Previously `17/765301` matched nothing in any of them, and `17/765,301` matched nothing in the office action and enriched citation APIs.
+- Text filters (names, titles, categories, classifications) are quoted when the value contains whitespace or one of `+ - & | ! ( ) { } [ ] ^ " ~ : \ /`, and double quotes and backslashes inside the quotes are escaped. A single plain word, including one with a `*` or `?` wildcard, is sent unquoted. A wildcard value that also contains one of those characters (`Garcia-Lopez*`) is quoted, so its wildcard is searched as plain text. Live, quoted `"Garcia-Lopez*"` returns the same 119 applications as `"Garcia-Lopez"`, and the unquoted form, sent before this change, returned HTTP 404. Before, the filters that quoted at all did so only for a space (or, for `classification_q`, a slash), so `assignee_name_q="Smith-Kline"` was sent unquoted, and an inner quote broke the phrase: `inventor_name_q='Smith "John'` matched nothing and now matches. Applies to the convenience filters of every search client.
+- Code filters (such as `patent_number_q`) send a value containing spaces inside parentheses, so the field applies to every term. `patent_number_q="10000000 OR 10000001"` returned 3 applications and now returns 2. Applies to the convenience filters of every search client.
+- `PTABAppealsClient` `appellant_name_q`, `requestor_name_q`, and `decision_type_category_q` were never quoted and are now quoted under the rule above. A multi-word value searched every word after the first as free text: `appellant_name_q="Block, Inc."` returned 4303 decisions from 2025 instead of 1.
+- The office action and enriched citation category filters are code filters under the rule above: `OAActionsClient` `access_level_category_q` and `application_type_category_q`, `action_type_category_q` on `OACitationsClient` and `OARejectionsClient`, and `EnrichedCitationsClient` `office_action_category_q`. Their values are single-word codes (`PUBLIC`, `REGULAR`, `rejected`, `CTNF`), so `office_action_category_q="CTNF OR CTFR"` is sent as `officeActionCategory:(CTNF OR CTFR)`, and the `OR` now applies to the field.
+- `customer_number_q=[]` and `status_code_q=[]` raise `ValueError` instead of sending the malformed clause `field:()`. Dropping the filter instead would have run the search unfiltered.
+- `OAActionsClient` `group_art_unit_number_q=""` adds no filter. It sent `groupArtUnitNumber:`.
+- `PetitionDecisionsClient.get_decision_by_id`, `BulkDataClient.get_product_by_id`, and `BulkDataClient.download_file` (when the file has no download URI) now percent-encode the ID or file name in the URL path. Previously a `?` or `/` in the value changed the request; `get_decision_by_id("abc?x")` requested decision `abc`. A non-string ID, such as a `uuid.UUID`, still works as it did before.
+- `PTABTrialsClient.search_decisions(document_type_description_q=...)` escapes double quotes and backslashes in the value. A `"` in the value closed the quoted search early and broke the query.
+- `BulkDataClient.download_file(file_name=...)` uses `file_name` only as the local save name. When the file had no download URI, it also requested `file_name` from the server instead of the real file, so `download_file(file_data, file_name="custom.zip")` asked for `.../custom.zip`.
+
+## [0.6.1] - 2026-10-27
+
+### Changed
+
+- `requirements.txt` pins `certifi` 2026.10.23 (was 2026.7.22).
+- The lint job (ruff, mypy) and the docs workflow run on Python 3.15 (was 3.14).
+- Development dependency updates: certifi 2026.10.23, coverage 7.17.0, pluggy 1.7.0, pytest 9.2.0, pytest-mock 3.17.0, ruff 0.17.3, sphinx 9.2.0, sphinx-autodoc-typehints 3.17.4, sphinxcontrib-jsmath 2.0.0.
+
+## [0.6.0] - 2026-10-27
 
 ### Added
 

{pyuspto-0.6.0/src/pyUSPTO.egg-info → pyuspto-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.6.0
+Version: 0.6.2
 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.6.0 → pyuspto-0.6.2}/examples/error_handling_example.py

@@ -32,6 +32,7 @@ try:
 except USPTOApiAuthError as e:
     print(f"Authentication failed: {e}")
     print("Check your API key and try again.")
+    print("A 'Missing Authentication Token' message can also mean a bad URL path.")
 
 print("-" * 40)
 print("Example 2: Not found errors")
@@ -95,7 +96,7 @@ try:
 except USPTOApiRateLimitError:
     print("Rate limited - wait and retry")
 except USPTOApiAuthError:
-    print("Authentication failed - check API key")
+    print("Authentication failed - check API key or URL path")
 except USPTOTimeout:
     print("Request timed out - try again")
 except USPTOConnectionError:

{pyuspto-0.6.0 → pyuspto-0.6.2}/requirements-dev.txt

@@ -10,7 +10,7 @@ ast-serialize==0.13.1
     # via mypy
 babel==2.18.0
     # via sphinx
-certifi==2026.7.22
+certifi==2026.10.23
     # via requests
 charset-normalizer==3.5.2
     # via requests
@@ -18,7 +18,7 @@ colorama==0.4.6
     # via
     #   pytest
     #   sphinx
-coverage==7.16.2
+coverage==7.17.0
     # via pytest-cov
 docutils==0.22.4
     # via
@@ -47,7 +47,7 @@ mdit-py-plugins==0.6.1
     # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
-mypy==2.4.0
+mypy==2.4.1
     # via pyUSPTO (pyproject.toml)
 mypy-extensions==1.1.0
     # via mypy
@@ -59,7 +59,7 @@ packaging==26.3
     #   sphinx
 pathspec==1.1.1
     # via mypy
-pluggy==1.6.0
+pluggy==1.7.0
     # via
     #   pytest
     #   pytest-cov
@@ -67,14 +67,14 @@ pygments==2.21.0
     # via
     #   pytest
     #   sphinx
-pytest==9.1.1
+pytest==9.2.0
     # via
     #   pyUSPTO (pyproject.toml)
     #   pytest-cov
     #   pytest-mock
 pytest-cov==7.1.0
     # via pyUSPTO (pyproject.toml)
-pytest-mock==3.16.0
+pytest-mock==3.17.0
     # via pyUSPTO (pyproject.toml)
 pyyaml==6.0.3
     # via myst-parser
@@ -84,11 +84,11 @@ requests==2.34.2
     #   sphinx
 roman-numerals==4.1.0
     # via sphinx
-ruff==0.17.0
+ruff==0.17.3
     # via pyUSPTO (pyproject.toml)
 snowballstemmer==3.1.1
     # via sphinx
-sphinx==9.1.0
+sphinx==9.2.0
     # via
     #   myst-parser
     #   pyUSPTO (pyproject.toml)
@@ -96,7 +96,7 @@ sphinx==9.1.0
     #   sphinx-copybutton
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-autodoc-typehints==3.13.9
+sphinx-autodoc-typehints==3.17.4
     # via pyUSPTO (pyproject.toml)
 sphinx-copybutton==0.5.2
     # via pyUSPTO (pyproject.toml)
@@ -110,17 +110,17 @@ sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jquery==4.1
     # via sphinx-rtd-theme
-sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-jsmath==2.0.0
     # via sphinx
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
-types-requests==2.33.0.20261006
+types-requests==2.33.0.20261030
     # via pyUSPTO (pyproject.toml)
 typing-extensions==4.16.0
     # via mypy
-tzdata==2026.5
+tzdata==2026.6
     # via pyUSPTO (pyproject.toml)
 urllib3==2.8.0
     # via

{pyuspto-0.6.0 → pyuspto-0.6.2}/requirements.txt

@@ -4,7 +4,7 @@
 #
 #    pip-compile --output-file=requirements.txt --strip-extras pyproject.toml
 #
-certifi==2026.7.22
+certifi==2026.10.23
     # via requests
 charset-normalizer==3.5.2
     # via requests
@@ -12,7 +12,7 @@ idna==3.20
     # via requests
 requests==2.34.2
     # via pyUSPTO (pyproject.toml)
-tzdata==2026.5
+tzdata==2026.6
     # via pyUSPTO (pyproject.toml)
 urllib3==2.8.0
     # via

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/base.py

@@ -14,6 +14,7 @@ from typing import (
     TypeVar,
     runtime_checkable,
 )
+from urllib.parse import quote
 
 import requests
 
@@ -196,6 +197,23 @@ class BaseUSPTOClient(Generic[T]):
         base = custom_base_url if custom_base_url else self.base_url
         return f"{base}/{endpoint.lstrip('/')}"
 
+    @staticmethod
+    def _quote_path_value(value: object) -> str:
+        """Percent-encode a caller value for use as one URL path segment.
+
+        Every reserved character is encoded, including ``/``, ``?``, and
+        ``#``, so the value cannot add path segments, a query string, or a
+        fragment to the request. A non-string value, such as a ``uuid.UUID``,
+        is formatted with ``str()`` first.
+
+        Args:
+            value: The raw value, such as a record ID or file name.
+
+        Returns:
+            The encoded value.
+        """
+        return quote(str(value), safe="")
+
     def _execute_request(
         self,
         method: str,

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/bulk_data.py

@@ -92,7 +92,9 @@ class BulkDataClient(BaseUSPTOClient[BulkDataResponse]):
             ...     latest=True
             ... )
         """
-        endpoint = self.ENDPOINTS["product_by_id"].format(product_id=product_id)
+        endpoint = self.ENDPOINTS["product_by_id"].format(
+            product_id=self._quote_path_value(product_id)
+        )
 
         params = {}
         if file_data_from_date:
@@ -147,7 +149,9 @@ class BulkDataClient(BaseUSPTOClient[BulkDataResponse]):
         Args:
             file_data: FileData object containing download info and product_identifier.
             destination: Directory to save/extract to. Defaults to current directory.
-            file_name: Override filename. Defaults to file_data.file_name.
+            file_name: Name to save the file under locally. Defaults to
+                file_data.file_name. The download always requests
+                file_data.file_name from the server.
             overwrite: Whether to overwrite existing files. Defaults to False.
             extract: Whether to auto-extract archives. Defaults to False.
 
@@ -171,8 +175,8 @@ class BulkDataClient(BaseUSPTOClient[BulkDataResponse]):
             download_url = file_data.file_download_uri
         else:
             endpoint = self.ENDPOINTS["download_file"].format(
-                productIdentifier=file_data.product_identifier,
-                fileName=default_file_name,
+                productIdentifier=self._quote_path_value(file_data.product_identifier),
+                fileName=self._quote_path_value(file_data.file_name),
             )
             download_url = f"{self.base_url}/{endpoint}"
 

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/enriched_citations.py

@@ -9,6 +9,14 @@ from collections.abc import Iterator
 from typing import Any
 
 from pyUSPTO.clients.base import BaseUSPTOClient
+from pyUSPTO.clients.query import (
+    all_of,
+    application_number,
+    boolean,
+    date_range,
+    phrase,
+    term,
+)
 from pyUSPTO.config import USPTOConfig
 from pyUSPTO.models.enriched_citations import (
     EnrichedCitation,
@@ -84,6 +92,12 @@ class EnrichedCitationsClient(BaseUSPTOClient[EnrichedCitationResponse]):
         You can provide either a direct post_body, a query string, or use convenience
         parameters that will be automatically combined into a query.
 
+        ``cited_document_identifier_q`` is quoted when it contains spaces or
+        special characters, with inner quotes escaped. The code filters
+        (office action and citation category codes, tech centers, art units)
+        wrap a value that contains spaces, such as ``"CTNF OR CTFR"``, in
+        parentheses, so the field applies to every term.
+
         Args:
             query: Direct query string in USPTO search syntax.
             sort: Sort order for results.
@@ -92,6 +106,8 @@ class EnrichedCitationsClient(BaseUSPTOClient[EnrichedCitationResponse]):
             post_body: Optional POST body for complex queries. When provided,
                 all other parameters are ignored.
             patent_application_number_q: Filter by patent application number.
+                Any common form matches (``17/765,301``, ``17765301``). Write
+                each number in an ``OR`` or range expression as 8 digits.
             cited_document_identifier_q: Filter by cited document identifier.
             office_action_category_q: Filter by office action category (e.g., "CTNF").
             citation_category_code_q: Filter by citation category code (e.g., "X", "Y").
@@ -141,41 +157,22 @@ class EnrichedCitationsClient(BaseUSPTOClient[EnrichedCitationResponse]):
         # Build query from convenience parameters
         final_q = query
         if final_q is None:
-            q_parts = []
-            if patent_application_number_q:
-                q_parts.append(f"patentApplicationNumber:{patent_application_number_q}")
-            if cited_document_identifier_q:
-                v = (
-                    f'"{cited_document_identifier_q}"'
-                    if " " in cited_document_identifier_q
-                    else cited_document_identifier_q
-                )
-                q_parts.append(f"citedDocumentIdentifier:{v}")
-            if office_action_category_q:
-                q_parts.append(f"officeActionCategory:{office_action_category_q}")
-            if citation_category_code_q:
-                q_parts.append(f"citationCategoryCode:{citation_category_code_q}")
-            if tech_center_q:
-                q_parts.append(f"techCenter:{tech_center_q}")
-            if group_art_unit_number_q:
-                q_parts.append(f"groupArtUnitNumber:{group_art_unit_number_q}")
-            if examiner_cited_q is not None:
-                q_parts.append(
-                    f"examinerCitedReferenceIndicator:{str(examiner_cited_q).lower()}"
-                )
-
-            # Handle office action date range
-            if office_action_date_from_q and office_action_date_to_q:
-                q_parts.append(
-                    f"officeActionDate:[{office_action_date_from_q} TO {office_action_date_to_q}]"
-                )
-            elif office_action_date_from_q:
-                q_parts.append(f"officeActionDate:>={office_action_date_from_q}")
-            elif office_action_date_to_q:
-                q_parts.append(f"officeActionDate:<={office_action_date_to_q}")
-
-            if q_parts:
-                final_q = " AND ".join(q_parts)
+            final_q = all_of(
+                application_number(
+                    "patentApplicationNumber", patent_application_number_q
+                ),
+                phrase("citedDocumentIdentifier", cited_document_identifier_q),
+                term("officeActionCategory", office_action_category_q),
+                term("citationCategoryCode", citation_category_code_q),
+                term("techCenter", tech_center_q),
+                term("groupArtUnitNumber", group_art_unit_number_q),
+                boolean("examinerCitedReferenceIndicator", examiner_cited_q),
+                date_range(
+                    "officeActionDate",
+                    office_action_date_from_q,
+                    office_action_date_to_q,
+                ),
+            )
 
         if final_q is not None:
             body["criteria"] = final_q

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/oa_actions.py

@@ -10,6 +10,12 @@ from collections.abc import Iterator
 from typing import Any
 
 from pyUSPTO.clients.base import BaseUSPTOClient
+from pyUSPTO.clients.query import (
+    all_of,
+    application_number,
+    date_range,
+    term,
+)
 from pyUSPTO.config import USPTOConfig
 from pyUSPTO.models.oa_actions import (
     OAActionsFieldsResponse,
@@ -77,6 +83,11 @@ class OAActionsClient(BaseUSPTOClient[OAActionsResponse]):
         office action documents. You can provide either a direct post_body,
         a criteria string, or use convenience parameters.
 
+        Every convenience filter is a code filter (document codes, categories,
+        tech centers, art units). A value that contains spaces, such as
+        ``"rejected OR objected"``, is wrapped in parentheses, so the field
+        applies to every term.
+
         Args:
             criteria: Direct Solr query string (e.g., ``"patentApplicationNumber:14485382"``).
             sort: Sort order for results (e.g., ``"submissionDate desc"``).
@@ -85,6 +96,8 @@ class OAActionsClient(BaseUSPTOClient[OAActionsResponse]):
             post_body: Optional POST body dict for complex queries. When provided,
                 all other parameters are ignored.
             patent_application_number_q: Filter by patent application number.
+                Any common form matches (``17/765,301``, ``17765301``). Write
+                each number in an ``OR`` or range expression as 8 digits.
             legacy_document_code_identifier_q: Filter by document code (e.g., ``"CTNF"``, ``"NOA"``).
             group_art_unit_number_q: Filter by group art unit number.
             tech_center_q: Filter by technology center code.
@@ -132,33 +145,19 @@ class OAActionsClient(BaseUSPTOClient[OAActionsResponse]):
         # Build criteria from convenience parameters
         final_criteria = criteria
         if final_criteria is None:
-            q_parts = []
-            if patent_application_number_q:
-                q_parts.append(f"patentApplicationNumber:{patent_application_number_q}")
-            if legacy_document_code_identifier_q:
-                q_parts.append(
-                    f"legacyDocumentCodeIdentifier:{legacy_document_code_identifier_q}"
-                )
-            if group_art_unit_number_q is not None:
-                q_parts.append(f"groupArtUnitNumber:{group_art_unit_number_q}")
-            if tech_center_q:
-                q_parts.append(f"techCenter:{tech_center_q}")
-            if access_level_category_q:
-                q_parts.append(f"accessLevelCategory:{access_level_category_q}")
-            if application_type_category_q:
-                q_parts.append(f"applicationTypeCategory:{application_type_category_q}")
-
-            if submission_date_from_q and submission_date_to_q:
-                q_parts.append(
-                    f"submissionDate:[{submission_date_from_q} TO {submission_date_to_q}]"
-                )
-            elif submission_date_from_q:
-                q_parts.append(f"submissionDate:>={submission_date_from_q}")
-            elif submission_date_to_q:
-                q_parts.append(f"submissionDate:<={submission_date_to_q}")
-
-            if q_parts:
-                final_criteria = " AND ".join(q_parts)
+            final_criteria = all_of(
+                application_number(
+                    "patentApplicationNumber", patent_application_number_q
+                ),
+                term("legacyDocumentCodeIdentifier", legacy_document_code_identifier_q),
+                term("groupArtUnitNumber", group_art_unit_number_q),
+                term("techCenter", tech_center_q),
+                term("accessLevelCategory", access_level_category_q),
+                term("applicationTypeCategory", application_type_category_q),
+                date_range(
+                    "submissionDate", submission_date_from_q, submission_date_to_q
+                ),
+            )
 
         if final_criteria is not None:
             body["criteria"] = final_criteria

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/oa_citations.py

@@ -10,6 +10,14 @@ from collections.abc import Iterator
 from typing import Any
 
 from pyUSPTO.clients.base import BaseUSPTOClient
+from pyUSPTO.clients.query import (
+    all_of,
+    application_number,
+    boolean,
+    contains,
+    date_range,
+    term,
+)
 from pyUSPTO.config import USPTOConfig
 from pyUSPTO.models.oa_citations import (
     OACitationRecord,
@@ -79,6 +87,11 @@ class OACitationsClient(BaseUSPTOClient[OACitationsResponse]):
         Office Action citation records. You can provide either a direct post_body,
         a criteria string, or use convenience parameters.
 
+        Every convenience filter is a code filter (document codes, categories,
+        tech centers, art units). A value that contains spaces, such as
+        ``"rejected OR objected"``, is wrapped in parentheses, so the field
+        applies to every term.
+
         Args:
             criteria: Direct Solr query string (e.g., ``"patentApplicationNumber:16845502"``).
             sort: Sort order for results (e.g., ``"createDateTime desc"``).
@@ -87,6 +100,8 @@ class OACitationsClient(BaseUSPTOClient[OACitationsResponse]):
             post_body: Optional POST body dict for complex queries. When provided,
                 all other parameters are ignored.
             patent_application_number_q: Filter by patent application number.
+                Any common form matches (``17/765,301``, ``17765301``). Write
+                each number in an ``OR`` or range expression as 8 digits.
             legal_section_code_q: Filter by legal section code (e.g., ``"101"``, ``"103"``).
             action_type_category_q: Filter by action type (e.g., ``"rejected"``).
             tech_center_q: Filter by technology center code.
@@ -137,37 +152,27 @@ class OACitationsClient(BaseUSPTOClient[OACitationsResponse]):
         # Build criteria from convenience parameters
         final_criteria = criteria
         if final_criteria is None:
-            q_parts = []
-            if patent_application_number_q:
-                q_parts.append(f"patentApplicationNumber:{patent_application_number_q}")
-            if legal_section_code_q:
-                q_parts.append(f"legalSectionCode:*{legal_section_code_q}*")
-            if action_type_category_q:
-                q_parts.append(f"actionTypeCategory:{action_type_category_q}")
-            if tech_center_q:
-                q_parts.append(f"techCenter:{tech_center_q}")
-            if work_group_q:
-                q_parts.append(f"workGroup:{work_group_q}")
-            if group_art_unit_number_q:
-                q_parts.append(f"groupArtUnitNumber:{group_art_unit_number_q}")
-            if examiner_cited_reference_indicator_q is not None:
-                val = str(examiner_cited_reference_indicator_q).lower()
-                q_parts.append(f"examinerCitedReferenceIndicator:{val}")
-            if applicant_cited_examiner_reference_indicator_q is not None:
-                val = str(applicant_cited_examiner_reference_indicator_q).lower()
-                q_parts.append(f"applicantCitedExaminerReferenceIndicator:{val}")
-
-            if create_date_time_from_q and create_date_time_to_q:
-                q_parts.append(
-                    f"createDateTime:[{create_date_time_from_q} TO {create_date_time_to_q}]"
-                )
-            elif create_date_time_from_q:
-                q_parts.append(f"createDateTime:>={create_date_time_from_q}")
-            elif create_date_time_to_q:
-                q_parts.append(f"createDateTime:<={create_date_time_to_q}")
-
-            if q_parts:
-                final_criteria = " AND ".join(q_parts)
+            final_criteria = all_of(
+                application_number(
+                    "patentApplicationNumber", patent_application_number_q
+                ),
+                contains("legalSectionCode", legal_section_code_q),
+                term("actionTypeCategory", action_type_category_q),
+                term("techCenter", tech_center_q),
+                term("workGroup", work_group_q),
+                term("groupArtUnitNumber", group_art_unit_number_q),
+                boolean(
+                    "examinerCitedReferenceIndicator",
+                    examiner_cited_reference_indicator_q,
+                ),
+                boolean(
+                    "applicantCitedExaminerReferenceIndicator",
+                    applicant_cited_examiner_reference_indicator_q,
+                ),
+                date_range(
+                    "createDateTime", create_date_time_from_q, create_date_time_to_q
+                ),
+            )
 
         if final_criteria is not None:
             body["criteria"] = final_criteria

{pyuspto-0.6.0 → pyuspto-0.6.2}/src/pyUSPTO/clients/oa_rejections.py

@@ -10,6 +10,12 @@ from collections.abc import Iterator
 from typing import Any
 
 from pyUSPTO.clients.base import BaseUSPTOClient
+from pyUSPTO.clients.query import (
+    all_of,
+    application_number,
+    date_range,
+    term,
+)
 from pyUSPTO.config import USPTOConfig
 from pyUSPTO.models.oa_rejections import (
     OARejectionsFieldsResponse,
@@ -76,6 +82,11 @@ class OARejectionsClient(BaseUSPTOClient[OARejectionsResponse]):
         office action rejection records. You can provide either a direct
         post_body, a criteria string, or use convenience parameters.
 
+        Every convenience filter is a code filter (document codes, categories,
+        tech centers, art units). A value that contains spaces, such as
+        ``"rejected OR objected"``, is wrapped in parentheses, so the field
+        applies to every term.
+
         Args:
             criteria: Direct Solr query string (e.g., ``"patentApplicationNumber:12190351"``).
             sort: Sort order for results (e.g., ``"submissionDate desc"``).
@@ -84,6 +95,8 @@ class OARejectionsClient(BaseUSPTOClient[OARejectionsResponse]):
             post_body: Optional POST body dict for complex queries. When provided,
                 all other parameters are ignored.
             patent_application_number_q: Filter by patent application number.
+                Any common form matches (``17/765,301``, ``17765301``). Write
+                each number in an ``OR`` or range expression as 8 digits.
             legacy_document_code_identifier_q: Filter by document code (e.g., ``"CTNF"``).
             group_art_unit_number_q: Filter by group art unit number.
             legal_section_code_q: Filter by legal section code.
@@ -130,31 +143,18 @@ class OARejectionsClient(BaseUSPTOClient[OARejectionsResponse]):
         # Build criteria from convenience parameters
         final_criteria = criteria
         if final_criteria is None:
-            q_parts = []
-            if patent_application_number_q:
-                q_parts.append(f"patentApplicationNumber:{patent_application_number_q}")
-            if legacy_document_code_identifier_q:
-                q_parts.append(
-                    f"legacyDocumentCodeIdentifier:{legacy_document_code_identifier_q}"
-                )
-            if group_art_unit_number_q:
-                q_parts.append(f"groupArtUnitNumber:{group_art_unit_number_q}")
-            if legal_section_code_q:
-                q_parts.append(f"legalSectionCode:{legal_section_code_q}")
-            if action_type_category_q:
-                q_parts.append(f"actionTypeCategory:{action_type_category_q}")
-
-            if submission_date_from_q and submission_date_to_q:
-                q_parts.append(
-                    f"submissionDate:[{submission_date_from_q} TO {submission_date_to_q}]"
-                )
-            elif submission_date_from_q:
-                q_parts.append(f"submissionDate:>={submission_date_from_q}")
-            elif submission_date_to_q:
-                q_parts.append(f"submissionDate:<={submission_date_to_q}")
-
-            if q_parts:
-                final_criteria = " AND ".join(q_parts)
+            final_criteria = all_of(
+                application_number(
+                    "patentApplicationNumber", patent_application_number_q
+                ),
+                term("legacyDocumentCodeIdentifier", legacy_document_code_identifier_q),
+                term("groupArtUnitNumber", group_art_unit_number_q),
+                term("legalSectionCode", legal_section_code_q),
+                term("actionTypeCategory", action_type_category_q),
+                date_range(
+                    "submissionDate", submission_date_from_q, submission_date_to_q
+                ),
+            )
 
         if final_criteria is not None:
             body["criteria"] = final_criteria