Skip to main content

This module uses python 3 type hints to validate request and response data in Flask Python APIs and generate API documentation.

Project description

Documentation Status Build Status Pypi

This module uses python types to validate request and response data in Flask Python APIs. It uses python 3 type hints to validate request paramters and generate API documentation. It also supports generic schema validation for plain dictionaries. An example of the generated API documentation can be found in the docs.

Install

doctor can easily be installed using pip:

$ pip install doctor

Quick Start

Define some types that will be used to validate your request parameters.

# mytypes.py
from doctor import types

# doctor provides helper functions to easily define simple types.
FooId = types.integer('The foo ID.')
FetchBars = types.boolean('A flag that indicates if we should fetch bars')

# You can also inherit from type classes to create more complex types.
class Foo(types.Object):
    description = 'A Foo object'
    example = {'foo_id': 1}
    properties = {'foo_id': FooId}
    required = ['foo_id']
    additional_properties = False

Define the logic function that our endpoint will route to:

# foo.py
from mytypes import Foo, FooId, FetchBars

# Note the type annotations on this function definition. This tells Doctor how
# to parse and validate parameters for routes attached to this logic function.
# The return type annotation will validate the response conforms to an
# expected definition in development environments.  In non-development
# environments a warning will be logged.
def get_foo(foo_id: FooId, fetch_bars: FetchBars=False) -> Foo:
    """Fetches the Foo object and optionally related bars."""
    return Foo.get_by_id(foo_id, fetch_bars=fetch_bars)

Now tie the endpoint to the logic function with a route:

from flask import Flask
from flask_restful import Api
from doctor.routing import create_routes, get, Route

from foo import get_foo

routes = (
    Route('/foo/<int:foo_id>/', methods=(
        get(get_foo),)
    ),
)

app = Flask(__name__)
api = Api(app)
for route, resource in create_routes(routes):
    api.add_resource(resource, route)

That’s it, you now have a functioning API endpoint you can curl and the request is automatically validated for you based on your schema. Positional arguments in your logic function are considered required request parameters and keyword arguments are considered optional. As a bonus, using the autoflask sphinx directive, you will also get automatically generated API documentation.

Generated API documentation

Documentation

Documentation and a full example is available at readthedocs.

Running Tests

Tests can be run with tox. It will handle installing dependencies into a virtualenv, running tests, and rebuilding documentation.

Then run Tox:

cd doctor
tox

You can pass arguments to pytest directly:

tox -- test/test_flask.py

Project details


Release history Release notifications

This version
History Node

3.6.0

History Node

3.5.0

History Node

3.4.0

History Node

3.3.0

History Node

3.2.0

History Node

3.1.0

History Node

3.0.1

History Node

3.0.0

History Node

3.0.0b7

History Node

3.0.0b6

History Node

3.0.0b5

History Node

3.0.0b4

History Node

3.0.0b3

History Node

3.0.0b2

History Node

3.0.0b0

History Node

1.4.0

History Node

1.3.5

History Node

1.3.4

History Node

1.3.3

History Node

1.3.2

History Node

1.3.1

History Node

1.3.0

History Node

1.2.2

History Node

1.2.1

History Node

1.2.0

History Node

1.1.4

History Node

1.1.3

History Node

1.1.2

History Node

1.1.1

History Node

1.1.0

History Node

1.0.1

History Node

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
doctor-3.6.0.tar.gz (51.3 kB) Copy SHA256 hash SHA256 Source None May 16, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page