> built 2026-10-20 18:35 UTC from 1831bc2 (master) · py2http 0.1.78. Details: build_info.json
# index.html.md
[Documentation here](https://i2mint.github.io/py2http/)
# py2http
Dispatching Python functions as http services.
You have some python objects and want to get an “equivalent” http service from them…
## Usage
Run a basic HTTP service from a list of functions.
```python
from py2http.service import run_app
# Define or import functions
def add(a, b):
return a + b
def multiply(a, b):
return a * b
class Divider:
def __init__(self, dividend):
self.dividend = dividend
def divide(self, divisor):
return self.dividend / divisor
divider_from_ten = Divider(10)
# Make a list of functions or instance methods
func_list = [add, multiply, divider_from_ten.divide]
# Create an HTTP server
run_app(func_list, publish_openapi=True, publish_swagger=True)
```
The HTTP server will listen on port 3030 by default.
Given we asked for those options, you can:
* access the OpenAPI specification of the http-service at http://localhost:3030/openapi
* access the swagger docs and fiddle of the http-service at http://localhost:3030/swagger
* actually use the http-service’s routes, for example:
```python
# Test the server in a separate process
import requests
url = 'http://localhost:3030/add'
add_args = {'a': 20, 'b': 22}
requests.post(url, json=add_args).json()
# should return 42
```
## Configuration
`run_app` accept many configuration values to customize the handling of HTTP requests and responses. Configuration documentation is listed in the file `config.yaml`.
## Method transformation
Expose class methods by flattening the init -> method call process.
```python
from py2http import run_app
from py2http.decorators import mk_flat
class Adder:
def __init__(self, a):
self.a = a
def add(self, b):
return self.a + b
add = mk_flat(Adder, Adder.add, func_name='add')
func_list = [add]
run_app(func_list)
```
## Input mapping
By default, the server will only accept JSON requests and parse the values from the request body as keyword arguments. You can define custom input mappers to perform extra handling on the JSON body or directly on the HTTP library request object, such as default injection or type mapping.
```python
from numpy import array
import soundfile
from py2http.decorators import handle_json_req
from my_service.data import fetch_user_data
@handle_json_req # extracts the JSON body and passes it to the input mapper as a dict
def array_input_mapper(input_kwargs):
return {'arr': array(input_kwargs.get('arr', [])),
'scalar': input_kwargs.get('scalar', 1)}
@handle_multipart_req # extracts a multipart body and passes it as a dict
def sound_file_input_mapper(input_kwargs):
file_input = input_kwargs['file_upload']
filename = file_input.filename
file_bytes = BytesIO(file_input.file)
wf, sr = soundfile.read(file_bytes)
return dict(input_kwargs, wf=wf, sr=sr, filename=filename)
def custom_header_input_mapper(req): # takes a raw aiohttp request
user = req.headers.get('User', '')
return {'user': user}
def array_multiplier(arr, scalar):
return arr * scalar
def save_audio(wf, sr, filename, storage_path='/audio'):
target = os.path.join(storage_path, filename)
soundfile.write(target, wf, sr)
def get_user_data(user):
return fetch_user_data(user)
array_multiplier.input_mapper = array_input_mapper
save_audio.input_mapper = sound_file_input_mapper
get_user_data.input_mapper = custom_header_input_mapper
```
## Output mapping
By default, the server will send the return value of the handler function in an HTTP response in JSON format. You can define custom output mappers to perform extra handling or type conversion.
```python
from io import BytesIO
import soundfile
from py2http.decorators import send_json_resp, send_html_resp
from my_service.data import fetch_blog
@send_json_resp # sends a JSON response
def array_output_mapper(output, input_kwargs):
return {'array_value': output['array_value'].tolist()}
@send_html_resp # sends an HTML response
def mk_html_list(output, input_kwargs):
tag = input_kwargs.get('tag', 'p')
item_list = output.split('\n')
result = [f'<{tag}>{item}' for item in item_list]
return ''.join(result)
def return_wav(output, input_kwargs):
wf, sr = output
wf_bytes = BytesIO()
soundfile.write(wf_bytes, wf, sr)
binary_result = wf_bytes.read()
return web.Response(body=binary_result, content_type='application/octet-stream')
def array_multiplier(arr, scalar):
return arr * scalar
def get_blog_posts(page):
return fetch_blog(page)
def download_audio(filename):
with open(filename) as fp:
wf, sr = soundfile.read(fp)
return wf, sr
array_multipler.output_mapper = array_output_mapper
get_blog_posts.output_mapper = mk_html_list
download_audio.output_mapper = return_wav
```
## Error handling
TODO
## Client generation
Py2http generates an OpenAPI specification for the server before running. You can use this document with any OpenAPI-compatible client tools. To extract the specification, you can generate a server application object before running it.
```python
import json
from py2http import mk_app, run_app
def add(a, b):
return a + b
func_list = [add]
app = mk_app(func_list)
openapi_spec = app.openapi_spec
with open('~/openapi.json', 'w') as fp:
json.dump(openapi_spec, fp)
run_app(app, port=3030)
```
## Configuration
Functions that generate an HTTP service, such as `run_app`, accept a number of keyword arguments for configuration. The available configuration arguments are listed below with their defaults.
* `framework=py2http.config.BOTTLE` The HTTP framework to use.
* `input_mapper=py2http.default_configs.default_input_mapper` A function to map an HTTP request to a dict of input arguments.
* `output_mapper=py2http.default_configs.default_output_mapper` A function to map the output of a function to an HTTP response.
* `error_handler=py2http.default_configs.default_error_handler` A function to map an exception to an HTTP response.
* `header_inputs={}` A dict of object properties in JSON schema format describing keys that should be excluded from request body definitions. These inputs are expected to be extracted from the request headers in the input mapper.
* `host='localhost'` The hostname the server can be reached at, to include in the OpenAPI specification.
* `port=3030` The TCP port to listen on.
* `http_method='post'` The default HTTP method for exposing functions, if a function does not specify its method.
* `openapi={}` A dict with several configuration options specific to the OpenAPI specification, described below.
* `logger=None` An object that implements a `log` method.
* `app_name='HTTP Service'` The name of the application (Flask only).
* `middleware=[]` A list of middlewares to run (aiohttp only).
* `plugins=[]` A list of plugins to install (bottle only).
* `enable_cors=False` Whether to enable CORS features.
* `cors_allowed_origins='*'` If CORS is enabled, the value to pass in the Access-Control-Allow-Origin header.
* `publish_openapi=False` Whether to add a GET /openapi route to the app that returns the OpenAPI specification.
* `openapi_insecure=False` Whether to skip middlewares and plugins for the /openapi route (disabling any authentication).
* `publish_swagger=False` Whether to add a GET route to the app that returns a Swagger HTML interface.
* `swagger_url='/swagger'` The URL of the swagger route.
* `swagger_title='Swagger'` The title to display on the Swagger HTML page.
* `ssl_certfile=None` The path to a valid SSL certificate.
* `ssl_keyfile=None` The path to a valid SSL certificate’s key.
OpenAPI configuration:
These values will be put in the OpenAPI specification document. All values are optional.
* `title` The title of the application.
* `version` The version number of the application.
* `auth`: A dict specifying the authentication details to include in the document, to make it easier for clients to automate authentication.
* `auth['auth_type']` Either ‘jwt’ or ‘api_key’.
* `auth['login_details']` A dict describing how a client can log in (for jwt authentication only).
* `auth['login_details']['login_url']` The URL of the login route.
* `auth['login_details']['refresh_url']`: The URL of the refresh route.
* `auth['login_details']['login_inputs']`: A list of strings with the keys expected by the login endpoint.
* `auth['login_details']['refresh_inputs']`: A list of strings with the keys expected by the refresh endpoint.
* `auth['login_details']['outputs']`: A list of strings with the keys returned by the login/refresh endpoints.,
This documentation as a single file: py2http.md (Markdown, for agents).
# _autosummary/py2http.auth.html.md
# py2http.auth
Framework-independent credential checks, shared by the aiohttp middleware
(`py2http.middleware`) and the Bottle plugins (`py2http.bottle_plugins`), so that
both refuse the same tokens and keys for the same reasons.
```pycon
>>> bearer_token('Bearer abc'), bearer_token('bearer abc'), bearer_token('Basic abc')
('abc', 'abc', '')
>>> key_matches('k-123', 'k-123'), key_matches('k-12', 'k-123'), key_matches(None, 'k')
(True, False, False)
```
### Functions
| [`bearer_token`](_autosummary/py2http.auth.html.md#py2http.auth.bearer_token)(authorization_header) | The token of an `Authorization: Bearer ` header, or `''`. |
|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| [`decode_jwt`](_autosummary/py2http.auth.html.md#py2http.auth.decode_jwt)(token, secret, \*, algorithms[, ...]) | The claims of `token`, or `CredentialsRejected` with a client-safe reason. |
| [`jwt_algorithms`](_autosummary/py2http.auth.html.md#py2http.auth.jwt_algorithms)(secret, \*[, verify, ...]) | Validate a JWT verification setup, returning the algorithms as a list. |
| [`jwt_decode_kwargs`](_autosummary/py2http.auth.html.md#py2http.auth.jwt_decode_kwargs)([decode_kwargs]) | Validate extra `jwt.decode` arguments (`audience`, `issuer`, `leeway`...), refusing those the verification setup owns. |
| [`key_matches`](_autosummary/py2http.auth.html.md#py2http.auth.key_matches)(given, expected) | Whether the `given` credential equals `expected`, in constant time. |
| [`required_key`](_autosummary/py2http.auth.html.md#py2http.auth.required_key)(key, \*[, name]) | `key`, refused when empty: an empty key would let a request with no `Authorization` header through. |
### Classes
| [`AuthPlugin`](_autosummary/py2http.auth.html.md#py2http.auth.AuthPlugin)() | What a plugin must be to guard a Flask app (see `py2http.flask_plugins`): a subclass with a `challenge` (the `WWW-Authenticate` value of a refusal) and an `authenticate` that raises `CredentialsRejected` to refuse a request. |
|-----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### Exceptions
| [`CredentialsRejected`](_autosummary/py2http.auth.html.md#py2http.auth.CredentialsRejected) | A request's credentials were refused. |
|------------------------------------------------------------------------|-----------------------------------------|
### *class* py2http.auth.AuthPlugin
Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)
What a plugin must be to guard a Flask app (see `py2http.flask_plugins`): a
subclass with a `challenge` (the `WWW-Authenticate` value of a refusal) and an
`authenticate` that raises `CredentialsRejected` to refuse a request. It is a
marker class rather than a duck-typed method name, so that a plugin which merely has
some `authenticate` method (returning `False` to refuse, say) can’t be mistaken
for one and let everything through.
#### authenticate(authorization_header, , method, endpoint)
The claims to put on the request, or `None`; `CredentialsRejected` refuses.
### *exception* py2http.auth.CredentialsRejected
Bases: [`Exception`](https://docs.python.org/3/builtins/exceptions.html#Exception)
A request’s credentials were refused. The message is safe to show the client:
it never contains the token, nor anything about the server’s key.
### py2http.auth.bearer_token(authorization_header)
The token of an `Authorization: Bearer ` header, or `''`.
* **Return type:**
[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)
### py2http.auth.decode_jwt(token, secret, , algorithms, verify=True, decode_kwargs=None)
The claims of `token`, or `CredentialsRejected` with a client-safe reason.
With `verify=False` neither the signature nor the claims (`exp`…) are checked.
`decode_kwargs` (`audience`, `issuer`, `leeway`…) go to `jwt.decode`.
* **Return type:**
[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)
### py2http.auth.jwt_algorithms(secret, , verify=True, algorithms=('HS256',), allow_mixed_algorithm_families=False)
Validate a JWT verification setup, returning the algorithms as a list.
Raises at construction time, rather than accepting forgeries at request time, when:
- `algorithms` is empty, a bare string, or names an unknown or unsigned (`none`)
algorithm (PyJWT names are case-sensitive);
- `verify` is True and `secret` is empty (an empty HMAC secret lets anyone sign
tokens), or an HMAC algorithm is asked for with a non-`str`/`bytes` secret;
- `verify` is True and HMAC and public-key algorithms are mixed with one
`secret` (the classic algorithm-confusion setup), unless
`allow_mixed_algorithm_families` is True.
```pycon
>>> jwt_algorithms('s3cret')
['HS256']
>>> jwt_algorithms('', algorithms=['HS256'])
Traceback (most recent call last):
...
ValueError: secret must be a non-empty key when verify=True
```
* **Return type:**
[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)
### py2http.auth.jwt_decode_kwargs(decode_kwargs=None)
Validate extra `jwt.decode` arguments (`audience`, `issuer`,
`leeway`…), refusing those the verification setup owns.
```pycon
>>> jwt_decode_kwargs({'audience': 'my-api'})
{'audience': 'my-api'}
>>> jwt_decode_kwargs({'options': {'verify_signature': False}})
Traceback (most recent call last):
...
ValueError: decode_kwargs may not set ['options']; use verify= and algorithms=
```
* **Return type:**
[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)
### py2http.auth.key_matches(given, expected)
Whether the `given` credential equals `expected`, in constant time.
* **Return type:**
[`bool`](https://docs.python.org/3/builtins/functions.html#bool)
### py2http.auth.required_key(key, , name='api_key')
`key`, refused when empty: an empty key would let a request with no
`Authorization` header through.
# _autosummary/py2http.bottle_plugins.html.md
# py2http.bottle_plugins
Plugins for adding middleware functionality to Bottle apps.
### Classes
| [`ApiKeyAuthPlugin`](_autosummary/py2http.bottle_plugins.html.md#py2http.bottle_plugins.ApiKeyAuthPlugin)(api_key) | A plugin letting through only requests whose `Authorization` header is exactly `api_key` (compared in constant time; an empty key is refused). |
|-------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `CorsPlugin`([origins]) | |
| [`JWTPlugin`](_autosummary/py2http.bottle_plugins.html.md#py2http.bottle_plugins.JWTPlugin)([secret, verify, mapper, ...]) | A plugin for validating JWTs and extracting their payloads. |
### *class* py2http.bottle_plugins.ApiKeyAuthPlugin(api_key)
Bases: [`AuthPlugin`](_autosummary/py2http.auth.html.md#py2http.auth.AuthPlugin)
A plugin letting through only requests whose `Authorization` header is
exactly `api_key` (compared in constant time; an empty key is refused).
#### authenticate(authorization_header, , method, endpoint)
`None` (the key sets nothing on the request) if the header is the key,
else `CredentialsRejected`. Framework-independent, like `JWTPlugin`’s.
### *class* py2http.bottle_plugins.JWTPlugin(secret='', verify=True, mapper=None, ignore_methods=None, algorithms=None, , allow_mixed_algorithm_families=False, decode_kwargs=None)
Bases: [`AuthPlugin`](_autosummary/py2http.auth.html.md#py2http.auth.AuthPlugin)
A plugin for validating JWTs and extracting their payloads.
After optionally validating a JWT found in the request header, will assign a dict with the JWT claims
to request.token.
#### authenticate(authorization_header, , method, endpoint)
The claims to put on the request (`None` when there are none to put), or
`CredentialsRejected`. Framework-independent: the Bottle plugin and the Flask
`before_request` hook (`py2http.flask_plugins`) both call it.
# _autosummary/py2http.config.html.md
# py2http.config
The code module provides functions for retrieving configuration values for a
function based on a hierarchy of sources, including function properties,
configuration dictionaries, and default values. The `get_result` function is used to
allow nested configurations by function name, with an example provided in the docstring
for illustration.
The `mk_config` function is used to get a configuration value for a function by checking
the function properties, configuration dictionaries, and default values. It also allows
for specifying the expected type of the output, with options to provide additional
options such as the function name and expected type.
Overall, the module helps manage and retrieve configuration values for functions,
ensuring they are appropriately set and validated based on the function’s requirements.
### Functions
| [`get_result`](_autosummary/py2http.config.html.md#py2http.config.get_result)(configs, func, funcname, key, options) | this is meant to allow nested configs by function name example: |
|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`mk_config`](_autosummary/py2http.config.html.md#py2http.config.mk_config)(key, func, configs, defaults, ...) | Get a config value for a function. |
### py2http.config.get_result(configs, func, funcname, key, options)
this is meant to allow nested configs by function name
example:
# TODO: See mk_config use and make an actual doctest for get_result
# >>> def create_something():
# … pass
# >>> example_configs = {‘http_method’: {
# … ‘create_something’: ‘post’,
# … ‘get_something’: ‘get’,
# … }}
# >>> defaults = {‘create_something’: ‘DEFAULTED’}
# >>> get_result(example_configs, create_something, ‘create_something’, ‘http_method’, defaults)
# ‘post’
### py2http.config.mk_config(key, func, configs, defaults, \*\*options)
Get a config value for a function. First checks the properties of the function,
then the configs, then the defaults.
* **Parameters:**
* **key** – The key to search for
* **func** – The function associated with the config
* **configs** – A config dict to search
* **defaults** – The default configs to fall back on
* **\*\*options** – Additional options
* **Keyword Arguments:**
* *funcname*
The name of the function, if not the same as func._\_name_\_
* *type*
The expected type of the output (use Callable for functions)
# _autosummary/py2http.constants.html.md
# py2http.constants
This module provides functionality for dispatching Python functions as HTTP services. It allows users to create a basic HTTP server from a list of functions or instance methods, customize input and output mapping, handle errors, generate client code from an OpenAPI specification, and configure various aspects of the server setup. The module includes features for transforming class methods, mapping input and output data, handling errors, and generating client code. It also supports configuration options for the HTTP framework, input and output mappers, error handlers, openAPI specifications, logging, middleware, plugins, CORS, SSL certificates, and more.
### Module Attributes
| [`WWW_AUTHENTICATE_ENV_VAR`](_autosummary/py2http.constants.html.md#py2http.constants.WWW_AUTHENTICATE_ENV_VAR) | Environment variable naming the challenge for a 401 a dispatched function raised (`AuthorizationError`); the deployment's auth decides it. |
|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
### py2http.constants.WWW_AUTHENTICATE_ENV_VAR *= 'PY2HTTP_WWW_AUTHENTICATE'*
Environment variable naming the challenge for a 401 a dispatched function raised
(`AuthorizationError`); the deployment’s auth decides it. Default: Bearer.
# _autosummary/py2http.decorators.html.md
# py2http.decorators
Decorator tools for py2http.
### Functions
| [`add_attrs`](_autosummary/py2http.decorators.html.md#py2http.decorators.add_attrs)(\*\*attrs) | Makes a function that adds attributes to a function. |
|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `base_output_mapper`(output, \*\*inputs) | |
| `binary_output`(func) | |
| [`ensure_awaitable_return_annot`](_autosummary/py2http.decorators.html.md#py2http.decorators.ensure_awaitable_return_annot)(func) | |
| [`flatten_callables`](_autosummary/py2http.decorators.html.md#py2http.decorators.flatten_callables)(\*callables[, func_name]) | Flatten a pipeline of calls into one function. |
| `flatten_methods`(methods[, decorator, ...]) | |
| [`handle_binary_req`](_autosummary/py2http.decorators.html.md#py2http.decorators.handle_binary_req)(func, \*[, loads]) | Make an input mapper that decodes a binary (octet-stream) request body. |
| `handle_form_req`(func) | |
| `handle_json_req`(func) | |
| `handle_raw_req`(func) | |
| `http_delete`(func) | |
| `http_get`(func) | |
| `http_post`(func) | |
| `http_put`(func) | |
| `ignore_extra_arguments`(func) | |
| [`inject_methodized_funcs`](_autosummary/py2http.decorators.html.md#py2http.decorators.inject_methodized_funcs)([cls, funcs, ...]) | |
| [`methodizer`](_autosummary/py2http.decorators.html.md#py2http.decorators.methodizer)([func, instance_params]) | A decorator to get method versions of functions. |
| [`mk_flat`](_autosummary/py2http.decorators.html.md#py2http.decorators.mk_flat)(cls, method, \*[, func_name, ...]) | Flatten a simple cls->instance->method call pipeline into one function. |
| `mk_handlers`(methods, \*[, decorator, ...]) | |
| `mk_input_mapper`(input_map) | |
| [`params_replacer`](_autosummary/py2http.decorators.html.md#py2http.decorators.params_replacer)(replace, obj) | Generator of transformed params. |
| [`replace_with_params`](_autosummary/py2http.decorators.html.md#py2http.decorators.replace_with_params)([target, source, inplace]) | Will return a version of the target type that has params taken from source. |
| `route`(route_name) | |
| `send_binary_resp`(func) | |
| `send_html_resp`(func) | |
| `send_json_resp`(func) | |
| `send_raw_resp`(func) | |
| [`unsafe_pickle_loads`](_autosummary/py2http.decorators.html.md#py2http.decorators.unsafe_pickle_loads)(data) | Unpickle `data`. |
### Classes
| `DecoParam`(default, annotation) | |
|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`DecoParameter`](_autosummary/py2http.decorators.html.md#py2http.decorators.DecoParameter)(name, kind, \*, default, annotation) | A Parameter object that is meant to be the a parameter of a decorator factory. |
| [`Decora`](_autosummary/py2http.decorators.html.md#py2http.decorators.Decora)([func]) | A version of Decorator where you can define your subclasses by defininig attributes of the subclass (instead of writing a manual \_\_new_\_ method). |
| [`Decorator`](_autosummary/py2http.decorators.html.md#py2http.decorators.Decorator)([func]) | A "transparent" decorator meant to be used to subclass into specialized decorators. |
| [`JsonRespEncoder`](_autosummary/py2http.decorators.html.md#py2http.decorators.JsonRespEncoder)(\*[, skipkeys, ensure_ascii, ...]) | |
| [`Literal`](_autosummary/py2http.decorators.html.md#py2http.decorators.Literal)(val) | An object to indicate that the value should be considered literally |
| [`ParamsSpecifier`](_autosummary/py2http.decorators.html.md#py2http.decorators.ParamsSpecifier)([_annotations, \_names, ...]) | A tool to specify params (that is, lists of inspect.Parameter instances that are used in callable signatures. |
| [`ProposalJsonRespEncoder`](_autosummary/py2http.decorators.html.md#py2http.decorators.ProposalJsonRespEncoder)(\*[, skipkeys, ...]) | |
### *class* py2http.decorators.DecoParameter(name, kind, , default, annotation)
Bases: [`Parameter`](https://docs.python.org/3/library/inspect.html#inspect.Parameter)
A Parameter object that is meant to be the a parameter of a decorator factory.
Subclassing inspect.Parameter so that it can be distinguished from it if needed.
### *class* py2http.decorators.Decora(func=None, \*\*kwargs)
Bases: [`Decorator`](_autosummary/py2http.decorators.html.md#py2http.decorators.Decorator)
A version of Decorator where you can define your subclasses by defininig attributes
of the subclass (instead of writing a manual \_\_new_\_ method).
Here’s a typical use, as a decorator factory…
```pycon
>>> from py2http.decorators import Decora, ParamsSpecifier
>>>
>>>
>>> class whatevs(ParamsSpecifier):
... minus = 3
... times: float
... repeat: int = 2
>>>
>>> class Deco(Decora):
... my_params = whatevs()
...
... def __call__(self, *args, **kwargs):
... func_result = super().__call__(*args, **kwargs)
... return func_result[0], [func_result[1] * self.times - self.minus] * self.repeat
>>>
>>> def f(w: float, x: int=0, greet='hi'):
... return greet, w + x
>>>
>>>
>>>
>>> g = Deco(times=3)(f)
>>> assert g(0) == ('hi', [-3] * 2)
>>> assert g(10) == ('hi', [27] * 2)
>>> assert g(10, x=1, greet='hello') == ('hello', [30, 30])
>>>
>>> g = Deco(f, times=1, minus=2, repeat=3)
>>> assert g(0) == ('hi', [-2, -2, -2])
>>> g = Deco(times=0, minus=3, repeat=1)(f)
>>> assert g(10) == ('hi', [-3])
>>> g = Deco(times=2, minus=0, repeat=1)(f)
>>> assert g(10) == ('hi', [20])
>>> f = lambda x, y=1: x + y
>>> f(10)
11
>>> signature(f)
>>>
```
More examples (of different forms)
```pycon
>>> class LogCalls(Decora):
... class DecoParams(ParamsSpecifier):
... verb: str = 'calling' # will be taken and included in the __init__
... decoy = None # will be taken (but not actually used in __call__)
...
... def __call__(self, *args, **kwargs):
... print(f'{self.verb} {self.func.__name__} with {args} and {kwargs}')
... return super().__call__(*args, **kwargs)
...
>>> ff = LogCalls(f, verb='launching') # doing it the "decorator way"
>>> assert ff(10) == 11
launching with (10,) and {}
>>> signature(ff)
>>> assert signature(ff) == signature(f) # asserting same signature as the wrapped f
>>> signature(LogCalls) # the signature of the decorator itself
>>>
>>> ff = LogCalls()(f) # defaults work when using as factory
>>> signature(ff)
>>> ff(10)
calling with (10,) and {}
11
>>> ff = LogCalls(f) # defaults work when using as decorator
>>> ff(10)
calling with (10,) and {}
11
>>>
>>> LogCalls(f, real_arg=False) # rejects arguments that weren't "registered" by the __new__
Traceback (most recent call last):
...
TypeError: TypeError: __new__() got unexpected keyword arguments: {'real_arg'}
>>>
```
But you can still do it with \_\_new_\_ if you want
```pycon
>>> class ProcessOutput(Decora):
... def __new__(cls, func=None, *, postproc=None):
... postproc = postproc or (lambda x: x)
... return super().__new__(cls, func, postproc=postproc)
...
... def __call__(self, *args, **kwargs):
... return self.postproc(super().__call__(*args, **kwargs))
...
>>> fff = ProcessOutput(postproc=str)(f) # doing it the "decorator factory way"
>>> assert fff(10) == "11"
>>> assert signature(fff) == signature(f)
>>> signature(ProcessOutput) # the signature of the decorator itself
>>>
>>> # Verifying that LogCalls still has the right signature
>>> signature(LogCalls) # the signature of the decorator itself
```
### *class* py2http.decorators.Decorator(func=None, \*\*kwargs)
Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)
A “transparent” decorator meant to be used to subclass into specialized decorators.
The signature of the wrapped function is carried to the \_\_call_\_ of the decorated instance.
To specialize (and do something else than just “transparent” wrapping, you need to subclass
Decorator and define your own `__call__` method. You may assume that
The decorator pattern is a significant reuse tool, and indeed we use them a lot in i2i tooling.
The standard way is to write decorators (and decorator factories) the functional was,
but writing them as classes has introspection (therefore debuggability) advantages.
The approach comes with other kinds of problems though.
One of them is signature transfer (both for the decorator and the decorator factory).
Taken care of here.
Another wish (not really a problem) is to be able to use both `deco(func, params)`
and `deco(params(func))` forms. Also taken care of here.
Another problem is an increased boilerplate in specifying the decorator mechanics.
For example: If you want to have a proper signature (not just \*\*kwargs),
you need to overwrite `__new__` for the sole purpose of specifying the arguments
(names, and optional annotations and defaults).
This problem is not taken care of here, but you can check out `Decora`,
a subclass of Decorator, that does.
```pycon
>>> from py2http.decorators import Decorator
>>> f = lambda x, y=1: x + y # a function to decorate
>>> f(10)
11
>>> signature(f)
>>>
>>> class LogCalls(Decorator):
... def __new__(cls, func=None, *, verb='calling'):
... return super().__new__(cls, func, verb=verb)
...
... def __call__(self, *args, **kwargs):
... print(f'{self.verb} {self.func.__name__} with {args} and {kwargs}')
... return super().__call__(*args, **kwargs)
...
>>> ff = LogCalls(f, verb='launching') # doing it the "decorator way"
>>> assert ff(10) == 11
launching with (10,) and {}
>>> signature(ff)
>>> assert signature(ff) == signature(f) # asserting same signature as the wrapped f
>>> signature(LogCalls)
>>>
>>> class ProcessOutput(Decorator):
... def __new__(cls, func=None, *, postproc=None):
... postproc = postproc or (lambda x: x)
... return super().__new__(cls, func, postproc=postproc)
...
... def __call__(self, *args, **kwargs):
... return self.postproc(super().__call__(*args, **kwargs))
...
>>>
>>>
>>> fff = ProcessOutput(postproc=str)(f) # doing it the "decorator factory way"
>>> assert fff(10) == "11"
>>> assert signature(fff) == signature(f)
>>> signature(ProcessOutput)
>>>
>>> ff = LogCalls()(f) # defaults work when using as factory
>>> signature(ff)
>>> ff(10)
calling with (10,) and {}
11
>>> ff = LogCalls(f) # defaults work when using as decorator
>>> ff(10)
calling with (10,) and {}
11
>>> # rejects arguments that weren't "registered" by the __new__:
>>> LogCalls(f, real_arg=False)
Traceback (most recent call last):
...
TypeError: __new__() got an unexpected keyword argument 'real_arg'
```
### *class* py2http.decorators.JsonRespEncoder(, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)
Bases: [`JSONEncoder`](https://docs.python.org/3/library/json.html#json.JSONEncoder)
#### default(o)
Implement this method in a subclass such that it returns
a serializable object for `o`, or calls the base implementation
(to raise a `TypeError`).
For example, to support arbitrary iterators, you could
implement default like this:
```default
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return super().default(o)
```
### *class* py2http.decorators.Literal(val)
Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)
An object to indicate that the value should be considered literally
### *class* py2http.decorators.ParamsSpecifier(\_annotations=None, \_names='', \_dflt_default=None, \_kind=\_ParameterKind.KEYWORD_ONLY, \*\*name_and_dflts)
Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)
A tool to specify params (that is, lists of inspect.Parameter instances that
are used in callable signatures.
But wait! you may not need this!
Often the cleanest way to make a signature, or list of Parameters is to define an empty function
with that signature, and extract it from there.
See `Decora` for the original intended use of ParamsSpecifier.
```pycon
>>> from inspect import signature, Signature, Parameter
>>> def f(a, b: int, c: float = 0.0, d: str='hi'): ...
>>> sig = signature(f)
>>> sig
>>> list(sig.parameters.values())
[, , , ]
```
The reason for the existence of ParamsSpecifier was to do some magic around giving class-based
decorators a signature. The reasons of this magic may be outdated soon.
```pycon
>>> from py2http.decorators import ParamsSpecifier
>>> from inspect import Parameter, Signature
>>> KO = Parameter.KEYWORD_ONLY
>>>
>>> class MyParams(ParamsSpecifier):
... b = 3
... z: float
... c: int = 2
...
>>> params = MyParams()()
>>> expected_params = [
... {'name': 'z', 'kind': KO, 'default': None, 'annotation': float},
... {'name': 'b', 'kind': KO, 'default': 3},
... {'name': 'c', 'kind': KO, 'default': 2, 'annotation': int}]
>>> assert params == expected_params
```
See that the params are all valid kwargs to inspect.Parameter, by making a signature from them
```pycon
>>> Signature(Parameter(**p) for p in params)
```
Let’s now get another params specifier.
```pycon
>>> get_new_params = MyParams(
... _annotations=dict(b=int, a=str),
... _names='a wol',
... another='here')
>>> params = get_new_params()
>>> expected_params = [
... {'name': 'z', 'kind': KO, 'default': None, 'annotation': float},
... {'name': 'b', 'kind': KO, 'default': 3, 'annotation': int},
... {'name': 'c', 'kind': KO, 'default': 2, 'annotation': int},
... {'name': 'another', 'kind': KO, 'default': 'here'},
... {'name': 'a', 'kind': KO, 'default': None, 'annotation': str},
... {'name': 'wol', 'kind': KO, 'default': None}]
```
One thing to note in the expected_params is the order.
Indeed, the order is not the order that is taken (because couldn’t figure out otherwise)
is as such:
- First the class-level attributes that are annotated, but not given a default
: (though a blanket \_dflt_default default will be given to them all).
Here order is not assured.
- Second the reset of the class-level attributes, in the order they were defined.
- Third the instance argument params given by the \_names argument, in the order they were listed.
- Finally the instance argument name_and_dflts params, in the order they were listed.
Remember, all this is meant to provide ways to specify signatures.
```pycon
>>> Signature(Parameter(**p) for p in params)
```
Now, not that ParamsSpecifier is the tool for this, but to demo what ParamsSpecifier’s
params are, we’ll give one last example where we take a function, make a ParamsSpecifier
from it, and add a different kind of default
```pycon
>>> def f(a, b: int, c: float = 0.0, d: str='hi'): ...
>>> param_maker = ParamsSpecifier.from_func(f, _dflt_default='a different dflt')
>>> Signature(Parameter(**p) for p in param_maker())
```
### *class* py2http.decorators.ProposalJsonRespEncoder(, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)
Bases: [`JSONEncoder`](https://docs.python.org/3/library/json.html#json.JSONEncoder)
#### default(o)
Implement this method in a subclass such that it returns
a serializable object for `o`, or calls the base implementation
(to raise a `TypeError`).
For example, to support arbitrary iterators, you could
implement default like this:
```default
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return super().default(o)
```
### py2http.decorators.add_attrs(\*\*attrs)
Makes a function that adds attributes to a function.
Used in it’s normal context, it looks something like this:
```pycon
>>> @add_attrs(my_special_attr='my special value', another=42)
... def foo(x):
... return x + 1
>>>
>>> foo(10) # checking that this great function still works
11
>>> # checking that it now has some extra attributes
>>> foo.my_special_attr
'my special value'
>>> foo.another
42
```
But it can be useful to make attribute adder, and reuse when needed.
```pycon
>>> brand_my_func = add_attrs(author="me")
>>> _ = brand_my_func(foo) # not capturing the output to show that the change happens in-place
>>> foo.author
'me'
```
### py2http.decorators.ensure_awaitable_return_annot(func)
```pycon
>>> async def foo(x: str) -> int: ...
>>> assert str(signature(foo)) == '(x: str) -> int'
>>> assert str(signature(ensure_awaitable_return_annot(foo))) == '(x: str) -> Awaitable[int]'
>>>
>>> # but if func is not async, don't change anything
>>> def bar(a) -> str: ...
>>> assert str(signature(bar)) == str(signature(ensure_awaitable_return_annot(bar))) == '(a) -> str'
>>>
>>> # or if the return annotation is already contained in an Awaitable, don't change anything
>>> async def baz() -> Awaitable[float]: ...
>>> assert str(signature(baz)) == str(signature(ensure_awaitable_return_annot(baz))) == '() -> Awaitable[float]'
```
### py2http.decorators.flatten_callables(\*callables, func_name=None)
Flatten a pipeline of calls into one function.
### py2http.decorators.handle_binary_req(func, , loads=None)
Make an input mapper that decodes a binary (octet-stream) request body.
`loads` turns the raw body bytes into the mapping of keyword arguments for
`func`. There is deliberately no default: request bodies used to be
unpickled implicitly, which lets any client run code on the server. Pass a
safe decoder of your own, or `loads=unsafe_pickle_loads` if (and only if)
every client is trusted.
Note that `http2py` clients encode binary request bodies with pickle, so
they only work against endpoints that opted into `unsafe_pickle_loads`.
```pycon
>>> handle_binary_req(lambda x: x)
Traceback (most recent call last):
...
TypeError: handle_binary_req needs an explicit loads=... (bytes -> dict of inputs). ...
```
### py2http.decorators.inject_methodized_funcs(cls=None, , funcs=(), instance_params=None, if_method_exists='raise')
* **Parameters:**
* **cls**
* **funcs**
* **instance_params**
* **if_method_exists**
* **Returns:**
# TODO: Come back to inject_methodized_funcs doctest once inject_methodized_funcs is well written
# >>> from inspect import signature
# >>>
# >>>
# >>> def f(a, b, x):
# … return x \* (a + b)
# …
# >>> def g(x, y=1):
# … return x \* y
# …
# >>>
# >>> def h(a, x, c, \*\*kwargs):
# … return f”{a}-{x}-{c}: {list(kwargs.keys())}”
# …
# >>> @inject_methodized_funcs(funcs=(f, g, h))
# … class C:
# … def \_\_init_\_(self, x, a=0, bob=True):
# … self.x = x
# … self.a = a
# … self.bob = bob
# …
# >>>
# >>>
# >>> c = C(x=10)
# >>> for m in (‘f’, ‘g’, ‘h’):
# … print(f”{C._\_name_\_}.{m}{signature(getattr(c, m))}”)
# …
# C.f(b, x)
# C.g(y, x)
# C.h(kwargs, c, x)
### py2http.decorators.methodizer(func=None, , instance_params=())
A decorator to get method versions of functions.
* **Parameters:**
* **func**
* **instance_params**
* **Returns:**
```pycon
>>> from py2http.decorators import methodizer
>>>
>>>
>>> def f(a, b, x):
... return x * (a + b)
...
>>> def g(x, y=1):
... return x * y
...
>>> methodize = methodizer(instance_params=('x', 'non_existing_attr'))
>>>
>>> class A:
... def __init__(self, x=0):
... self.x = x
...
... f = methodize(f)
... g = methodize(g)
...
>>>
>>> a = A(x=3)
>>> assert a.f(b=1, a=2) == 9
>>> assert a.g() == 3
>>> assert a.g(y=10) == 30
```
### py2http.decorators.mk_flat(cls, method, , func_name='flat_func', cls_cache_key=None)
Flatten a simple cls->instance->method call pipeline into one function.
That is, a function mk_flat(cls, method) that returns a “flat function” such that
```text
cls(**init_kwargs).method(**method_kwargs) == flat_func(**init_kwargs, **method_kwargs)
```
So, instead of this:
```graphviz
label="NESTED: result = cls(**init_kwargs).method(**method_kwargs)"
cls, init_kwargs -> instance
instance, method, method_kwargs -> result
```
you get a function `flat_func` that you can use like this:
```graphviz
label="FLAT: result = flat_func(**init_kwargs, **method_kwargs)"
flat_func, init_kwargs, method_kwargs -> result
```
* **Parameters:**
* **cls** – A class
* **method** – A method of this class
* **func_name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the function (will be “flat_func” by default)
* **cls_cache_key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The name of the kwarg used to manage cache. If not None, the
same instance of `cls` will be used for all the flattened method called with the same
value for this kwarg.
* **Returns:**
```pycon
>>> class MultiplierClass:
... def __init__(self, x):
... self.x = x
... def multiply(self, y: float = 1) -> float:
... return self.x * y
... def subtract(self, z):
... return self.x - z
...
>>> MultiplierClass(6).multiply(7)
42
>>> MultiplierClass(3.14).multiply()
3.14
>>> MultiplierClass(3).subtract(1)
2
>>> f = mk_flat(MultiplierClass, 'multiply', func_name='my_special_func')
>>> help(f)
Help on function my_special_func in module ...
my_special_func(x, y: float = 1) -> float
>>> f = mk_flat(MultiplierClass, MultiplierClass.subtract)
>>> help(f)
Help on function flat_func in in module ...
flat_func(x, z)
```
### py2http.decorators.params_replacer(replace, obj)
Generator of transformed params.
### py2http.decorators.replace_with_params(target=None, , , source=None, inplace=False)
Will return a version of the target type that has params taken from source.
Both target and source can be of the HasParams type, i.e.
```text
Union[Iterable[Parameter], Mapping[str, Parameter], Signature, Callable]
```
```pycon
>>> def f(a, /, b, *, c=None, **kwargs): ...
...
>>> def g(x, y=1, *args, **kwargs): ...
...
>>> f_sig = signature(f)
>>> f_params_map = f_sig.parameters
>>> f_params = tuple(f_params_map.values())
>>> g_sig = signature(g)
>>> g_params_map = g_sig.parameters
>>> g_params = tuple(g_params_map.values())
>>>
>>> original_f_sig = signature(f)
>>> print(original_f_sig)
(a, /, b, *, c=None, **kwargs)
>>> new_f = replace_with_params(f, source=g)
>>> print(signature(new_f))
(x, y=1, *args, **kwargs)
>>> assert signature(new_f) == signature(g)
>>> # but f remains unchanged (there is inplace=False option though!)
>>> assert signature(f) == original_f_sig
```
### py2http.decorators.unsafe_pickle_loads(data)
Unpickle `data`. UNSAFE on anything a client can send.
Unpickling runs code chosen by whoever produced the bytes, so this must only
be used when every caller of the endpoint is fully trusted (for example, a
service reachable only by your own processes). It exists so that opting into
pickled request bodies is explicit and visible at the call site:
```default
handle_binary_req(func, loads=unsafe_pickle_loads)
```
# _autosummary/py2http.default_configs.html.md
# py2http.default_configs
This module provides default configurations, input mappers, output mappers,
and error handlers for an HTTP service implemented in Python using the py2http
library. It includes functions for handling JSON requests and responses,
as well as mapping errors to appropriate HTTP responses based on different
HTTP frameworks (AIOHTTP, BOTTLE, FLASK).
The module also defines a set of default configuration values for setting up
the HTTP service, such as the application name, framework to use, port number,
error handling strategy, and CORS settings. It provides flexibility to customize
these configurations based on the specific requirements of the project.
Overall, this module serves as a foundational component for building and setting
up an HTTP service in Python using the py2http library.
### Functions
| `aiohttp_error_handler`(error) | |
|-----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `bottle_error_handler`(error) | |
| `bottle_output_mapper`(output, \*\*inputs) | |
| `default_error_handler`(error) | |
| `default_input_mapper`(\*\*inputs) | |
| [`error_status`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.error_status)(error) | The HTTP status for an error a handler raised (500 when it is not a client's). |
| [`flask_error_handler`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.flask_error_handler)(error) | The `(body, status, headers)` a Flask view returns for an error, mapped like the bottle handler (`OPAQUE_ERRORS` hides the text of a 500). |
| [`flask_json_output_mapper`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.flask_json_output_mapper)(output, \*\*inputs) | The default output mapper of a Flask app: the output as a JSON response. |
| `flask_output_mapper`(output, \*\*inputs) | |
| [`flask_response_mapper`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.flask_response_mapper)(output_mapper) | Make a Flask view's response of what an output mapper returns. |
| [`framework_defaults`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.framework_defaults)(framework, \*, ...) | The error handler and output mapper to use under `framework`: the given ones, except that the defaults (which only know of Bottle and AIOHTTP) are swapped for the framework's own, so that no process-wide state decides how a response is made. |
| [`www_authenticate_challenge`](_autosummary/py2http.default_configs.html.md#py2http.default_configs.www_authenticate_challenge)() | The `WWW-Authenticate` value of a 401 a dispatched function raised: the `PY2HTTP_WWW_AUTHENTICATE` environment variable, else `Bearer` (also when the variable holds a line break, which would make every 401 fail to send). |
### py2http.default_configs.error_status(error)
The HTTP status for an error a handler raised (500 when it is not a client’s).
```pycon
>>> error_status(AuthorizationError()), error_status(ForbiddenError())
(401, 403)
>>> error_status(InputError()), error_status(KeyError())
(400, 500)
```
* **Return type:**
[`int`](https://docs.python.org/3/builtins/functions.html#int)
### py2http.default_configs.flask_error_handler(error)
The `(body, status, headers)` a Flask view returns for an error, mapped like
the bottle handler (`OPAQUE_ERRORS` hides the text of a 500).
### py2http.default_configs.flask_json_output_mapper(output, \*\*inputs)
The default output mapper of a Flask app: the output as a JSON response.
### py2http.default_configs.flask_response_mapper(output_mapper)
Make a Flask view’s response of what an output mapper returns.
The `send_*_resp` decorators set Bottle’s `response.content_type` and return
the body (`str` or `bytes`); Flask ignores that and would answer `text/html`.
A mapper that declares a `content_type` and returns a `str`/`bytes` body, or a
`(body, status[, headers])` tuple of one, gets that content type (unless the tuple’s
headers set their own); an `async` mapper is awaited first. Anything else (a
`Response`, a dict) is kept as is.
```pycon
>>> from py2http.decorators import send_raw_resp # (needs flask)
>>> flask_response_mapper(send_raw_resp(lambda o: o))(b"x").content_type
'text/plain'
```
### py2http.default_configs.framework_defaults(framework, , error_handler, output_mapper)
The error handler and output mapper to use under `framework`: the given ones,
except that the defaults (which only know of Bottle and AIOHTTP) are swapped for
the framework’s own, so that no process-wide state decides how a response is made.
```pycon
>>> framework_defaults(FLASK, error_handler=default_error_handler,
... output_mapper=default_output_mapper)[0] is flask_error_handler
True
```
### py2http.default_configs.www_authenticate_challenge()
The `WWW-Authenticate` value of a 401 a dispatched function raised: the
`PY2HTTP_WWW_AUTHENTICATE` environment variable, else `Bearer` (also when the
variable holds a line break, which would make every 401 fail to send).
```pycon
>>> os.environ.pop(WWW_AUTHENTICATE_ENV_VAR, None) and None
>>> www_authenticate_challenge()
'Bearer'
```
* **Return type:**
[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)
# _autosummary/py2http.diagnosis.html.md
# py2http.diagnosis
This module is meant to contain diagnosis and validation tools.
### Functions
| `route_collisions`(app) | |
|---------------------------|----|
# _autosummary/py2http.flask_plugins.html.md
# py2http.flask_plugins
Flask counterparts of the Bottle plugins: auth as a `before_request` hook, CORS as an
`after_request` hook.
The credential checks are the plugins’ own (`JWTPlugin.authenticate`,
`ApiKeyAuthPlugin.authenticate`, which call `py2http.auth`), so Bottle and Flask
refuse the same requests for the same reasons. A plugin without an `authenticate`
method is a Bottle-only plugin: it is refused with `NotImplementedError` rather than
dropped, because a silently dropped auth plugin would leave its routes open.
### Functions
| [`check_flask_plugins`](_autosummary/py2http.flask_plugins.html.md#py2http.flask_plugins.check_flask_plugins)(plugins) | The `plugins` as a list, each known to work under Flask; else `NotImplementedError`. |
|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`mk_auth_hook`](_autosummary/py2http.flask_plugins.html.md#py2http.flask_plugins.mk_auth_hook)(plugins, \*, public_views[, cors]) | A `before_request` function running `plugins` (outermost first, as under Bottle). |
| [`mk_cors_hook`](_autosummary/py2http.flask_plugins.html.md#py2http.flask_plugins.mk_cors_hook)([origins]) | An `after_request` function adding the CORS headers `CorsPlugin` adds. |
### py2http.flask_plugins.check_flask_plugins(plugins)
The `plugins` as a list, each known to work under Flask; else `NotImplementedError`.
```pycon
>>> check_flask_plugins(None)
[]
>>> check_flask_plugins([object()])
Traceback (most recent call last):
...
NotImplementedError: The plugin