Features¶

• Validation of Request-like objects against Open API/Swagger schemas.

TODO¶

• Response validation.
• Query parameter validation.
• collectionformat support that ties into werkzeug’s datastructures.
• Authorization support not baked in.

Validating Incoming Requests¶

Spectastic offers two strategies for validation:

• Iterative API’s that yield individual FieldError instances.
• ValidationErrors raising methods.

Most of spectastic’s utility is contained within Operation instances. Lets make one using our test schema:

from spectastic.schema import Schema
from spectastic import Operation

schema = Spec(SPEC)
op = Operation.from_schema(schema, 'GetItem')

Once instantiated, you can validate an incoming BasicRequest:

op.validate_request(request)

If there are validation errors, we’ll raise a ValidationErrors exception, which contains an errors property consisting of a list of FieldError:

from spectastic.request import BasicRequest

request = BasicRequest(
    {"hello": "world"},
    {"Authorization": "basic beefbabaabbabeef"},
    {"query": "created:yesterday"},
    "/things/are/great",
)

try:
  op.validate_request(request)
except ValidationErrors as e:
  print e.errors[0].field

Flask Integration¶

Spectastic’s flask_utils module has some additional tools to automatically validate incoming requests for a given route against your schema:

from spectastic.contrib.flask_utils import validate_route

...

@validate_route(schema, 'GetItems')
@app.route('/items/')
def get_items(*args, **kwargs):
  return 'Success'

The validate_route() function has a few bonuses. The first argument may be a Schema instance or a callable that returns a Schema. An optional responder callable receives any ValidationErrors that may have occured and returns an appropriate flask-compatible response. You can use this to customize your error output.

The default_responder() simply outputs the general structure shown below along with a 400 status code:

{
  "errors": [
    {
      "msg": "Required path parameter is missing",
      "location": "path",
      "field": "query",
    },
    {
      ...
    }
  ]
}

Submodules¶

Errors¶

exception spectastic.errors.FieldError(msg, location, field)[source]¶

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)[source]¶

Bases: exceptions.Exception

Operation¶

exception spectastic.operation.InvalidPath[source]¶

Bases: exceptions.Exception

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

class spectastic.operation.Operation(schema, route, method, local_schema)[source]¶

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()[source]¶

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

extract_path_args(path)[source]¶

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)[source]¶

header_schema(header_name)[source]¶

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()[source]¶

Returns a list of all header parameter schemas.

iter_request_body_errors(request_body)[source]¶

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

iter_request_errors(request)[source]¶

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)[source]¶

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

iter_request_path_errors(request_path)[source]¶

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

iter_request_query_errors(query_params)[source]¶

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

path_schema(path_param_name)[source]¶

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()[source]¶

Returns a list of all path parameter schemas.

query_schema(query_param_name)[source]¶

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()[source]¶

Returns a list of all query parameter schemas.

validate_request(request)[source]¶

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)[source]¶

Validates a request body against the operation schema.

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

validate_request_headers(headers)[source]¶

Validates headers against the operation.

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

validate_request_path(path_arguments)[source]¶

Validates headers against the operation.

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

validate_request_query(query_params)[source]¶

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[source]¶

Bases: exceptions.Exception

Raised when an operation cannot be found in a schema.

spectastic.operation.coerce_param(value, schema)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Converts a flask flask.Request to a BasicRequest

Returns:	BasicRequest

spectastic.contrib.flask_utils.default_responder(validation_errors)[source]¶

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)[source]¶

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¶

Development Lead¶

• Jacob Straszynski <jacob.straszynski@planet.com>

Contributors¶

None yet. Why not be the first?