Skip to main content

PyPI GitHub release (latest by date including pre-releases) PyPI - License Lines of code GitHub issues GitHub pull requests

rest-tools

This project contains REST tools in python, as common code for multiple other projects under https://github.com/WIPACrepo.

All code uses python asyncio, so is fully asyncronous.

Note that both the client and server assume starting the asyncio loop happens elsewhere - they do not start the loop themselves.

Client

A REST API client exists under rest_tools.client. Use as:

from rest_tools.client import RestClient

api = RestClient('http://my.site.here/api', token='XXXX')
ret = await api.request('GET', '/fruits/apple')
ret = await api.request('POST', '/fruits', {'name': 'banana'})

There are several variations of the client for OAuth2/OpenID support:

  • OpenIDRestClient : A child of RestClient that supports OAuth2 token refresh using the OpenID Connect Discovery protocol for an authentication server.

  • ClientCredentialsAuth : Uses OpenIDRestClient in combination with OAuth2 client credentials (client ID and secret) for service-based auth. Use this for long-lived services that need to perform REST API calls.

  • DeviceGrantAuth / SavedDeviceGrantAuth : Uses OpenIDRestClient to perform a "device" login for a user. Use this for user-based terminal applications that need to perform REST API calls. The SavedDeviceGrantAuth can save the refresh token to disk, allowing repeated application sessions without having to log in again.

Server

A REST API server exists under rest_tools.server. Use as:

import asyncio
from rest_tools.server import RestServer, RestHandler

class Fruits(RestHandler):
    def post(self):
        # handle a new fruit
        self.write({})

server = RestServer()
server.add_route('/fruits', Fruits)
server.startup(address='my.site.here', port=8080)
asyncio.get_event_loop().run_forever()

The server uses Tornado to handle HTTP connections. It is recommended to use Apache or Nginx as a front-facing proxy, to handle TLS sessions and non-standard HTTP requests in production.

Handling Arguments Server-side

server.ArgumentHandler is a robust wrapper around argparse.ArgumentParser, extended for use in handling REST arguments, both query arguments and JSON-encoded body arguments. The intended design of this class is to follow the argparse pattern as closely as possible.

from rest_tools.server import RestHandler, ArgumentHandler, ArgumentSource

class Fruits(RestHandler):

    def get(self):
        argo = ArgumentHandler(ArgumentSource.QUERY_ARGUMENTS, self)

        argo.add_argument('name', type=str)  # de-facto required
        argo.add_argument('alias', dest='other_names', type=str, nargs='*', default=[])  # list

        argo.add_argument('is-citrus', type=bool, default=False)
        argo.add_argument('amount', type=float, required=True)

        args = argo.parse_args()

        fruit = get_fruit(args.name, args.other_names, args.is_citrus, args.amount)

        ...

    def post(self):
        argo = ArgumentHandler(ArgumentSource.JSON_BODY_ARGUMENTS, self)

        argo.add_argument('name', type=str)  # de-facto required
        argo.add_argument('other-names', type=list, default=[])

        argo.add_argument('supply', type=dict, required=True)

        def _origin(val):
            try:
                return {'USA': 'United States of America', 'MEX': 'Mexico'}[val]
            except KeyError:
                # raise a ValueError or TypeError to propagate a 400 Error
                raise ValueError('Invalid origin')

        argo.add_argument('country_code', dest='origin', type=_origin, required=True)

        args = argo.parse_args()

        add_to_basket(args.name, args.other_names, args.supply, args.origin)

        ...

Metadata

Release files for wipac-rest-tools 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wipac-rest-tools 1.8.0
File Size Uploaded Provenance Actions
wipac-rest-tools-1.8.0.tar.gz 32.5 kB Without provenance Details for wipac-rest-tools-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wipac-rest-tools 1.8.0
File Interpreter ABI Platform Actions
wipac_rest_tools-1.8.0-py3-none-any.whl Python 3 none any Details for wipac_rest_tools-1.8.0-py3-none-any.whl

Total release size: 70.3 kB

Release files / wipac-rest-tools-1.8.0.tar.gz

Download URL wipac-rest-tools-1.8.0.tar.gz
Size 32.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e38ce6318dec0aa64a4a0404edd596f6af2e51c62b6fce587a0a9be3a9de06d8
BLAKE2b-256 checksum
How to use checksums
962602adc903061fac43890c452fbf6d558263d5120f57888909db8ce3bdf075
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.11.1 readme-renderer/44.0 requests/2.32.3 requests-toolbelt/1.0.0 urllib3/2.2.3 tqdm/4.66.5 importlib-metadata/8.5.0 keyring/25.4.1 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.15

Release files / wipac_rest_tools-1.8.0-py3-none-any.whl

Download URL wipac_rest_tools-1.8.0-py3-none-any.whl
Size 37.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fcd23024dd99ff5fd815ca6743142952e0f11d696de3a8ec4436dc4b8eefe07c
BLAKE2b-256 checksum
How to use checksums
0f72ce4307ac94e29d50e037467cef1f1f664f5b4fffb4aa40d881ab0b1fedd3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.8.0 pkginfo/1.11.1 readme-renderer/44.0 requests/2.32.3 requests-toolbelt/1.0.0 urllib3/2.2.3 tqdm/4.66.5 importlib-metadata/8.5.0 keyring/25.4.1 rfc3986/2.0.0 colorama/0.4.6 CPython/3.10.15

Security for wipac-rest-tools 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.8.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page