py2http 0.1.59__tar.gz → 0.1.61__tar.gz

py2http-0.1.61/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: py2http
+Version: 0.1.61
+Summary: Declarative HTTP service entry point.
+Home-page: https://github.com/i2mint/py2http
+License: MIT
+Keywords: http service,web service
+Platform: any
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bottle
+Requires-Dist: PyJWT[crypto]
+Requires-Dist: aiohttp
+Requires-Dist: i2
+Requires-Dist: glom
+Requires-Dist: gunicorn
+Requires-Dist: requests
+Requires-Dist: strand
+Requires-Dist: swagger-ui-py
+Requires-Dist: pycparser
+Requires-Dist: http2py
+Provides-Extra: testing
+Requires-Dist: http2py; extra == "testing"
+Dynamic: license-file
+
+[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}</{tag}>' 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.,

{py2http-0.1.59 → py2http-0.1.61}/README.md

@@ -10,7 +10,8 @@ You have some python objects and want to get an "equivalent" http service from t
 ## Usage
 
 Run a basic HTTP service from a list of functions.
-```
+
+```python
 from py2http.service import run_app
 
 # Define or import functions
@@ -22,7 +23,7 @@ def multiply(a, b):
 
 class Divider:
     def __init__(self, dividend):
-        self.dividend = divident
+        self.dividend = dividend
     
     def divide(self, divisor):
         return self.dividend / divisor
@@ -33,10 +34,17 @@ divider_from_ten = Divider(10)
 func_list = [add, multiply, divider_from_ten.divide]
 
 # Create an HTTP server
-run_app(func_list)
+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
 
@@ -54,7 +62,7 @@ requests.post(url, json=add_args).json()
 
 Expose class methods by flattening the init -> method call process.
 
-```
+```python
 from py2http import run_app
 from py2http.decorators import mk_flat
 
@@ -76,7 +84,7 @@ run_app(func_list)
 
 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
@@ -120,7 +128,7 @@ get_user_data.input_mapper = custom_header_input_mapper
 
 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
 
@@ -174,7 +182,8 @@ 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
 

py2http-0.1.61/py2http/__init__.py

@@ -0,0 +1,25 @@
+"""This module provides functionality to easily create HTTP services from Python
+functions and class methods. It includes features such as method transformation,
+input mapping, output mapping, error handling, and client generation.
+The module also allows for customization through various configuration options
+and provides the ability to generate OpenAPI specifications for the created HTTP
+services. Additionally, it includes middleware, plugins, and decorators to enhance
+the functionality of the HTTP services."""
+
+from .middleware import mk_jwt_middleware, mk_superadmin_middleware
+from .bottle_plugins import JWTPlugin, ApiKeyAuthPlugin
+from .service import (
+    mk_app,
+    run_app,
+)
+from .decorators import (
+    Decorator,
+    DecoParam,
+    Decora,
+    replace_with_params,
+    ch_func_to_all_pk,
+    mk_flat,
+    mk_handlers,
+    add_attrs,
+)
+from .openapi_utils import func_to_openapi_spec

{py2http-0.1.59 → py2http-0.1.61}/py2http/bottle_plugins.py

@@ -1,5 +1,4 @@
-"""Plugins for adding middleware functionality to Bottle apps.
-"""
+"""Plugins for adding middleware functionality to Bottle apps."""
 
 from bottle import request, response, abort
 from functools import wraps
@@ -9,7 +8,7 @@ from typing import Iterable
 from warnings import warn
 from py2http.constants import JSON_CONTENT_TYPE
 
-OPTIONS = 'OPTIONS'
+OPTIONS = "OPTIONS"
 
 
 class JWTPlugin:
@@ -21,7 +20,7 @@ class JWTPlugin:
 
     def __init__(
         self,
-        secret: str = '',
+        secret: str = "",
         verify: bool = True,
         mapper: dict = None,
         ignore_methods: Iterable[str] = None,
@@ -39,7 +38,7 @@ class JWTPlugin:
         self._verify = verify
         self._mapper = mapper if mapper else {}
         self._ignore_methods = ignore_methods if ignore_methods else []
-        self._algorithms = algorithms if algorithms else ['HS256']
+        self._algorithms = algorithms if algorithms else ["HS256"]
 
     def __call__(self, handler):
         if self._ignore_methods and handler.method_name in self._ignore_methods:
@@ -49,13 +48,13 @@ class JWTPlugin:
         def wrapped_handler(*args, **kwargs):
             if request.method == OPTIONS:
                 return handler(*args, *kwargs)
-            auth_header = request.headers.get('Authorization', '')
+            auth_header = request.headers.get("Authorization", "")
             token = auth_header[7:]
             try:
                 decoded = jwt.decode(
                     token,
                     self._secret,
-                    options={'verify_signature': self._verify},
+                    options={"verify_signature": self._verify},
                     algorithms=self._algorithms,
                 )
                 for k, v in self._mapper.items():
@@ -69,10 +68,10 @@ class JWTPlugin:
                     response.content_type = JSON_CONTENT_TYPE
                     return json.dumps(
                         {
-                            'error': f'Invalid authentication token "{token}", {str(error)}'
+                            "error": f'Invalid authentication token "{token}", {str(error)}'
                         }
                     )
-                warn(f'Invalid JWT: {token}')
+                warn(f"Invalid JWT: {token}")
                 return handler(*args, **kwargs)
 
         return wrapped_handler
@@ -84,12 +83,12 @@ class ApiKeyAuthPlugin:
 
     def __call__(self, handler):
         def wrapped_handler(*args, **kwargs):
-            auth_header = request.headers.get('Authorization', '')
+            auth_header = request.headers.get("Authorization", "")
             if auth_header == self._api_key:
                 return handler(*args, **kwargs)
             response.status = 401
             response.content_type = JSON_CONTENT_TYPE
-            return json.dumps({'error': 'invalid API key'})
+            return json.dumps({"error": "invalid API key"})
 
         return wrapped_handler
 
@@ -97,18 +96,18 @@ class ApiKeyAuthPlugin:
 # from https://stackoverflow.com/questions/17262170/bottle-py-enabling-cors-for-jquery-ajax-requests
 # TODO: accept lists of headers and methods as init args
 class CorsPlugin:
-    def __init__(self, origins: str = '*'):
+    def __init__(self, origins: str = "*"):
         self._origins = origins
 
     def __call__(self, handler):
         def wrapped_handler(*args, **kwargs):
-            response.headers['Access-Control-Allow-Origin'] = self._origins
-            response.headers[
-                'Access-Control-Allow-Methods'
-            ] = 'GET, POST, PUT, DELETE, OPTIONS'
-            response.headers[
-                'Access-Control-Allow-Headers'
-            ] = 'Origin, Accept, Content-Type, X-Requested-With, Authorization, X-api-key'
+            response.headers["Access-Control-Allow-Origin"] = self._origins
+            response.headers["Access-Control-Allow-Methods"] = (
+                "GET, POST, PUT, DELETE, OPTIONS"
+            )
+            response.headers["Access-Control-Allow-Headers"] = (
+                "Origin, Accept, Content-Type, X-Requested-With, Authorization, X-api-key"
+            )
             if request.method != OPTIONS:
                 return handler(*args, **kwargs)
 

{py2http-0.1.59 → py2http-0.1.61}/py2http/config.py

@@ -1,12 +1,27 @@
+"""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.
+"""
+
 from typing import Callable
 
-AIOHTTP = 'aiohttp'
-BOTTLE = 'bottle'
-FLASK = 'flask'
+AIOHTTP = "aiohttp"
+BOTTLE = "bottle"
+FLASK = "flask"
 
 
 def get_result(configs, func, funcname, key, options):
-    """ this is meant to allow nested configs by function name
+    """this is meant to allow nested configs by function name
     example:
 
     # TODO: See mk_config use and make an actual doctest for get_result
@@ -27,9 +42,9 @@ def get_result(configs, func, funcname, key, options):
         dict_value = result.get(funcname, None)
         if dict_value:
             result = dict_value
-        elif '$else' in result:
-            result = result['$else']
-        elif options.get('type', None) is not dict:
+        elif "$else" in result:
+            result = result["$else"]
+        elif options.get("type", None) is not dict:
             result = None
     return result
 
@@ -52,12 +67,12 @@ def mk_config(key, func, configs, defaults, **options):
         * *type*
           The expected type of the output (use Callable for functions)
     """
-    funcname = options.get('funcname', getattr(func, '__name__', None))
+    funcname = options.get("funcname", getattr(func, "__name__", None))
 
     result = get_result(configs, func, funcname, key, options)
 
     if result:
-        expected_type = options.get('type', None)  # align names expected_type <-> type
+        expected_type = options.get("type", None)  # align names expected_type <-> type
         if not expected_type:
             assert key in defaults, f'Missing default value for key "{key}"'
             default_value = defaults.get(key)
@@ -67,7 +82,7 @@ def mk_config(key, func, configs, defaults, **options):
                 expected_type = type(default_value)
         assert expected_type == type(None) or isinstance(
             result, expected_type
-        ), f'Config {key} does not match type {expected_type}.'
+        ), f"Config {key} does not match type {expected_type}."
     else:
         result = defaults.get(key, None)
     return result

py2http-0.1.61/py2http/constants.py

@@ -0,0 +1,7 @@
+"""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."""
+
+JSON_CONTENT_TYPE = "application/json"
+BINARY_CONTENT_TYPE = "application/octet-stream"
+FORM_CONTENT_TYPE = "multipart/form-data"
+RAW_CONTENT_TYPE = "text/plain"
+HTML_CONTENT_TYPE = "text/html"