rest-tools

This project contains REST tools in python, as common code for multiple other

_Description: _{REST tools in python - common code for client and server}
_Authors: _{WIPAC Developers / developers@icecube.wisc.edu}
_Keywords: _{WIPAC · IceCube · REST · tools · utilities}
_URLs: _{Homepage · Tracker · Source}

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.13.6

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.13.6
File	Size	Uploaded
wipac_rest_tools-1.13.6.tar.gz	76.1 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for wipac-rest-tools 1.13.6
File	Interpreter	ABI	Platform	Reset
wipac_rest_tools-1.13.6-py3-none-any.whl 45.8 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 121.9 kB

Release files / wipac_rest_tools-1.13.6.tar.gz

Download URL	wipac_rest_tools-1.13.6.tar.gz
Size	76.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`903e56cf43b98925fb479be99f48b180e2426f42ead5eb5e499291eee83dcc9d`
BLAKE2b-256 checksum How to use checksums	`d2060ad78da26181edff25dc57486e902d14911f4a059ade7b247b0ae6116930`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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

Download URL	wipac_rest_tools-1.13.6-py3-none-any.whl
Size	45.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c91a87776c8b7e9fd432ff967be35afd8bf3d041e614bec294e35a308667da3f`
BLAKE2b-256 checksum How to use checksums	`74d00340118d84ac0a597dec9b7023805c136f94e65cc925082d081635825074`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`