Skip to main content

General REST api client with built in request caching and retries.

Project description

OWPHydroTools :: REST Client

Subpackage of objects and utilities suitable for quickly developing robust REST api libraries.

Main features:

  • RestClient: a class which offers asynchronous performance via a convenient serial wrapper, sqlite database GET request caching, GET request backoff, batch GET requests, and flexible url argument encoding.

  • Url: Treat urls like to pathlib.Paths. Supports appending paths with / and appending url query parameters with +.

  • ClientSession: Extension of aiohttp_client_cache that adds exponential backoff.

  • Variadic: Join list or tuple of objects on some delimiter. Useful when query parameters utilize a non-key=value&key=value2 pattern.

  • Alias and AliasGroup: Immutable utility classes that simplify common API library development patterns (i.e. separation of backend uris from front end interfaces).

See the REST Client Documentation for a complete list and description of the currently available methods. To report bugs or request new features, submit an issue through the OWPHydroTools Issue Tracker on GitHub.


In accordance with the python community, we support and advise the usage of virtual environments in any workflow using python. In the following installation guide, we use python's built-in venv module to create a virtual environment in which the tool will be installed. Note this is just personal preference, any python virtual environment manager should work just fine (conda, pipenv, etc. ).

# Create and activate python environment, requires python >= 3.8
$ python3 -m venv venv
$ source venv/bin/activate
$ python3 -m pip install --upgrade pip

# Install _restclient
$ python3 -m pip install hydrotools._restclient


The following example demonstrates how one might use hydrotools._restclient to write a simple REST api interface.


from hydrotools import _restclient

class BaconIpsum:
    """ Python API to """

    _base_url = ""

    # Return "meat-and-filler" if "mixed-meat" or "mixed" passed like:
    # _meat_and_filler["mixed-meat"] or _meat_and_filler.get("mixed")
    _meat_and_filler = _restclient.Alias("meat-and-filler", ["mixed-meat", "mixed"])
    _all_meat = _restclient.Alias("all-meat", ["all-meat", "all"])

    # Treat multiple alias as one alias
    _meat_options = _restclient.AliasGroup([_meat_and_filler, _all_meat])

    def __init__(self):
        self._restclient = _restclient.RestClient(
            cache_expire_after=43200, # in seconds

    def get(cls, type: str):
        Get either 'mixed-meat' / 'mixed' or 'all-meat' / 'all'
        Mixed contains filler 'lorem ipsum' text. All is just the meats!
        inst = cls()

        params = {"type": inst._meat_options[type], "sentences": 1, "format": "json"}

        response = inst._restclient.get(parameters=params)
        return response.json()

if __name__ == "__main__":



['Short loin tongue drumstick chuck beef meatball brisket ball tip pork loin doner kielbasa flank.']
['Andouille excepteur in, shankle irure laboris voluptate et ad incididunt.']

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for hydrotools.-restclient, version 3.0.3
Filename, size File type Python version Upload date Hashes
Filename, size hydrotools._restclient-3.0.3-py3-none-any.whl (18.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size hydrotools._restclient-3.0.3.tar.gz (17.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page