pyUSPTO 0.5.0__tar.gz → 0.5.1__tar.gz

{pyuspto-0.5.0 → pyuspto-0.5.1}/.github/workflows/python-tests.yml

@@ -32,7 +32,7 @@ jobs:
           pytest tests/ --cov=src/pyUSPTO
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           fail_ci_if_error: false
 

{pyuspto-0.5.0 → pyuspto-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.5.0
+Version: 0.5.1
 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
@@ -75,7 +75,7 @@ Dynamic: license-file
 
 A Python client library for interacting with the United Stated Patent and Trademark Office (USPTO) [Open Data Portal](https://data.uspto.gov/home) APIs.
 
-This package provides clients for interacting with the USPTO Bulk Data API, Patent Data API, Final Petition Decisions API, and PTAB (Patent Trial and Appeal Board) APIs.
+This package provides clients for interacting with the USPTO Bulk Data API, Patent Data API, Final Petition Decisions API, PTAB (Patent Trial and Appeal Board) APIs, Enriched Citations API, Office Action Text Retrieval API, Office Action Rejections API, and Office Action Citations API.
 
 > [!IMPORTANT]
 > The USPTO is in the process of moving their Developer API. This package is only concerned with the new API. The [old API](https://developer.uspto.gov/) was officially retired at the end of 2025; however, some products have not yet been fully transitioned to the Open Data Portal API. The USPTO expects the remaining products to be transitioned to the Open Data Portal in early 2026.
@@ -123,6 +123,10 @@ Then use it in your Python code:
 ```python
 from pyUSPTO import (
     BulkDataClient,
+    EnrichedCitationsClient,
+    OAActionsClient,
+    OACitationsClient,
+    OARejectionsClient,
     PatentDataClient,
     FinalPetitionDecisionsClient,
     PTABTrialsClient,
@@ -140,6 +144,10 @@ petition_client = FinalPetitionDecisionsClient(config=config)
 trials_client = PTABTrialsClient(config=config)
 appeals_client = PTABAppealsClient(config=config)
 interferences_client = PTABInterferencesClient(config=config)
+citations_client = EnrichedCitationsClient(config=config)
+oa_client = OAActionsClient(config=config)
+oa_citations_client = OACitationsClient(config=config)
+rejections_client = OARejectionsClient(config=config)
 ```
 
 ### Direct API Key
@@ -302,6 +310,79 @@ print(f"Found {response.count} interference decisions since 2023")
 
 See [`examples/ptab_interferences_example.py`](examples/ptab_interferences_example.py) for detailed examples including searching by party name and outcome.
 
+### Enriched Citations API
+
+```python
+from pyUSPTO import EnrichedCitationsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = EnrichedCitationsClient(config=config)
+
+# Search for enriched citations by technology center
+response = client.search_citations(
+    tech_center_q="1700",
+    rows=5,
+)
+print(f"Found {response.count} citations from TC 1700")
+```
+
+See [`examples/enriched_citations_example.py`](examples/enriched_citations_example.py) for detailed examples including searching by application number and citation category.
+
+### Office Action Text Retrieval API
+
+```python
+from pyUSPTO import OAActionsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OAActionsClient(config=config)
+
+# Search for office actions by technology center
+response = client.search(
+    tech_center_q="1700",
+    rows=5,
+)
+print(f"Found {response.count} office actions from TC 1700")
+```
+
+See [`examples/oa_actions_example.py`](examples/oa_actions_example.py) for detailed examples including searching by document code and paginating results.
+
+### Office Action Rejections API
+
+```python
+from pyUSPTO import OARejectionsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OARejectionsClient(config=config)
+
+# Search for rejections by application number
+response = client.search(
+    patent_application_number_q="12190351",
+    rows=5,
+)
+print(f"Found {response.count} rejection records for application 12190351")
+```
+
+See [`examples/oa_rejections_example.py`](examples/oa_rejections_example.py) for detailed examples including searching by document code and inspecting rejection flags.
+
+### Office Action Citations API
+
+```python
+from pyUSPTO import OACitationsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OACitationsClient(config=config)
+
+# Search for citations by legal section code
+response = client.search(
+    legal_section_code_q="103",
+    tech_center_q="2800",
+    rows=5,
+)
+print(f"Found {response.count} section 103 citations in tech center 2800")
+```
+
+See [`examples/oa_citations_example.py`](examples/oa_citations_example.py) for detailed examples including searching by examiner-cited indicator and paginating results.
+
 ## Documentation
 
 Full documentation may be found on [Read the Docs](https://pyuspto.readthedocs.io/).

{pyuspto-0.5.0 → pyuspto-0.5.1}/README.md

@@ -8,7 +8,7 @@
 
 A Python client library for interacting with the United Stated Patent and Trademark Office (USPTO) [Open Data Portal](https://data.uspto.gov/home) APIs.
 
-This package provides clients for interacting with the USPTO Bulk Data API, Patent Data API, Final Petition Decisions API, and PTAB (Patent Trial and Appeal Board) APIs.
+This package provides clients for interacting with the USPTO Bulk Data API, Patent Data API, Final Petition Decisions API, PTAB (Patent Trial and Appeal Board) APIs, Enriched Citations API, Office Action Text Retrieval API, Office Action Rejections API, and Office Action Citations API.
 
 > [!IMPORTANT]
 > The USPTO is in the process of moving their Developer API. This package is only concerned with the new API. The [old API](https://developer.uspto.gov/) was officially retired at the end of 2025; however, some products have not yet been fully transitioned to the Open Data Portal API. The USPTO expects the remaining products to be transitioned to the Open Data Portal in early 2026.
@@ -56,6 +56,10 @@ Then use it in your Python code:
 ```python
 from pyUSPTO import (
     BulkDataClient,
+    EnrichedCitationsClient,
+    OAActionsClient,
+    OACitationsClient,
+    OARejectionsClient,
     PatentDataClient,
     FinalPetitionDecisionsClient,
     PTABTrialsClient,
@@ -73,6 +77,10 @@ petition_client = FinalPetitionDecisionsClient(config=config)
 trials_client = PTABTrialsClient(config=config)
 appeals_client = PTABAppealsClient(config=config)
 interferences_client = PTABInterferencesClient(config=config)
+citations_client = EnrichedCitationsClient(config=config)
+oa_client = OAActionsClient(config=config)
+oa_citations_client = OACitationsClient(config=config)
+rejections_client = OARejectionsClient(config=config)
 ```
 
 ### Direct API Key
@@ -235,6 +243,79 @@ print(f"Found {response.count} interference decisions since 2023")
 
 See [`examples/ptab_interferences_example.py`](examples/ptab_interferences_example.py) for detailed examples including searching by party name and outcome.
 
+### Enriched Citations API
+
+```python
+from pyUSPTO import EnrichedCitationsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = EnrichedCitationsClient(config=config)
+
+# Search for enriched citations by technology center
+response = client.search_citations(
+    tech_center_q="1700",
+    rows=5,
+)
+print(f"Found {response.count} citations from TC 1700")
+```
+
+See [`examples/enriched_citations_example.py`](examples/enriched_citations_example.py) for detailed examples including searching by application number and citation category.
+
+### Office Action Text Retrieval API
+
+```python
+from pyUSPTO import OAActionsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OAActionsClient(config=config)
+
+# Search for office actions by technology center
+response = client.search(
+    tech_center_q="1700",
+    rows=5,
+)
+print(f"Found {response.count} office actions from TC 1700")
+```
+
+See [`examples/oa_actions_example.py`](examples/oa_actions_example.py) for detailed examples including searching by document code and paginating results.
+
+### Office Action Rejections API
+
+```python
+from pyUSPTO import OARejectionsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OARejectionsClient(config=config)
+
+# Search for rejections by application number
+response = client.search(
+    patent_application_number_q="12190351",
+    rows=5,
+)
+print(f"Found {response.count} rejection records for application 12190351")
+```
+
+See [`examples/oa_rejections_example.py`](examples/oa_rejections_example.py) for detailed examples including searching by document code and inspecting rejection flags.
+
+### Office Action Citations API
+
+```python
+from pyUSPTO import OACitationsClient, USPTOConfig
+
+config = USPTOConfig(api_key="your_api_key_here")
+client = OACitationsClient(config=config)
+
+# Search for citations by legal section code
+response = client.search(
+    legal_section_code_q="103",
+    tech_center_q="2800",
+    rows=5,
+)
+print(f"Found {response.count} section 103 citations in tech center 2800")
+```
+
+See [`examples/oa_citations_example.py`](examples/oa_citations_example.py) for detailed examples including searching by examiner-cited indicator and paginating results.
+
 ## Documentation
 
 Full documentation may be found on [Read the Docs](https://pyuspto.readthedocs.io/).

{pyuspto-0.5.0 → pyuspto-0.5.1}/docs/source/api/clients/index.rst

@@ -6,6 +6,9 @@ Clients
 
    bulk_data
    enriched_citations
+   oa_actions
+   oa_citations
+   oa_rejections
    patent_data
    petition_decisions
    ptab_appeals

pyuspto-0.5.1/docs/source/api/clients/oa_actions.rst

@@ -0,0 +1,7 @@
+OA Actions Client
+=================
+
+.. automodule:: pyUSPTO.clients.oa_actions
+   :members:
+   :undoc-members:
+   :show-inheritance:

pyuspto-0.5.1/docs/source/api/clients/oa_citations.rst

@@ -0,0 +1,7 @@
+OA Citations Client
+===================
+
+.. automodule:: pyUSPTO.clients.oa_citations
+   :members:
+   :undoc-members:
+   :show-inheritance:

pyuspto-0.5.1/docs/source/api/clients/oa_rejections.rst

@@ -0,0 +1,7 @@
+Office Action Rejections Client
+===============================
+
+.. automodule:: pyUSPTO.clients.oa_rejections
+   :members:
+   :undoc-members:
+   :show-inheritance:

{pyuspto-0.5.0 → pyuspto-0.5.1}/docs/source/api/models/index.rst

@@ -7,6 +7,9 @@ Models
    base
    bulk_data
    enriched_citations
+   oa_actions
+   oa_citations
+   oa_rejections
    patent_data
    petition_decisions
    ptab

pyuspto-0.5.1/docs/source/api/models/oa_actions.rst

@@ -0,0 +1,7 @@
+OA Actions Models
+=================
+
+.. automodule:: pyUSPTO.models.oa_actions
+   :members:
+   :undoc-members:
+   :show-inheritance:

pyuspto-0.5.1/docs/source/api/models/oa_citations.rst

@@ -0,0 +1,7 @@
+OA Citations Models
+===================
+
+.. automodule:: pyUSPTO.models.oa_citations
+   :members:
+   :undoc-members:
+   :show-inheritance:

pyuspto-0.5.1/docs/source/api/models/oa_rejections.rst

@@ -0,0 +1,7 @@
+Office Action Rejections Models
+================================
+
+.. automodule:: pyUSPTO.models.oa_rejections
+   :members:
+   :undoc-members:
+   :show-inheritance:

{pyuspto-0.5.0 → pyuspto-0.5.1}/docs/source/examples/index.rst

@@ -6,6 +6,9 @@ Examples
 
    bulk_data
    enriched_citations
+   oa_actions
+   oa_citations
+   oa_rejections
    patent_data
    ifw_example
    petition_decisions

pyuspto-0.5.1/docs/source/examples/oa_actions.rst

@@ -0,0 +1,6 @@
+OA Actions Example
+==================
+
+.. literalinclude:: ../../../examples/oa_actions_example.py
+   :language: python
+   :linenos:

pyuspto-0.5.1/docs/source/examples/oa_citations.rst

@@ -0,0 +1,6 @@
+OA Citations Example
+====================
+
+.. literalinclude:: ../../../examples/oa_citations_example.py
+   :language: python
+   :linenos:

pyuspto-0.5.1/docs/source/examples/oa_rejections.rst

@@ -0,0 +1,6 @@
+Office Action Rejections Examples
+==================================
+
+.. automodule:: examples.oa_rejections_example
+   :members:
+   :undoc-members:

{pyuspto-0.5.0 → pyuspto-0.5.1}/examples/enriched_citations_example.py

@@ -111,7 +111,7 @@ print("-" * 40)
 
 max_items = 30
 count = 0
-for citation in client.paginate_citations(
+for _ in client.paginate_citations(
     tech_center_q="2800", rows=10
 ):
     count += 1

pyuspto-0.5.1/examples/oa_actions_example.py

@@ -0,0 +1,117 @@
+"""Example usage of pyUSPTO for Office Action Text Retrieval.
+
+Demonstrates the OAActionsClient for searching full-text office action
+documents, filtering by various criteria, inspecting section data,
+and paginating through results.
+"""
+
+import os
+
+from pyUSPTO import OAActionsClient, USPTOConfig
+
+# --- Client Initialization ---
+api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
+if api_key == "YOUR_API_KEY_HERE":
+    raise ValueError("API key is not set. Set the USPTO_API_KEY environment variable.")
+config = USPTOConfig(api_key=api_key)
+client = OAActionsClient(config=config)
+
+print("-" * 40)
+print("Example 1: Search by application number")
+print("-" * 40)
+
+response = client.search(patent_application_number_q="11363598")
+print(f"Found {response.num_found} office actions for application 11363598.")
+for record in response.docs[:3]:
+    print(f"\n  Doc Code: {record.legacy_document_code_identifier}")
+    print(f"  Submission Date: {record.submission_date}")
+    print(f"  Art Unit: {record.group_art_unit_number}")
+    if record.section:
+        if record.section.section_102_rejection_text:
+            print("  Has § 102 rejection text.")
+        if record.section.section_103_rejection_text:
+            print("  Has § 103 rejection text.")
+
+print("-" * 40)
+print("Example 2: Search by document code (CTNF) and tech center")
+print("-" * 40)
+
+response = client.search(
+    tech_center_q="2800",
+    legacy_document_code_identifier_q="CTNF",
+    rows=5,
+)
+print(f"Found {response.num_found} CTNF office actions in tech center 2800.")
+for record in response.docs:
+    print(
+        f"  App {record.patent_application_number}: "
+        f"AU {record.group_art_unit_number}, "
+        f"submitted {record.submission_date}"
+    )
+
+print("-" * 40)
+print("Example 3: Search by submission date range")
+print("-" * 40)
+
+response = client.search(
+    submission_date_from_q="2010-01-01",
+    submission_date_to_q="2010-12-31",
+    rows=5,
+)
+print(f"Found {response.num_found} office actions submitted in 2010.")
+
+print("-" * 40)
+print("Example 4: Search with sort")
+print("-" * 40)
+
+response = client.search(
+    tech_center_q="1700",
+    sort="submissionDate desc",
+    rows=5,
+)
+print(f"Found {response.num_found} office actions in tech center 1700 (newest first).")
+for record in response.docs:
+    print(f"  {record.submission_date}: {record.invention_title}")
+
+print("-" * 40)
+print("Example 5: Inspect section data")
+print("-" * 40)
+
+response = client.search(
+    criteria='id:"9c27199b54dc83c9a6f643b828990d0322071461557b31ead3428885"',
+    rows=1,
+)
+if response.docs:
+    record = response.docs[0]
+    print(f"Record: {record.id}")
+    print(f"  Patent Number: {record.patent_number}")
+    print(f"  Invention Title: {record.invention_title}")
+    if record.section:
+        print("  Section 102 text (first 200 chars):")
+        for text in record.section.section_102_rejection_text:
+            if text:
+                print(f"    {text[:200]}...")
+
+print("-" * 40)
+print("Example 6: Paginate through results")
+print("-" * 40)
+
+max_items = 30
+count = 0
+for _ in client.paginate(tech_center_q="1700", rows=10):
+    count += 1
+    if count >= max_items:
+        print(f"  ... (stopping at {max_items} items)")
+        break
+
+print(f"Retrieved {count} office action records via pagination.")
+
+print("-" * 40)
+print("Example 7: Get available fields")
+print("-" * 40)
+
+fields_response = client.get_fields()
+print(f"API Status: {fields_response.api_status}")
+print(f"Field Count: {fields_response.field_count}")
+print(f"Last Updated: {fields_response.last_data_updated_date}")
+print(f"Sample fields: {fields_response.fields[:5]}")

pyuspto-0.5.1/examples/oa_citations_example.py

@@ -0,0 +1,106 @@
+"""Example usage of pyUSPTO for Office Action Citations.
+
+Demonstrates the OACitationsClient for searching citation data from
+Office Actions, filtering by various criteria, and paginating through results.
+"""
+
+import os
+
+from pyUSPTO import OACitationsClient, USPTOConfig
+
+# --- Client Initialization ---
+api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
+if api_key == "YOUR_API_KEY_HERE":
+    raise ValueError("API key is not set. Set the USPTO_API_KEY environment variable.")
+config = USPTOConfig(api_key=api_key)
+client = OACitationsClient(config=config)
+
+print("-" * 40)
+print("Example 1: Search by application number")
+print("-" * 40)
+
+response = client.search(patent_application_number_q="17519936")
+print(f"Found {response.num_found} citations for application 17519936.")
+for record in response.docs[:3]:
+    print(f"\n  Legal Section: {record.legal_section_code}")
+    print(f"  Action Type: {record.action_type_category}")
+    print(f"  Reference: {record.reference_identifier}")
+    print(f"  Examiner Cited: {record.examiner_cited_reference_indicator}")
+
+print("-" * 40)
+print("Example 2: Search by legal section code and tech center")
+print("-" * 40)
+
+response = client.search(
+    tech_center_q="2800",
+    legal_section_code_q="103",
+    rows=5,
+)
+print(f"Found {response.num_found} section 103 citations in tech center 2800.")
+for record in response.docs:
+    print(
+        f"  App {record.patent_application_number}: "
+        f"AU {record.group_art_unit_number}, "
+        f"ref {record.parsed_reference_identifier}"
+    )
+
+print("-" * 40)
+print("Example 3: Search by examiner-cited indicator")
+print("-" * 40)
+
+response = client.search(
+    examiner_cited_reference_indicator_q=True,
+    tech_center_q="1700",
+    rows=5,
+)
+print(f"Found {response.num_found} examiner-cited references in tech center 1700.")
+for record in response.docs:
+    print(f"  {record.reference_identifier}")
+
+print("-" * 40)
+print("Example 4: Search by create date range")
+print("-" * 40)
+
+response = client.search(
+    create_date_time_from_q="2025-07-01",
+    create_date_time_to_q="2025-07-04",
+    rows=5,
+)
+print(f"Found {response.num_found} citations created 2025-07-01 to 2025-07-04.")
+
+print("-" * 40)
+print("Example 5: Search with sort")
+print("-" * 40)
+
+response = client.search(
+    tech_center_q="2800",
+    sort="createDateTime desc",
+    rows=5,
+)
+print(f"Found {response.num_found} citations in tech center 2800 (newest first).")
+for record in response.docs:
+    print(f"  {record.create_date_time}: {record.patent_application_number}")
+
+print("-" * 40)
+print("Example 6: Paginate through results")
+print("-" * 40)
+
+max_items = 30
+count = 0
+for _ in client.paginate(tech_center_q="2800", rows=10):
+    count += 1
+    if count >= max_items:
+        print(f"  ... (stopping at {max_items} items)")
+        break
+
+print(f"Retrieved {count} citation records via pagination.")
+
+print("-" * 40)
+print("Example 7: Get available fields")
+print("-" * 40)
+
+fields_response = client.get_fields()
+print(f"API Status: {fields_response.api_status}")
+print(f"Field Count: {fields_response.field_count}")
+print(f"Last Updated: {fields_response.last_data_updated_date}")
+print(f"Sample fields: {fields_response.fields[:5]}")

pyuspto-0.5.1/examples/oa_rejections_example.py

@@ -0,0 +1,63 @@
+"""Examples for the OARejectionsClient.
+
+This module demonstrates how to use the OARejectionsClient to search for
+rejection-level data from USPTO Office Actions.
+"""
+
+from pyUSPTO import OARejectionsClient, USPTOConfig
+
+config = USPTOConfig.from_env()
+client = OARejectionsClient(config=config)
+
+# --- Example 1: Search by application number ---
+response = client.search(patent_application_number_q="12190351")
+print(f"Found {response.count} records for application 12190351")
+for record in response.docs:
+    print(f"  {record.id}: {record.legacy_document_code_identifier}")
+
+# --- Example 2: Search by document code and date range ---
+response = client.search(
+    legacy_document_code_identifier_q="CTNF",
+    submission_date_from_q="2020-01-01",
+    submission_date_to_q="2020-12-31",
+    rows=5,
+)
+print(f"\nFound {response.count} CTNF rejections in 2020")
+
+# --- Example 3: Search with a direct criteria string ---
+response = client.search(
+    criteria="hasRej103:1 AND groupArtUnitNumber:1713",
+    rows=5,
+)
+print(f"\nFound {response.count} 103-rejection records in art unit 1713")
+
+# --- Example 4: Inspect rejection flags ---
+response = client.search(patent_application_number_q="12190351", rows=1)
+if response.docs:
+    record = response.docs[0]
+    print(f"\nRecord: {record.id}")
+    print(f"  101 rejection: {record.has_rej_101}")
+    print(f"  102 rejection: {record.has_rej_102}")
+    print(f"  103 rejection: {record.has_rej_103}")
+    print(f"  112 rejection: {record.has_rej_112}")
+    print(f"  Alice indicator: {record.alice_indicator}")
+    print(f"  Claims: {record.claim_number_array_document}")
+
+# --- Example 5: Search with POST body ---
+response = client.search(
+    post_body={"criteria": "patentApplicationNumber:12190351", "rows": 10}
+)
+print(f"\nFound {response.count} records via POST body")
+
+# --- Example 6: Paginate through results ---
+count = 0
+for _ in client.paginate(
+    legal_section_code_q="103",
+    submission_date_from_q="2020-01-01",
+    submission_date_to_q="2020-01-31",
+    rows=25,
+):
+    count += 1
+    if count >= 50:
+        break
+print(f"\nIterated through {count} records")