From 938acf88bdab5812c430e82e1c75ab30c048d709 Mon Sep 17 00:00:00 2001 From: Steffen Leistner Date: Fri, 27 Sep 2019 17:37:35 +0200 Subject: [PATCH] docs: separate api and collaboration documentation --- README.md | 126 ++------------------------------------------------ docs/index.md | 118 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 121 insertions(+), 123 deletions(-) mode change 120000 => 100644 docs/index.md diff --git a/README.md b/README.md index ba603adb..b886850d 100644 --- a/README.md +++ b/README.md @@ -12,120 +12,12 @@ An opinionated Python package that facilitates specifying AWS Lambda handlers. It includes input validation, error handling and response formatting. -## Contents +## Documentation +Read more about the project motivation and API documentation at: -* [Validators](validators.md) -* [API Reference](source/modules) +- [https://lambda-handlers.readthedocs.io/en/latest/](https://lambda-handlers.readthedocs.io/en/latest/) -## Getting started - -Install `lambda-handlers` with: - -```bash -pip install lambda-handlers -``` - -If you are going to use validation, you should choose between -[Marshmallow](https://pypi.org/project/marshmallow/) or -[jsonschema](https://pypi.org/project/jsonschema/). - -To install with one of these: - -```bash -pip install 'lambda-handlers[marshmallow]' -``` - -or - -```bash -pip install 'lambda-handlers[jsonschema]' -``` - -### Quickstart - -By default the `http_handler` decorator makes sure of parsing the request body -as JSON, and also formats the response as JSON with: - - - an adequate statusCode, - - CORS headers, and - - the handler return value in the body. - -```python -from lambda_handler import http_handler - -@http_handler() -def handler(event, context): - return event['body'] -``` - -### Examples - -Skipping the CORS headers default and configuring it. - -```python -from lambda_handler import http_handler -from lambda_handlers.response import cors - -@http_handler( - cors=cors(origin='localhost', credentials=False), -) -def handler(event, context): - return event['body'] -``` - -Using jsonschema to validate a the input of a User model. - -```python -from typing import Dict, Any - -from lambda_handler import validators, http_handler - -user_schema: Dict[str, Any] = { - 'type': 'object', - 'properties': { - 'user_id': {'type': 'number'}, - }, -} - - -@http_handler( - validator=validators.jsonschema(body=user_schema), -) -def handler(event, context): - user = event['body'] - return user -``` - -Using Marshmallow to validate a User model in the input and in -the response body. - -```python -from lambda_handler import validators, http_handler -from marshmallow import Schema, fields - - -class UserSchema(Schema): - user_id = fields.Integer(required=True) - - -class ResponseSchema(Schema): - body = fields.Nested(UserSchema, required=True) - headers = fields.Dict(required=True) - statusCode = fields.Integer(required=True) - - -@http_handler( - validator=validators.marshmallow( - body=UserSchema(), - response=ResponseSchema(), - ), -) -def handler(event, context): - user = event['body'] - return user -``` - -## Using the source code +## How to collaborate This project uses [pipenv](https://pipenv.readthedocs.io) to manage its dependencies and Python environment. You can install it by: @@ -139,16 +31,6 @@ For that, we suggest using [pyenv](https://github.com/pyenv/pyenv-installer). ### Installation -For production, after you clone this repository, -you can install this project plus dependencies with: - -```bash -cd -make install -``` - -### Development - For development you should also install the development dependencies, so run instead: diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..b5b58fef --- /dev/null +++ b/docs/index.md @@ -0,0 +1,117 @@ +# lambda-handlers +An opinionated Python package that facilitates specifying AWS Lambda handlers. + +It includes input validation, error handling and response formatting. + +## Contents + +* [Validators](validators.md) +* [API Reference](source/modules) + +## Getting started + +Install `lambda-handlers` with: + +```bash +pip install lambda-handlers +``` + +If you are going to use validation, you should choose between +[Marshmallow](https://pypi.org/project/marshmallow/) or +[jsonschema](https://pypi.org/project/jsonschema/). + +To install with one of these: + +```bash +pip install 'lambda-handlers[marshmallow]' +``` + +or + +```bash +pip install 'lambda-handlers[jsonschema]' +``` + +### Quickstart + +By default the `http_handler` decorator makes sure of parsing the request body +as JSON, and also formats the response as JSON with: + + - an adequate statusCode, + - CORS headers, and + - the handler return value in the body. + +```python +from lambda_handler import http_handler + +@http_handler() +def handler(event, context): + return event['body'] +``` + +### Examples + +Skipping the CORS headers default and configuring it. + +```python +from lambda_handler import http_handler +from lambda_handlers.response import cors + +@http_handler( + cors=cors(origin='localhost', credentials=False), +) +def handler(event, context): + return event['body'] +``` + +Using jsonschema to validate a the input of a User model. + +```python +from typing import Dict, Any + +from lambda_handler import validators, http_handler + +user_schema: Dict[str, Any] = { + 'type': 'object', + 'properties': { + 'user_id': {'type': 'number'}, + }, +} + + +@http_handler( + validator=validators.jsonschema(body=user_schema), +) +def handler(event, context): + user = event['body'] + return user +``` + +Using Marshmallow to validate a User model in the input and in +the response body. + +```python +from lambda_handler import validators, http_handler +from marshmallow import Schema, fields + + +class UserSchema(Schema): + user_id = fields.Integer(required=True) + + +class ResponseSchema(Schema): + body = fields.Nested(UserSchema, required=True) + headers = fields.Dict(required=True) + statusCode = fields.Integer(required=True) + + +@http_handler( + validator=validators.marshmallow( + body=UserSchema(), + response=ResponseSchema(), + ), +) +def handler(event, context): + user = event['body'] + return user +``` \ No newline at end of file