Create API specifications and documentation using Python
Project description
Pactum
The HTTP-API specification sketchbook for pythonistas
pip install pactum
With Pactum
you can specify HTTP-APIs using pure python.
Pactum is easy to use, easy to extend and easy to contribute:
Easy to use
The only requirements to start writing an API specification with pactum
is pactum
package itself and some knowledge of python.
import pactum
class MyAPI(pactum.API):
name = 'My API'
versions = [...]
Easy to extend
Using the visitor pattern you can create exporters and extensions for any format or service you want.
Take a look at pactum/exporters/openapi.py.
Architecture
Always keep this diagram in mind when defining your APIs.
Tutorial
Create a file called specs.py and start defining your API.
You can define a Resource
object for your API.
from pactum import Action, API, Resource, Response, Version
from pactum import fields, verbs
class Order(Resource):
fields = [
fields.IntegerField(name='code', required=True),
fields.TimestampField(name='created_at'),
fields.StringField(name='item')
]
resource = Order()
error_resource = Resource(
name = 'ErrorResource'
fields = [fields.StringField(name='error', required=False)]
)
You can define any element of your specification by calling it directly as in
error_resource
or by class definition as in MyResource
and then calling it.
List resources are definitions of lists of the same resource.
list_order_resource = ListResource(resource=resource)
You can define Response
objects with status
, description
(optional) a
header
(optional) and a Resource
/ListResource
object as body
(optionally)...
list_response = Response(
status=200, description='Here is your orders list.', body=list_resource
)
detail_response = Response(
status=200, description='Here is your order.', body=resource
)
error_response = Response(status=404, resource=error_resource, headers=[('Content-type': 'application-json')])
... and Request
objects with verb
, description
, header
(optional) and a Resource
/ListResource
object as payload
.
get_request = Request(verb=verbs.GET)
An Action
groups your request and a list of responses for a specified action passed in the description parameter.
list_action = Action(
description='Returns a list of resources.',
request=get_request,
responses=[error_response, list_response]
)
detail_action = Action(
description='Returns a resource based on its code.',
request=get_request,
responses=[error_response, detail_response]
)
The Action object, as all other elements in Pactum, receive a description string
that sets the .__doc__
attribute and can be the docstring of the class
if the object is defined by class definition.
A route can have a list of actions in an HTTP path.
class OrderListRoute(Route):
path = '/orders'
actions = [list_action]
list_route = OrderListRoute()
detail_route = OrderRoute(path='/orders/{code}', actions=detail_action)
Your routes can be grouped in API versions.
class V1(Version):
name = 'V1'
routes = [list_route, detail_route]
v1 = V1()
Then you can define your API. ;)
class OrdersAPI(API):
name = 'Orders API'
versions = [v1]
api = OrdersAPI()
Be happy and ready to export your specification to any format you want.
Exporting to openapi specs.
Pactum has a command that exports your specification to OpenAPI. You can call it by using:
pactum-openapi <spec_file.py> <output_file> [--format=<json or yaml>]
Road to version 1.
- Test elements .accept(visitor) methods.
- Support for version selectors (Versions should be specified on HTTP header, path, or custom fields)
- Stabilize the way we work with path parameters.
- Support for Authorization and Authentication Specifications.
- Support for extensions.
- Behaviors
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file pactum-0.2.0.tar.gz
.
File metadata
- Download URL: pactum-0.2.0.tar.gz
- Upload date:
- Size: 16.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.7.1
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ff930010fe6abca237ec924297f28a719564e6356c2d6f0b882bb44b5917e89e |
|
MD5 | 8dd09ed0845b0686ae8da6393cb91f3b |
|
BLAKE2b-256 | ef861f21a7429b40ac83e6c32980cdb406ea2a27f185a7d314084cf93d70bb24 |