pyUSPTO 0.4.4__tar.gz → 0.4.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyUSPTO
-Version: 0.4.4
+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

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

@@ -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
@@ -115,7 +111,7 @@ sphinx==9.1.0
     #   sphinx-immaterial
     #   sphinx-rtd-theme
     #   sphinxcontrib-jquery
-sphinx-autodoc-typehints==3.9.7
+sphinx-autodoc-typehints==3.9.8
     # via pyuspto
 sphinx-copybutton==0.5.2
     # via pyuspto

{pyuspto-0.4.4 → 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.4 → 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

{pyuspto-0.4.4 → pyuspto-0.4.5}/src/pyUSPTO/clients/patent_data.py

@@ -263,12 +263,12 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["search_applications"]
 
         if post_body is not None:
-            result = self._make_request(
+            result = self._get_model(
                 method="POST",
                 endpoint=endpoint,
+                response_class=PatentDataResponse,
                 json_data=post_body,
                 params=additional_query_params,
-                response_class=PatentDataResponse,
             )
         else:
             params: dict[str, Any] = {}
@@ -366,13 +366,12 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
 
             if additional_query_params:
                 params.update(additional_query_params)
-            result = self._make_request(
+            result = self._get_model(
                 method="GET",
                 endpoint=endpoint,
-                params=params,
                 response_class=PatentDataResponse,
+                params=params,
             )
-        assert isinstance(result, PatentDataResponse)
         return result
 
     def get_search_results(
@@ -408,7 +407,7 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
             if "format" not in post_body:
                 post_body["format"] = "json"
 
-            result = self._make_request(
+            result = self._get_json(
                 method="POST",
                 endpoint=endpoint,
                 json_data=post_body,
@@ -504,12 +503,11 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
             if additional_query_params:
                 params.update(additional_query_params)
 
-            result = self._make_request(
+            result = self._get_json(
                 method="GET",
                 endpoint=endpoint,
                 params=params,
             )
-        assert isinstance(result, dict)
         amd_list = [
             ApplicationMetaData.from_dict(item["applicationMetaData"])
             for item in result["patentdata"]
@@ -541,14 +539,14 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_by_number"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
-        return self._get_wrapper_from_response(
+        ret = self._get_wrapper_from_response(
             response_data=response_data,
             application_number_for_validation=application_number,
         )
+        return ret
 
     def get_application_metadata(
         self, application_number: str
@@ -575,10 +573,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_metadata"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.application_meta_data if wrapper else None
 
@@ -606,10 +603,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_adjustment"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.patent_term_adjustment_data if wrapper else None
 
@@ -638,10 +634,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_assignment"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.assignment_bag if wrapper else None
 
@@ -668,10 +663,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_attorney"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.record_attorney if wrapper else None
 
@@ -701,10 +695,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_continuity"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return ApplicationContinuityData.from_wrapper(wrapper) if wrapper else None
 
@@ -733,10 +726,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_foreign_priority"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.foreign_priority_bag if wrapper else None
 
@@ -765,10 +757,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_transactions"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return wrapper.event_data_bag if wrapper else None
 
@@ -819,11 +810,12 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         if official_date_to:
             params["officialDateTo"] = official_date_to
 
-        result_dict = self._make_request(
-            method="GET", endpoint=endpoint, params=params if params else None
+        return self._get_model(
+            method="GET",
+            endpoint=endpoint,
+            response_class=DocumentBag,
+            params=params if params else None,
         )
-        assert isinstance(result_dict, dict)
-        return DocumentBag.from_dict(result_dict)
 
     def get_application_associated_documents(
         self, application_number: str
@@ -855,10 +847,9 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
         endpoint = self.ENDPOINTS["get_application_associated_documents"].format(
             application_number=self.sanitize_application_number(application_number)
         )
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET", endpoint=endpoint, response_class=PatentDataResponse
         )
-        assert isinstance(response_data, PatentDataResponse)
         wrapper = self._get_wrapper_from_response(response_data, application_number)
         return PrintedPublication.from_wrapper(wrapper) if wrapper else None
 
@@ -935,11 +926,12 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                 status codes, a `StatusCodeCollection` of the `StatusCode`
                 objects (code and description), and a request identifier.
         """
-        result_dict = self._make_request(
-            method="GET", endpoint=self.ENDPOINTS["status_codes"], params=params
+        return self._get_model(
+            method="GET",
+            endpoint=self.ENDPOINTS["status_codes"],
+            response_class=StatusCodeSearchResponse,
+            params=params,
         )
-        assert isinstance(result_dict, dict)
-        return StatusCodeSearchResponse.from_dict(result_dict)
 
     def search_status_codes(
         self, search_request: dict[str, Any]
@@ -962,13 +954,12 @@ class PatentDataClient(BaseUSPTOClient[PatentDataResponse]):
                 status codes, a `StatusCodeCollection` of the `StatusCode`
                 objects (code and description), and a request identifier.
         """
-        result_dict = self._make_request(
+        return self._get_model(
             method="POST",
             endpoint=self.ENDPOINTS["status_codes"],
+            response_class=StatusCodeSearchResponse,
             json_data=search_request,
         )
-        assert isinstance(result_dict, dict)
-        return StatusCodeSearchResponse.from_dict(result_dict)
 
     def download_document(
         self,

{pyuspto-0.4.4 → pyuspto-0.4.5}/src/pyUSPTO/clients/petition_decisions.py

@@ -184,12 +184,12 @@ class FinalPetitionDecisionsClient(BaseUSPTOClient[PetitionDecisionResponse]):
 
         if post_body is not None:
             # POST request path
-            result = self._make_request(
+            result = self._get_model(
                 method="POST",
                 endpoint=endpoint,
+                response_class=PetitionDecisionResponse,
                 json_data=post_body,
                 params=additional_query_params,
-                response_class=PetitionDecisionResponse,
             )
         else:
             # GET request path
@@ -280,14 +280,12 @@ class FinalPetitionDecisionsClient(BaseUSPTOClient[PetitionDecisionResponse]):
             if additional_query_params:
                 params.update(additional_query_params)
 
-            result = self._make_request(
+            result = self._get_model(
                 method="GET",
                 endpoint=endpoint,
-                params=params,
                 response_class=PetitionDecisionResponse,
+                params=params,
             )
-
-        assert isinstance(result, PetitionDecisionResponse)
         return result
 
     def get_decision_by_id(
@@ -326,13 +324,12 @@ class FinalPetitionDecisionsClient(BaseUSPTOClient[PetitionDecisionResponse]):
         if include_documents is not None:
             params["includeDocuments"] = str(include_documents).lower()
 
-        response_data = self._make_request(
+        response_data = self._get_model(
             method="GET",
             endpoint=endpoint,
-            params=params if params else None,
             response_class=PetitionDecisionResponse,
+            params=params if params else None,
         )
-        assert isinstance(response_data, PetitionDecisionResponse)
         return self._get_decision_from_response(
             response_data=response_data,
             petition_decision_record_identifier_for_validation=petition_decision_record_identifier,
@@ -480,17 +477,17 @@ class FinalPetitionDecisionsClient(BaseUSPTOClient[PetitionDecisionResponse]):
 
         if format.lower() == "json":
             # For JSON, parse the response
-            result_dict = self._make_request(
-                method="GET", endpoint=endpoint, params=params
+            return self._get_model(
+                method="GET",
+                endpoint=endpoint,
+                response_class=PetitionDecisionDownloadResponse,
+                params=params,
             )
-            assert isinstance(result_dict, dict)
-            return PetitionDecisionDownloadResponse.from_dict(result_dict)
         else:
             # For CSV or other formats, get streaming response
-            result = self._make_request(
-                method="GET", endpoint=endpoint, params=params, stream=True
+            result = self._stream_request(
+                method="GET", endpoint=endpoint, params=params
             )
-            assert isinstance(result, requests.Response)
 
             if destination is not None:
                 # Save to file using the base class helper