tooluniverse.uspto_tool module

class tooluniverse.uspto_tool.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

Bases: BaseAdapter

The built-in HTTP Adapter for urllib3.

Provides a general-case interface for Requests sessions to contact HTTP and HTTPS urls by implementing the Transport Adapter interface. This class will usually be created by the :class:Session <Session> class under the covers.

Parameters:

• pool_connections – The number of urllib3 connection pools to cache.

• pool_maxsize – The maximum number of connections to save in the pool.

• max_retries – The maximum number of retries each connection should attempt. Note, this applies only to failed DNS lookups, socket connections and connection timeouts, never to requests where data has made it to the server. By default, Requests does not retry failed connections. If you need granular control over the conditions under which we retry a request, import urllib3’s `Retry` class and pass that instead.

• pool_block – Whether the connection pool should block for connections.

Usage:

>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)

__init__(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

init_poolmanager(connections, maxsize, block=False, **pool_kwargs)

Initializes a urllib3 PoolManager.

This method should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• connections – The number of urllib3 connection pools to cache.

• maxsize – The maximum number of connections to save in the pool.

• block – Block when no free connections are available.

• pool_kwargs – Extra keyword arguments used to initialize the Pool Manager.

proxy_manager_for(proxy, **proxy_kwargs)

Return urllib3 ProxyManager for the given proxy.

This method should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• proxy – The proxy to return a urllib3 ProxyManager for.

• proxy_kwargs – Extra keyword arguments used to configure the Proxy Manager.

Returns:

ProxyManager

Return type:

urllib3.ProxyManager

cert_verify(conn, url, verify, cert)

Verify a SSL certificate. This method should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• conn – The urllib3 connection object associated with the cert.

• url – The requested URL.

• verify – Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use

• cert – The SSL certificate to verify.

build_response(req, resp)

Builds a :class:Response <requests.Response> object from a urllib3 response. This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>

Parameters:

• req – The :class:PreparedRequest <PreparedRequest> used to generate the response.

• resp – The urllib3 response object.

Return type:

requests.Response

build_connection_pool_key_attributes(request, verify, cert=None)

Build the PoolKey attributes used by urllib3 to return a connection.

This looks at the PreparedRequest, the user-specified verify value, and the value of the cert parameter to determine what PoolKey values to use to select a connection from a given urllib3 Connection Pool.

The SSL related pool key arguments are not consistently set. As of this writing, use the following to determine what keys may be in that dictionary:

• If `verify`` is ``True``, ``"ssl_context"` will be set and will be the default Requests SSL Context

• If `verify`` is ``False``, ``"ssl_context"` will not be set but `"cert_reqs"` will be set

• If `verify` is a string, (i.e., it is a user-specified trust bundle) `"ca_certs"` will be set if the string is not a directory recognized by :py:func:os.path.isdir, otherwise `"ca_cert_dir"` will be set.

• If `"cert"`` is specified, ``"cert_file"` will always be set. If `"cert"`` is a tuple with a second item, ``"key_file"` will also be present

To override these settings, one may subclass this class, call this method and use the above logic to change parameters as desired. For example, if one wishes to use a custom :py:class:ssl.SSLContext one must both set `"ssl_context"` and based on what else they require, alter the other keys to ensure the desired behaviour.

Parameters:

• request (:class:~requests.models.PreparedRequest) – The PreparedReqest being sent over the connection.

• verify – Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.

• cert – (optional) Any user-provided SSL certificate for client authentication (a.k.a., mTLS). This may be a string (i.e., just the path to a file which holds both certificate and key) or a tuple of length 2 with the certificate file path and key file path.

Returns:

A tuple of two dictionaries. The first is the “host parameters” portion of the Pool Key including scheme, hostname, and port. The second is a dictionary of SSLContext related parameters.

get_connection_with_tls_context(request, verify, proxies=None, cert=None)

Returns a urllib3 connection for the given request and TLS settings. This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• request – The :class:PreparedRequest <PreparedRequest> object to be sent over the connection.

• verify – Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use.

• proxies – (optional) The proxies dictionary to apply to the request.

• cert – (optional) Any user-provided SSL certificate to be used for client authentication (a.k.a., mTLS).

Return type:

urllib3.ConnectionPool

get_connection(url, proxies=None)

DEPRECATED: Users should move to get_connection_with_tls_context for all subclasses of HTTPAdapter using Requests>=2.32.2.

Returns a urllib3 connection for the given URL. This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• url – The URL to connect to.

• proxies – (optional) A Requests-style dictionary of proxies used on this request.

Return type:

urllib3.ConnectionPool

close()

Disposes of any internal state.

Currently, this closes the PoolManager and any active ProxyManager, which closes any pooled connections.

request_url(request, proxies)

Obtain the url to use when making the final request.

If the message is being sent through a HTTP proxy, the full URL has to be used. Otherwise, we should only use the path portion of the URL.

This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• request – The :class:PreparedRequest <PreparedRequest> being sent.

• proxies – A dictionary of schemes or schemes and hosts to proxy URLs.

Return type:

str

add_headers(request, **kwargs)

Add any headers needed by the connection. As of v2.0 this does nothing by default, but is left for overriding by users that subclass the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

• request – The :class:PreparedRequest <PreparedRequest> to add headers to.

• kwargs – The keyword arguments from the call to send().

proxy_headers(proxy)

Returns a dictionary of the headers to add to any request sent through a proxy. This works with urllib3 magic to ensure that they are correctly sent to the proxy, rather than in a tunnelled request if CONNECT is being used.

This should not be called from user code, and is only exposed for use when subclassing the :class:HTTPAdapter <requests.adapters.HTTPAdapter>.

Parameters:

proxy – The url of the proxy being used for this request.

Return type:

dict

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)

Sends PreparedRequest object. Returns Response object.

Parameters:

• request – The :class:PreparedRequest <PreparedRequest> being sent.

• stream – (optional) Whether to stream the request content.

• timeout (float or tuple or urllib3 Timeout object) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.

• verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use

• cert – (optional) Any user-provided SSL certificate to be trusted.

• proxies – (optional) The proxies dictionary to apply to the request.

Return type:

requests.Response

class tooluniverse.uspto_tool.Retry(total: bool | int | None = 10, connect: int | None = None, read: int | None = None, redirect: bool | int | None = None, status: int | None = None, other: int | None = None, allowed_methods: Collection[str] | None = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'}), status_forcelist: Collection[int] | None = None, backoff_factor: float = 0, backoff_max: float = 120, raise_on_redirect: bool = True, raise_on_status: bool = True, history: tuple[RequestHistory, ...] | None = None, respect_retry_after_header: bool = True, remove_headers_on_redirect: Collection[str] = frozenset({'Authorization', 'Cookie', 'Proxy-Authorization'}), backoff_jitter: float = 0.0)

Bases: object

Retry configuration.

Each retry attempt will create a new Retry object with updated values, so they can be safely reused.

Retries can be defined as a default for a pool:

retries = Retry(connect=5, read=2, redirect=5)
http = PoolManager(retries=retries)
response = http.request("GET", "https://example.com/")

Or per-request (which overrides the default for the pool):

response = http.request("GET", "https://example.com/", retries=Retry(10))

Retries can be disabled by passing `False`:

response = http.request("GET", "https://example.com/", retries=False)

Errors will be wrapped in :class:~urllib3.exceptions.MaxRetryError unless retries are disabled, in which case the causing exception will be raised.

Parameters:

• total (int) –

  Total number of retries to allow. Takes precedence over other counts.

  Set to `None` to remove this constraint and fall back on other counts.

  Set to `0` to fail on the first retry.

  Set to `False`` to disable and imply ``raise_on_redirect=False`.

• connect (int) –

  How many connection-related errors to retry on.

  These are errors raised before the request is sent to the remote server, which we assume has not triggered the server to process the request.

  Set to `0` to fail on the first retry of this type.

• read (int) –

  How many times to retry on read errors.

  These errors are raised after the request was sent to the server, so the request may have side-effects.

  Set to `0` to fail on the first retry of this type.

• redirect (int) –

  How many redirects to perform. Limit this to avoid infinite redirect loops.

  A redirect is a HTTP response with a status code 301, 302, 303, 307 or 308.

  Set to `0` to fail on the first retry of this type.

  Set to `False`` to disable and imply ``raise_on_redirect=False`.

• status (int) –

  How many times to retry on bad status codes.

  These are retries made on responses, where status code matches `status_forcelist`.

  Set to `0` to fail on the first retry of this type.

• other (int) –

  How many times to retry on other errors.

  Other errors are errors that are not connect, read, redirect or status errors. These errors might be raised after the request was sent to the server, so the request might have side-effects.

  Set to `0` to fail on the first retry of this type.

  If `total` is not set, it’s a good idea to set this to 0 to account for unexpected edge cases and avoid infinite retry loops.

• allowed_methods (Collection) –

  Set of uppercased HTTP method verbs that we should retry on.

  By default, we only retry on methods which are considered to be idempotent (multiple requests with the same parameters end with the same state). See :attr:Retry.DEFAULT_ALLOWED_METHODS.

  Set to a `None` value to retry on any verb.

• status_forcelist (Collection) –

  A set of integer HTTP status codes that we should force a retry on. A retry is initiated if the request method is in `allowed_methods` and the response status code is in `status_forcelist`.

  By default, this is disabled with `None`.

• backoff_factor (float) –

  A backoff factor to apply between attempts after the second try (most errors are resolved immediately by a second try without a delay). urllib3 will sleep for:

  {backoff factor} * (2 \** ({number of previous retries}))
  

  seconds. If backoff_jitter is non-zero, this sleep is extended by:

  random.uniform(0, {backoff jitter})
  

  seconds. For example, if the backoff_factor is 0.1, then :func:Retry.sleep will sleep for [0.0s, 0.2s, 0.4s, 0.8s, …] between retries. No backoff will ever be longer than backoff_max.

  By default, backoff is disabled (factor set to 0).

• raise_on_redirect (bool) – Whether, if the number of redirects is exhausted, to raise a MaxRetryError, or to return a response with a response code in the 3xx range.

• raise_on_status (bool) – Similar meaning to `raise_on_redirect`: whether we should raise an exception, or return a response, if status falls in `status_forcelist` range and retries have been exhausted.

• history (tuple) – The history of the request encountered during each call to :meth:~Retry.increment. The list is in the order the requests occurred. Each list item is of class :class:RequestHistory.

• respect_retry_after_header (bool) – Whether to respect Retry-After header on status codes defined as :attr:Retry.RETRY_AFTER_STATUS_CODES or not.

• remove_headers_on_redirect (Collection) – Sequence of headers to remove from the request when a response indicating a redirect is returned before firing off the redirected request.

DEFAULT_ALLOWED_METHODS = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'})

Default methods to be used for `allowed_methods`

RETRY_AFTER_STATUS_CODES = frozenset({413, 429, 503})

Default status codes to be used for `status_forcelist`

DEFAULT_REMOVE_HEADERS_ON_REDIRECT = frozenset({'Authorization', 'Cookie', 'Proxy-Authorization'})

Default headers to be used for `remove_headers_on_redirect`

DEFAULT_BACKOFF_MAX = 120

Default maximum backoff time.

DEFAULT: ClassVar[Retry] = Retry(total=3, connect=None, read=None, redirect=None, status=None)

__init__(total: bool | int | None = 10, connect: int | None = None, read: int | None = None, redirect: bool | int | None = None, status: int | None = None, other: int | None = None, allowed_methods: Collection[str] | None = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'}), status_forcelist: Collection[int] | None = None, backoff_factor: float = 0, backoff_max: float = 120, raise_on_redirect: bool = True, raise_on_status: bool = True, history: tuple[RequestHistory, ...] | None = None, respect_retry_after_header: bool = True, remove_headers_on_redirect: Collection[str] = frozenset({'Authorization', 'Cookie', 'Proxy-Authorization'}), backoff_jitter: float = 0.0) → None

new(**kw: Any) → Self

classmethod from_int(retries: Retry | bool | int | None, redirect: bool | int | None = True, default: Retry | bool | int | None = None) → Retry

Backwards-compatibility for the old retries format.

get_backoff_time() → float

Formula for computing the current backoff

Return type:

float

parse_retry_after(retry_after: str) → float

get_retry_after(response: BaseHTTPResponse) → float | None

Get the value of Retry-After in seconds.

sleep_for_retry(response: BaseHTTPResponse) → bool

sleep(response: BaseHTTPResponse | None = None) → None

Sleep between retry attempts.

This method will respect a server’s `Retry-After` response header and sleep the duration of the time requested. If that is not present, it will use an exponential backoff. By default, the backoff factor is 0 and this method will return immediately.

is_retry(method: str, status_code: int, has_retry_after: bool = False) → bool

Is this method/status code retryable? (Based on allowlists and control variables such as the number of total retries to allow, whether to respect the Retry-After header, whether this header is present, and whether the returned status code is on the list of status codes to be retried upon on the presence of the aforementioned header)

is_exhausted() → bool

Are we out of retries?

increment(method: str | None = None, url: str | None = None, response: BaseHTTPResponse | None = None, error: Exception | None = None, _pool: ConnectionPool | None = None, _stacktrace: TracebackType | None = None) → Self

Return a new Retry object with incremented retry counters.

Parameters:

• response (:class:~urllib3.response.BaseHTTPResponse) – A response object, or None, if the server did not return a response.

• error (Exception) – An error encountered during the request, or None if the response was received successfully.

Returns:

A new `Retry` object.

__repr__() → str

Return repr(self).

class tooluniverse.uspto_tool.BaseTool(tool_config)

Bases: object

__init__(tool_config)

classmethod get_default_config_file()

Get the path to the default configuration file for this tool type.

This method uses a robust path resolution strategy that works across different installation scenarios:

1. Installed packages: Uses importlib.resources for proper package resource access

2. Development mode: Falls back to file-based path resolution

3. Legacy Python: Handles importlib.resources and importlib_resources

Override this method in subclasses to specify a custom defaults file.

Returns:

Path or resource object pointing to the defaults file

classmethod load_defaults_from_file()

Load defaults from the configuration file

run(arguments=None)

Execute the tool.

The default BaseTool implementation accepts an optional arguments mapping to align with most concrete tool implementations which expect a dictionary of inputs.

check_function_call(function_call_json)

get_required_parameters()

Retrieve required parameters from the endpoint definition. Returns: list: List of required parameters for the given endpoint.

tooluniverse.uspto_tool.register_tool(tool_type_name=None, config=None)

Decorator to automatically register tool classes and their configs.

Usage:

@register_tool(‘CustomToolName’, config={…}) class MyTool:

pass

tooluniverse.uspto_tool.load_dotenv(dotenv_path: str | PathLike[str] | None = None, stream: IO[str] | None = None, verbose: bool = False, override: bool = False, interpolate: bool = True, encoding: str | None = 'utf-8') → bool

Parse a .env file and then load all the variables found as environment variables.

Parameters:

• dotenv_path – Absolute or relative path to .env file.

• stream – Text stream (such as io.StringIO) with .env content, used if dotenv_path is None.

• verbose – Whether to output a warning the .env file is missing.

• override – Whether to override the system environment variables with the variables from the .env file.

• encoding – Encoding to be used to read the file.

Returns:

True if at least one environment variable is set else False

Return type:

Bool

If both dotenv_path and stream are None, find_dotenv() is used to find the .env file with it’s default parameters. If you need to change the default parameters of find_dotenv(), you can explicitly call find_dotenv() and pass the result to this function as dotenv_path.

tooluniverse.uspto_tool.find_dotenv(filename: str = '.env', raise_error_if_not_found: bool = False, usecwd: bool = False) → str

Search in increasingly higher folders for the given file

Returns path to the file if found, or an empty string otherwise

class tooluniverse.uspto_tool.USPTOOpenDataPortalTool(tool_config, api_key=None, base_url='https://api.uspto.gov/api/v1')

Bases: BaseTool

A tool for interacting with the USPTO Open Data Portal API to search for and retrieve patent information. The run method dynamically constructs API requests based on the provided tool configuration.

__init__(tool_config, api_key=None, base_url='https://api.uspto.gov/api/v1')

Initializes the USPTOOpenDataPortalTool.

Parameters:

• tool_config – The configuration for the specific tool being run.

• api_key – Your USPTO Open Data Portal API key.

• base_url – The base URL for the USPTO API.

get_by_path(d, keys)

Safely navigate nested dicts by a list of keys.

assign_by_path(d, path, value)

Create nested dicts for a dot‑path and set the final key to value.

prune_item(item, return_fields)

run(arguments)

Runs the specified tool by constructing and executing an API call based on the tool’s configuration.

Parameters:

arguments – A dictionary of arguments for the tool, matching the parameters in the tool definition.

Returns:

The result of the API call, either as a dictionary (for JSON) or a string (for CSV).