REST tools in python - common code for client and server
Project description
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 ofRestClient
that supports OAuth2 token refresh using the OpenID Connect Discovery protocol for an authentication server. -
ClientCredentialsAuth
: UsesOpenIDRestClient
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
: UsesOpenIDRestClient
to perform a "device" login for a user. Use this for user-based terminal applications that need to perform REST API calls. TheSavedDeviceGrantAuth
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)
...
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for wipac_rest_tools-1.7.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b52840d0b350f37d6349d24c33f9661c04f8465cf33209f603d2a6e71609c2ea |
|
MD5 | 72255721efab40bc3df7e6adb4ba0b5c |
|
BLAKE2b-256 | 043c84d73d0bb4bfefc3c865843f90d9ce604fd39ee4023965f0858d0b8cdd0a |