API

General

class aiopenapi3.OpenAPI(url, document, session_factory=<class 'httpx.AsyncClient'>, loader=None, plugins=None, use_operation_tags=True)

property _: OperationIndex

the sad smiley interface access operations by operationId

authenticate(*args, **kwargs)

authenticate, multiple authentication schemes can be used simultaneously serving “or” or “and” authentication schemes

Parameters

• args – None to remove all credentials / reset the authorizations

• kwargs – scheme=value

static cache_load(path, plugins=None, session_factory=None)

read a pickle api object from path and init the schema types

Parameters

path (Path) – cache path

Return type

OpenAPI

cache_store(path)

write the pickled api object to Path to dismiss potentially local defined objects loader, plugins and the session_factory are dropped

Parameters

path (Path) – cache path

Return type

None

clone(baseurl=None)

shallwo copy the api object optional set a base url

Parameters

baseurl (Optional[URL]) –

Return type

OpenAPI

createRequest(operationId)

create a Request

lookup the Operation by operationId or path,method

the type of Request returned depends on the session_factory of the OpenAPI object and OpenAPI/Swagger version

Parameters

operationId (Union[str, Tuple[str, str]]) – the operationId or tuple(path,method)

Return type

RequestBase

Returns

the returned Request is either aiopenapi3.request.RequestBase or - in case of a httpx.AsyncClient session_factory - aiopenapi3.request.AsyncRequestBase

async classmethod load_async(url, session_factory=<class 'httpx.AsyncClient'>, loader=None, plugins=None, use_operation_tags=False)

Create an asynchronous OpenAPI object from a description document.

Parameters

• url (str) – the url of the description document

• session_factory (Callable[[], AsyncClient]) – used to create the session for http/s io

• loader (Optional[Loader]) – the backend to access referenced description documents

• plugins (Optional[List[Plugin]]) – potions to cure defects in the description document or requests/responses

• use_operation_tags (bool) – honor tags

Return type

OpenAPI

classmethod load_file(url, path, session_factory=<class 'httpx.AsyncClient'>, loader=None, plugins=None, use_operation_tags=False)

Create an OpenAPI object from a description document file.

Parameters

• url (str) – the fictive url of the description document

• path (Union[str, Path, URL]) – description document location

• session_factory (Callable[[], Union[AsyncClient, Client]]) – used to create the session for http/s io, defaults to use an AsyncClient

• loader (Optional[Loader]) – the backend to access referenced description documents

• plugins (Optional[List[Plugin]]) – potions to cure defects in the description document or requests/responses

• use_operation_tags (bool) – honor tags

Return type

OpenAPI

classmethod load_sync(url, session_factory=<class 'httpx.Client'>, loader=None, plugins=None, use_operation_tags=False)

Create a synchronous OpenAPI object from a description document.

Parameters

• url – the url of the description document

• session_factory (Callable[[], Client]) – used to create the session for http/s io

• loader – the backend to access referenced description documents

• plugins (Optional[List[Plugin]]) – potions to cure defects in the description document or requests/responses

• use_operation_tags (bool) – honor tags

Return type

OpenAPI

classmethod loads(url, data, session_factory=<class 'httpx.AsyncClient'>, loader=None, plugins=None, use_operation_tags=False)

Parameters

• url (str) – the url of the description document

• data (str) – description document

• session_factory (Callable[[], Union[AsyncClient, Client]]) – used to create the session for http/s io, defaults to use an AsyncClient

• loader – the backend to access referenced description documents

• plugins (Optional[List[Plugin]]) – potions to cure defects in the description document or requests/responses

• use_operation_tags (bool) – honor tags

Return type

OpenAPI

Requests

Requests encapsulate the required information to call an operation, they compile the actual HTTP request sent, including authentication information, headers, parameters and the body.

class aiopenapi3.request.RequestBase(api, method, path, operation)

__call__(*args, return_headers=False, **kwargs)

Parameters

• args –

• return_headers (bool) – if set return a tuple (header, body)

• kwargs –

Return type

Union[Any, Tuple[Dict[str, str], Any]]

Returns

body or (header, body)

abstract property data: SchemaBase

Returns

the Schema for the body

abstract property parameters: List[ParameterBase]

Returns

list of parameters

request(data=None, parameters=None)

Sends an HTTP request as described by this Path

Parameters

• data (any, should match content/type) – The request body to send.

• parameters (dict{str: str}) – The parameters used to create the path

Return type

Tuple[Dict[str, Any], Any, Response]

Returns

headers, data, response

class aiopenapi3.v20.glue.Request(api, method, path, operation)

class aiopenapi3.v20.glue.AsyncRequest(api, method, path, operation)

class aiopenapi3.v30.glue.Request(api, method, path, operation)

This class is returned by instances of the OpenAPI class when members formatted like call_operationId are accessed, and a valid Operation is found, and allows calling the operation directly from the OpenAPI object with the configured values included. This class is not intended to be used directly.

class aiopenapi3.v30.glue.AsyncRequest(api, method, path, operation)

Parameters

Parameters are part of the operation specification and can be in

• path e.g. /users/{name}

• query e.g. /users?limit=50

• header

class aiopenapi3.v20.parameter.Parameter(**data)

Describes a single operation parameter.

class aiopenapi3.v30.parameter.Parameter(**data)

Parameter Encoding

Each of those Parameters has a different encoding strategy for different argument types. e.g. encoding a List[str] as query parameter or object in a header. Additionally Swagger 2.0 has a different encoding strategy to OpenAPI 3.x.

class aiopenapi3.v20.parameter._ParameterCodec

SEPERATOR_VALUES = {'csv': ',', 'pipes': '|', 'ssv': ' ', 'tsv': '\t'}

Describing Parameters

https://swagger.io/docs/specification/2-0/describing-parameters/

class aiopenapi3.v30.parameter._ParameterCodec

Plugin Interface

Init Plugins

Init plugins are used to signal the setup is done.

class Init.Context(initialized)

class aiopenapi3.plugin.Init

Document Plugins

Document plugins are used to mangle description documents.

class Document.Context(url, document)

class aiopenapi3.plugin.Document

loaded(ctx)

modify the text before parsing

Return type

Context

parsed(ctx)

modify the parsed dict before …

Return type

Context

Message Plugins

Message plugins are used to mangle message.

class Message.Context(operationId, marshalled=None, sending=None, received=None, headers=None, status_code=None, content_type=None, parsed=None, unmarshalled=None, expected_type=None)

class aiopenapi3.plugin.Message

marshalled(ctx)

modify the dict before sending

Return type

Context

parsed(ctx)

modify the parsed dict structure

Return type

Context

received(ctx)

modify the received text

Return type

Context

sending(ctx)

modify the text before sending

Return type

Context

unmarshalled(ctx)

modify the object

Return type

Context

Loader

The loader is used to access description documents. aiopenapi3.loader.Loader is the base class, providing flexibility to load description documents.

loading operation

The order of operation for the loader is:

• aiopenapi3.loader.Loader.get()

  • aiopenapi3.loader.Loader.load()

    • aiopenapi3.loader.Loader.decode()

      • aiopenapi3.plugin.Document.loaded()

  • aiopenapi3.loader.Loader.parse()

    • yaml?

      • yaml.load(yload)

    • json?

      • json.loads

  • aiopenapi3.plugin.Document.parsed()

Loaders

class aiopenapi3.loader.Loader(yload=<class 'yaml.loader.SafeLoader'>)

Loaders are used to ‘get’ description documents:

• load

• decode

• parse

classmethod decode(data, codec)

decode bytes to ascii or utf-8

Parameters

• data (bytes) –

• codec (str) –

Returns

get(plugins, url)

load & parse the description document :type plugins: Plugins :param plugins: collection of aiopenapi3.plugin.Document plugins :type url: URL :param url: location of the description document :return:

abstract load(plugins, url, codec=None)

load and decode description document

Parameters

• plugins (Plugins) – collection of aiopenapi3.plugin.Document plugins

• url (URL) – location of the description document

• codec (Optional[str]) –

Returns

decoded data

parse(plugins, url, data)

parse the downloaded document as json or yaml

Parameters

• plugins (Plugins) – collection of aiopenapi3.plugin.Document plugins

• url (URL) – location of the description document

• data (str) – decoded data of the description document

Returns

class aiopenapi3.loader.FileSystemLoader(base, yload=<class 'yaml.loader.SafeLoader'>)

Loader to use the local filesystem

class aiopenapi3.loader.WebLoader(baseurl, session_factory=<class 'httpx.Client'>, yload=<class 'yaml.loader.SafeLoader'>)

Loader downloads data via http/s using the supplied session_factory

class aiopenapi3.loader.ChainLoader(*loaders, yload=<class 'yaml.loader.SafeLoader'>)

Loader to chain different Loaders: succeed or raise trying

The ChainLoader is useful when using multiple locations with description documents.

ChainLoader(RedirectLoader("description_documents/dell"), RedirectLoader("description_documents/supermicro"))

class aiopenapi3.loader.RedirectLoader(base, yload=<class 'yaml.loader.SafeLoader'>)

Loader to redirect web-requests to a local directory everything but the “name” is stripped of the url

The RedirectLoader allows redirecting to local resources. A description documents URI is stripped to the file name of the document, and loaded relative to the basedir of the RedirectLoader.

RedirectLoader("description_documents/dell")

YAML type coercion

Changing a Loaders YAML Loader may be required to parse description documents with improper tags, e.g. values getting decoded as dates in a text. The aiopenapi3.loader.YAMLCompatibilityLoader provided removes decoding of

• timestamp

• value

• int

• book

and can be passed to a aiopenapi3.loader.Loader as yload argument.

Exceptions

Description Document Validation

class aiopenapi3.errors.SpecError(message, element=None)

This error class is used when an invalid format is found while parsing an object in the spec.

class aiopenapi3.errors.ReferenceResolutionError(message, element=None)

This error class is used when resolving a reference fails, usually because of a malformed path in the reference.

class aiopenapi3.errors.ParameterFormatError

The specified parameter encoding is invalid for the parameter family

Message

exception aiopenapi3.errors.HTTPError

HTTPError is the base class for all request/response related errors.

exception aiopenapi3.errors.RequestError(operation, request, data, parameters)

data: object

operation: object

parameters: object

request: object

A RequestError typically wraps an error of the underlying httpx library.

exception aiopenapi3.errors.ResponseError

the response can not be processed accordingly

ReponseErrors indicate the response does not match the expectation/definition in the description document. Most ReponseErrors can be mitigated around using plugins to match the protocol to the description document.

exception aiopenapi3.errors.ContentTypeError(operation, content_type, message, response)

The content-type is unexpected

content_type: str

message: str

operation: object

response: object

exception aiopenapi3.errors.HTTPStatusError(operation, http_status, message, response)

The HTTP Status is unexpected

http_status: int

message: str

operation: object

response: object

exception aiopenapi3.errors.ResponseDecodingError(operation, data, response)

the json decoder failed

data: object

operation: object

response: object

exception aiopenapi3.errors.ResponseSchemaError(operation, expectation, schema, response, exception)

the response data does not match the schema

exception: object

expectation: object

operation: object

response: object

schema: object