Spectastic API

Submodules

Errors

exception spectastic.errors.FieldError(msg, location, field)

Bases: exceptions.Exception

Parameters:

• msg – The associated exception message.
• location – The location of the field e.g header, body, query.
• field – The name of the field.

VALID_LOCATIONS = ['header', 'body', 'query', 'path']

exception spectastic.errors.ValidationErrors(errors=None)

Bases: exceptions.Exception

Operation

exception spectastic.operation.InvalidPath

Bases: exceptions.Exception

Raised when a path does not match an operation’s route.

class spectastic.operation.Operation(schema, route, method, local_schema)

Bases: object

Parameters:

• schema (dict) – The overall schema for this API.
• local_schema (dict) – The schema specific to this operation.
• route (string) – The route for this operation.
• method (string) – The http method for this operation.

body_schema()

Returns a tuple of consisting of the body parameter and it’s corresponding body schema.

extract_path_args(path)

Matches a request path against this operation’s route, returning an intermediate dictionary of strings for each path parameter. The resulting dictionary is not validated nor are it’s types coerced.

Return dict:A dictionary of path arguments, with keys corresponding to the case sensitive name specified in the swagger schema.

static from_schema(schema, operation_id)

header_schema(header_name)

Returns the schema for a header parameter of a given name. The parameter name is case-insensitive.

Raises:KeyError If the header is not found.

header_schemas()

Returns a list of all header parameter schemas.

iter_request_body_errors(request_body)

Validates a request body against the schema, yielding a FieldError for each failure.

iter_request_errors(request)

Validates an entire request, yielding a FieldError for each failure.

Parameters:request (BasicRequest) – A request conforming to the structure outlined in BasicRequest

iter_request_header_errors(request_headers)

Validates individual request headers against the schema, yielding a FieldError for each failure.

iter_request_path_errors(request_path)

Validates a request path against the schema, yielding a FieldError for each failure.

iter_request_query_errors(query_params)

Validates a request query against the schema, yielding a FieldError for each failure.

path_schema(path_param_name)

Returns the schema for a path parameter of a given name. The parameter name is case-insensitive.

Raises:KeyError If the query is not found.

path_schemas()

Returns a list of all path parameter schemas.

query_schema(query_param_name)

Returns the schema for a query parameter of a given name. The parameter name is case-insensitive.

Raises:KeyError If the query is not found.

query_schemas()

Returns a list of all query parameter schemas.

validate_request(request)

Validates all components of a request.

Parameters:request – A request conforming to the structure outlined in BasicRequest Raises:ValidationErrors When validation fails. Return bool:True on success.

validate_request_body(request_body)

Validates a request body against the operation schema.

Raises:ValidationErrors When validation fails. Return bool:True on success.

validate_request_headers(headers)

Validates headers against the operation.

Raises:ValidationErrors When validation fails. Return bool:True on success.

validate_request_path(path_arguments)

Validates headers against the operation.

Raises:ValidationErrors When validation fails. Return bool:True on success.

validate_request_query(query_params)

Validates the query parameters from a request.

Parameters:query_params (dict|werkzeug.datastructures.MultiDict) – A dictionary like object of query parameters. Raises:ValidationErrors When validation fails. Return bool:True on success.

validator

exception spectastic.operation.OperationNotFound

Bases: exceptions.Exception

Raised when an operation cannot be found in a schema.

spectastic.operation.coerce_param(value, schema)

Coerces a named parameter within a path, query, or headers to the type specified in the appropriate schema. If the string is not properly formated, raise a FieldError.

Parameters:

• value (string) – The stringified value
• schema (dict) – The schema dictionary for the parameter.

Raises:

FieldError When the primitive type is not coercible.

Returns:

The value, coerced according to the parameter definition for the field named name located in location.

spectastic.operation.find_operation(schema, operation_id)

Returns a tuple of the route, method and schema for an operation.

Raises:OperationNotFound When the operation_id does not exist anywhere in the sec.

Schema

class spectastic.schema.Schema(schema_dict)

Bases: dict

Simple wrapper around Swagger / Open API schema’s. At some ‘semblance’ of type safety. Mostly used to resolve all references with the provided schema to make spectastic’s job easier.

spectastic.schema.resolve_all(schema_dict)

Recursively resolve all refs to appropriate references within the spec dictionary.

Parameters:schema_dict (dict) – A raw, json-decoded schema.

spectastic.schema.resolve_ref(schema_dict, ref)

Resolves a local ref in the form of #/definitions/dog or #/parameters/cat.

Parameters:schema_dict (dict) – A raw, json-decoded schema.

Request

class spectastic.request.BasicRequest(body, headers, query, path)

Bases: object

Demonstrates the most basic interface required by spectastic for proper request validation.

Parameters:

• headers (dict) – A dictionary-like object of headers.
• query (dict) – A dictionary-like object of query parameters.
• body (dict) – Generally a json-encoded string, or JSON decoded dictionary.
• path (string) – The request path of the request.

Flask Utilities

spectastic.contrib.flask_utils.convert_request(flask_request)

Converts a flask flask.Request to a BasicRequest

Returns:BasicRequest

spectastic.contrib.flask_utils.default_responder(validation_errors)

Generates a flask response from provided validation_errors.

Parameters:validation_errors (ValidationErrors) – A instance containing an aggregate of all errors discovered during request parsing.

spectastic.contrib.flask_utils.validate_route(schema, operation_id, responder=None)

Parameters:

• schema (Schema) – The schema to use for validation. May also be a callable that receives a flask request and returns a Schema.
• operation_id (string) – The operation id to validate. May also be a callable that receives a flask request and returns a Schema.

Module contents