pyUSPTO 0.4.3__tar.gz → 0.4.5__tar.gz

{pyuspto-0.4.3 → pyuspto-0.4.5}/.github/workflows/publish-to-test-pypi.yml

@@ -12,7 +12,7 @@ on:
 
 jobs:
   build:
-    name: Build distribution 📦
+    name: Build distribution
     runs-on: ubuntu-latest
 
     steps:

{pyuspto-0.4.3 → pyuspto-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.4.3
+Version: 0.4.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
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
@@ -65,12 +65,13 @@ Requires-Dist: pyUSPTO[docs]; extra == "dev"
 Requires-Dist: pyUSPTO[lint]; extra == "dev"
 Dynamic: license-file
 
-# pyUSPTO
+# USPTO Open Data Portal Client Library
 
 [![PyPI version](https://badge.fury.io/py/pyUSPTO.svg)](https://badge.fury.io/py/pyUSPTO)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Read the Docs](https://img.shields.io/readthedocs/pyuspto)](https://pyuspto.readthedocs.io/en/latest/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pyuspto?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=GREY&left_text=downloads)](https://pepy.tech/projects/pyuspto)
 
 A Python client library for interacting with the United Stated Patent and Trademark Office (USPTO) [Open Data Portal](https://data.uspto.gov/home) APIs.
 

{pyuspto-0.4.3 → pyuspto-0.4.5}/README.md

@@ -1,9 +1,10 @@
-# pyUSPTO
+# USPTO Open Data Portal Client Library
 
 [![PyPI version](https://badge.fury.io/py/pyUSPTO.svg)](https://badge.fury.io/py/pyUSPTO)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![Read the Docs](https://img.shields.io/readthedocs/pyuspto)](https://pyuspto.readthedocs.io/en/latest/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pyuspto?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=GREY&left_text=downloads)](https://pepy.tech/projects/pyuspto)
 
 A Python client library for interacting with the United Stated Patent and Trademark Office (USPTO) [Open Data Portal](https://data.uspto.gov/home) APIs.
 

{pyuspto-0.4.3 → pyuspto-0.4.5}/pyproject.toml

@@ -20,7 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Intended Audience :: Education",
@@ -51,7 +51,12 @@ dependencies = [
 dynamic = ["version"]
 
 [project.optional-dependencies]
-test = ["pytest>=9.0.2", "pytest-cov>=7.0.0", "pytest-mock>=3.15.1", "typing_extensions>=4.15.0"]
+test = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+    "typing_extensions>=4.15.0",
+]
 docs = [
     "sphinx>=9.1.0",
     "sphinx-rtd-theme>=3.1.0",

{pyuspto-0.4.3 → pyuspto-0.4.5}/requirements-dev.txt

@@ -14,7 +14,7 @@ babel==2.18.0
     # via sphinx
 certifi==2026.2.25
     # via requests
-charset-normalizer==3.4.4
+charset-normalizer==3.4.5
     # via requests
 colorama==0.4.6
     # via
@@ -88,10 +88,6 @@ pytest-cov==7.0.0
     # via pyuspto
 pytest-mock==3.15.1
     # via pyuspto
-pyuspto @ file:///C:/Users/andrewp/Documents/GitHub/pyUSPTO
-    # via
-    #   pyUSPTO (pyproject.toml)
-    #   pyuspto
 pyyaml==6.0.3
     # via myst-parser
 requests==2.32.5
@@ -102,7 +98,7 @@ requests==2.32.5
     #   sphinx-immaterial
 roman-numerals==4.1.0
     # via sphinx
-ruff==0.15.4
+ruff==0.15.5
     # via pyuspto
 snowballstemmer==3.0.1
     # via sphinx
@@ -115,7 +111,7 @@ sphinx==9.1.0
     #   sphinx-immaterial
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-autodoc-typehints==3.9.6
+sphinx-autodoc-typehints==3.9.8
     # via pyuspto
 sphinx-copybutton==0.5.2
     # via pyuspto

{pyuspto-0.4.3 → pyuspto-0.4.5}/requirements.txt

@@ -6,7 +6,7 @@
 #
 certifi==2026.2.25
     # via requests
-charset-normalizer==3.4.4
+charset-normalizer==3.4.5
     # via requests
 idna==3.11
     # via requests

{pyuspto-0.4.3 → pyuspto-0.4.5}/src/pyUSPTO/clients/base.py

@@ -14,6 +14,10 @@ from typing import (
     runtime_checkable,
 )
 
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
 import requests
 
 from pyUSPTO.config import USPTOConfig
@@ -31,7 +35,7 @@ class FromDictProtocol(Protocol):
     """Protocol for classes that can be created from a dictionary."""
 
     @classmethod
-    def from_dict(cls, data: dict[str, Any], include_raw_data: bool = False) -> Any:
+    def from_dict(cls, data: dict[str, Any], include_raw_data: bool = False) -> Self:
         """Create an object from a dictionary."""
         ...
 
@@ -39,6 +43,9 @@ class FromDictProtocol(Protocol):
 # Type variable for response classes
 T = TypeVar("T", bound=FromDictProtocol)
 
+# Type variable for response classes
+M = TypeVar("M", bound=FromDictProtocol)
+
 
 class BaseUSPTOClient(Generic[T]):
     """Base client class for USPTO API clients."""
@@ -166,49 +173,56 @@ class BaseUSPTOClient(Generic[T]):
                 ),
             ) from json_err
 
-    def _make_request(
+    def _build_url(
         self,
-        method: str,
         endpoint: str,
+        custom_url: str | None = None,
+        custom_base_url: str | None = None,
+    ) -> str:
+        """Build the request URL from endpoint or custom URL.
+
+        Args:
+            endpoint: API endpoint path (without base URL)
+            custom_url: Optional full custom URL (overrides endpoint and base URL)
+            custom_base_url: Optional custom base URL instead of self.base_url
+
+        Returns:
+            The resolved URL string.
+        """
+        if custom_url:
+            return custom_url
+        base = custom_base_url if custom_base_url else self.base_url
+        return f"{base}/{endpoint.lstrip('/')}"
+
+    def _execute_request(
+        self,
+        method: str,
+        url: str,
         params: dict[str, Any] | None = None,
         json_data: dict[str, Any] | None = None,
         stream: bool = False,
-        response_class: type[T] | None = None,
-        custom_url: str | None = None,
-        custom_base_url: str | None = None,
-    ) -> dict[str, Any] | T | requests.Response:
-        """Make an HTTP request to the USPTO API.
+    ) -> requests.Response:
+        """Execute an HTTP request and return the raw Response.
 
-        Note: Only GET and POST methods are supported. Other HTTP methods will
-        raise a ValueError.
+        Handles URL dispatch, error translation, and timeout/connection errors.
+        Callers are responsible for interpreting the response body.
 
         Args:
             method: HTTP method (GET or POST only)
-            endpoint: API endpoint path (without base URL)
+            url: Fully resolved request URL
             params: Optional query parameters
             json_data: Optional JSON body for POST requests
             stream: Whether to stream the response
-            response_class: Class to use for parsing the response
-            custom_url: Optional full custom URL to use (overrides endpoint and base URL)
-            custom_base_url: Optional custom base URL to use instead of self.base_url
 
         Returns:
-            Response data in the appropriate format:
-            - If stream=True: requests.Response object
-            - If response_class is provided: Instance of response_class
-            - Otherwise: Dict[str, Any] containing the JSON response
+            The raw requests.Response after raise_for_status().
 
         Raises:
             ValueError: If an unsupported HTTP method is provided
+            USPTOApiError: On HTTP errors from the API
+            USPTOTimeout: On request timeout
+            USPTOConnectionError: On connection failure
         """
-        url: str = ""
-        if custom_url:
-            url = custom_url
-        else:
-            base = custom_base_url if custom_base_url else self.base_url
-            url = f"{base}/{endpoint.lstrip('/')}"
-
-        # Get timeout from HTTP config
         timeout = self.http_config.get_timeout_tuple()
 
         try:
@@ -228,26 +242,10 @@ class BaseUSPTOClient(Generic[T]):
                 raise ValueError(f"Unsupported HTTP method: {method}")
 
             response.raise_for_status()
-
-            # Return the raw response for streaming requests
-            if stream:
-                return response
-
-            # Parse JSON response with error handling
-            json_data = self._parse_json_response(response, url)
-
-            # Parse the response based on the specified class
-            if response_class:
-                parsed_response: T = response_class.from_dict(
-                    json_data, include_raw_data=self.config.include_raw_data
-                )
-                return parsed_response
-
-            # Return the raw JSON for other requests
-            return json_data
+            return response
 
         except requests.exceptions.HTTPError as http_err:
-            client_operation_message = f"API request to '{url}' failed with HTTPError"  # 'url' is from _make_request scope
+            client_operation_message = f"API request to '{url}' failed with HTTPError"
 
             # Include request body for POST debugging
             if method.upper() == "POST" and json_data:
@@ -257,7 +255,6 @@ class BaseUSPTOClient(Generic[T]):
                     f"\nRequest body sent:\n{json.dumps(json_data, indent=2)}"
                 )
 
-            # Create APIErrorArgs directly from the HTTPError
             current_error_args = APIErrorArgs.from_http_error(
                 http_error=http_err, client_operation_message=client_operation_message
             )
@@ -266,7 +263,6 @@ class BaseUSPTOClient(Generic[T]):
             raise api_exception_to_raise from http_err
 
         except requests.exceptions.Timeout as timeout_err:
-            # Specific handling for timeout errors
             raise USPTOTimeout(
                 message=f"Request to '{url}' timed out",
                 api_short_error="Timeout",
@@ -274,31 +270,120 @@ class BaseUSPTOClient(Generic[T]):
             ) from timeout_err
 
         except requests.exceptions.ConnectionError as conn_err:
-            # Specific handling for connection errors (DNS, refused connection, etc.)
             raise USPTOConnectionError(
                 message=f"Failed to connect to '{url}'",
                 api_short_error="Connection Error",
                 error_details=str(conn_err),
             ) from conn_err
 
-        except (
-            requests.exceptions.RequestException
-        ) as req_err:  # Catches other non-HTTP errors from requests
-            client_operation_message = (
-                f"API request to '{url}' failed"  # 'url' is from _make_request scope
-            )
+        except requests.exceptions.RequestException as req_err:
+            client_operation_message = f"API request to '{url}' failed"
 
-            # Create APIErrorArgs from the generic RequestException
             current_error_args = APIErrorArgs.from_request_exception(
                 request_exception=req_err,
-                client_operation_message=client_operation_message,  # or pass None if you prefer default message
+                client_operation_message=client_operation_message,
             )
 
-            api_exception_to_raise = get_api_exception(
-                current_error_args
-            )  # Will default to USPTOApiError
+            api_exception_to_raise = get_api_exception(current_error_args)
             raise api_exception_to_raise from req_err
 
+    def _stream_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        custom_url: str | None = None,
+        custom_base_url: str | None = None,
+    ) -> requests.Response:
+        """Make a streaming HTTP request and return the raw Response.
+
+        Args:
+            method: HTTP method (GET or POST only)
+            endpoint: API endpoint path (without base URL)
+            params: Optional query parameters
+            json_data: Optional JSON body for POST requests
+            custom_url: Optional full custom URL (overrides endpoint and base URL)
+            custom_base_url: Optional custom base URL instead of self.base_url
+
+        Returns:
+            Streaming requests.Response object.
+        """
+        url = self._build_url(
+            endpoint, custom_url=custom_url, custom_base_url=custom_base_url
+        )
+        return self._execute_request(
+            method=method, url=url, params=params, json_data=json_data, stream=True
+        )
+
+    def _get_model(
+        self,
+        method: str,
+        endpoint: str,
+        response_class: type[M],
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        custom_url: str | None = None,
+        custom_base_url: str | None = None,
+    ) -> M:
+        """Make an HTTP request and parse the response into a model.
+
+        Args:
+            method: HTTP method (GET or POST only)
+            endpoint: API endpoint path (without base URL)
+            response_class: Class to use for parsing the response
+            params: Optional query parameters
+            json_data: Optional JSON body for POST requests
+            custom_url: Optional full custom URL (overrides endpoint and base URL)
+            custom_base_url: Optional custom base URL instead of self.base_url
+
+        Returns:
+            Instance of response_class parsed from the JSON response.
+        """
+        url = self._build_url(
+            endpoint, custom_url=custom_url, custom_base_url=custom_base_url
+        )
+        response = self._execute_request(
+            method=method, url=url, params=params, json_data=json_data
+        )
+        data = self._parse_json_response(response, url)
+
+        ret = response_class.from_dict(
+            data, include_raw_data=self.config.include_raw_data
+        )
+        assert isinstance(ret, response_class)
+        return ret
+
+    def _get_json(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        custom_url: str | None = None,
+        custom_base_url: str | None = None,
+    ) -> dict[str, Any]:
+        """Make an HTTP request and return the parsed JSON response.
+
+        Args:
+            method: HTTP method (GET or POST only)
+            endpoint: API endpoint path (without base URL)
+            params: Optional query parameters
+            json_data: Optional JSON body for POST requests
+            custom_url: Optional full custom URL (overrides endpoint and base URL)
+            custom_base_url: Optional custom base URL instead of self.base_url
+
+        Returns:
+            Dict containing the JSON response.
+        """
+        url = self._build_url(
+            endpoint, custom_url=custom_url, custom_base_url=custom_base_url
+        )
+        response = self._execute_request(
+            method=method, url=url, params=params, json_data=json_data
+        )
+        return self._parse_json_response(response, url)
+
     def paginate_results(
         self,
         method_name: str,
@@ -785,19 +870,14 @@ class BaseUSPTOClient(Generic[T]):
             Path to downloaded file
 
         Raises:
-            TypeError: If response is not a valid Response object
             FileExistsError: If file exists and overwrite is False
         """
-        response = self._make_request(
+        response = self._stream_request(
             method="GET",
             endpoint="",
-            stream=True,
             custom_url=url,
         )
 
-        if not isinstance(response, requests.Response):
-            raise TypeError(f"Expected Response, got {type(response)}")
-
         return self._save_response_to_file(
             response=response,
             destination=destination,

{pyuspto-0.4.3 → pyuspto-0.4.5}/src/pyUSPTO/clients/bulk_data.py

@@ -109,13 +109,12 @@ class BulkDataClient(BaseUSPTOClient[BulkDataResponse]):
             params["latest"] = str(latest).lower()
 
         # Use response_class for clean parsing
-        response = self._make_request(
+        response = self._get_model(
             method="GET",
             endpoint=endpoint,
-            params=params if params else None,
             response_class=BulkDataResponse,
+            params=params if params else None,
         )
-        assert isinstance(response, BulkDataResponse)
 
         # Extract the product from response
         if response.bulk_data_product_bag:
@@ -251,13 +250,9 @@ class BulkDataClient(BaseUSPTOClient[BulkDataResponse]):
         if fields is not None:
             params["fields"] = ",".join(fields)
 
-        result = self._make_request(
+        return self._get_model(
             method="GET",
             endpoint=self.ENDPOINTS["products_search"],
-            params=params,
             response_class=BulkDataResponse,
+            params=params,
         )
-
-        # Since we specified response_class=BulkDataResponse, the result should be a BulkDataResponse
-        assert isinstance(result, BulkDataResponse)
-        return result