API Reference

TransmuteContext

class transmute_core.context.TransmuteContext(serializers=None, contenttype_serializers=None, response_shape=None)[source]

TransmuteContext contains all of the configuration points for a framework based off of transmute.

It is useful for customizing default behaviour in Transmute, such as serialization of additional content types, or using different serializers for objects to and from basic data times.

Decorators

transmute_core.decorators.annotate(annotations)[source]

in python2, native annotions on parameters do not exist:

def foo(a : str, b: int) -> bool:
    ...

this provides a way to provide attribute annotations:

@annotate({"a": str, "b": int, "return": bool})
def foo(a, b):
    ...
transmute_core.decorators.describe(**kwargs)[source]

describe is a decorator to customize the rest API that transmute generates, such as choosing certain arguments to be query parameters or body parameters, or a different method.

Parameters:
  • paths (list(str)) – the path(s) for the handler to represent (using swagger’s syntax for a path)
  • methods (list(str)) – the methods this function should respond to. if non is set, transmute defaults to a GET.
  • query_parameters (list(str)) – the names of arguments that should be query parameters. By default, all arguments are query_or path parameters for a GET request.
  • body_parameters (List[str] or str) –

    the names of arguments that should be body parameters. By default, all arguments are either body or path parameters for a non-GET request.

    in the case of a single string, the whole body is validated against a single object.

  • header_parameters (list(str)) – the arguments that should be passed into the header.
  • path_parameters (list(str)) – the arguments that are specified by the path. By default, arguments that are found in the path are used first before the query_parameters and body_parameters.

Object Serialization

class transmute_core.object_serializers.ObjectSerializer[source]

The object serializer is responsible for converting objects to and from basic data types. Basic data types are serializable to and from most common data representation languages (such as yaml or json)

Basic data types are:

  • str (basestring in Python2, str in Python3)
  • float
  • int
  • None
  • dict
  • list

The serializer decides what it can and can not serialize, and should raise an exception when a type it can not serialize is passed.

SchematicsSerializer is the default implementation used.

dump(model, value)[source]

dump the value from a class to a basic datatype.

if the model or value is not valid, raise a SerializationException

load(model, value)[source]

load the value from a basic datatype, into a class.

if the model or value is not valid, raise a SerializationException

to_json_schema(model)[source]

return a dictionary representing a jsonschema for the model.

class transmute_core.object_serializers.SchematicsSerializer(builtin_models=None)[source]

An ObjectSerializer which allows the serialization of basic types and schematics models.

The valid types that SchematicsSerializer supports are:

  • int
  • float
  • bool
  • decimal
  • string
  • none
  • lists, in the form of [Type] (e.g. [str])
  • any type that extends the schematics.models.Model.

ContentType Serialization

class transmute_core.contenttype_serializers.ContentTypeSerializer[source]

A ContentTypeSerializer handles the conversion from a python data structure to a bytes object representing the content in a particular content type.

can_handle(content_type_name)[source]

given a content type, returns true if this serializer can convert bodies of the given type.

content_type()[source]

return back what a list of content types this serializer should support.

dump(data)[source]

should return back a bytes (or string in python 2), representation of your object, to be used in e.g. response bodies.

a ValueError should be returned in the case where the object cannote be serialized.

load(raw_bytes)[source]

given a bytes object, should return a base python data structure that represents the object.

a ValueError should be returned in the case where the object cannot be serialized.

main_type()[source]

return back a single content type that represents this serializer.

class transmute_core.contenttype_serializers.SerializerSet(serializer_list)[source]

composes multiple serializers, delegating commands to one that can handle the desired content type.

SerializerSet implements a dict-like interface. Retrieving serializers is done by get the content type item:

serializers["application/json"]
keys()[source]

return a list of the content types this set supports.

this is not a complete list: serializers can accept more than one content type. However, it is a good representation of the class of content types supported.

class transmute_core.contenttype_serializers.JsonSerializer[source]
static can_handle(content_type_name)[source]

given a content type, returns true if this serializer can convert bodies of the given type.

static dump(data)[source]

should return back a bytes (or string in python 2), representation of your object, to be used in e.g. response bodies.

static load(raw_bytes)[source]

given a bytes object, should return a base python data structure that represents the object.

class transmute_core.contenttype_serializers.YamlSerializer[source]
static can_handle(content_type_name)[source]

given a content type, returns true if this serializer can convert bodies of the given type.

static dump(data)[source]

should return back a bytes (or string in python 2), representation of your object, to be used in e.g. response bodies.

static load(raw_bytes)[source]

given a bytes object, should return a base python data structure that represents the object.

Swagger

class transmute_core.swagger.SwaggerSpec[source]

a class for aggregating and outputting swagger definitions, from transmute primitives

add_func(transmute_func, transmute_context)[source]

add a transmute function’s swagger definition to the spec

add_path(path, path_item)[source]

for a given path, add the path items.

paths

return the path section of the final swagger spec, aggregated from the paths added.

swagger_definition(title='example', version='1.0', base_path=None)[source]

return a valid swagger spec, with the values passed.

transmute_core.swagger.generate_swagger_html(swagger_static_root, swagger_json_url)[source]

given a root directory for the swagger statics, and a swagger json path, return back a swagger html designed to use those values.

transmute_core.swagger.get_swagger_static_root()[source]

transmute-core includes the statics to render a swagger page. Use this function to return the directory containing said statics.

Shape

class transmute_core.response_shape.ResponseShape[source]

result shapes define the return format of the response.

static create_body(result_dict)[source]

given the result dict from transmute_func, return back the response object.

static swagger(result_schema)[source]

given the schema of the inner result object, return back the swagger schema representation.

class transmute_core.response_shape.ResponseShapeComplex[source]

return back an object with the result nested, providing a little more context on the result:

  • status code
  • success
  • result
class transmute_core.response_shape.ResponseShapeSimple[source]

return back just the result object.

TransmuteFunction

Warning

transmute framework authors should not need to use attributes in TransmuteFunction directly. see Creating a framework-specific library

class transmute_core.function.transmute_function.TransmuteFunction(func, args_not_from_request=None)[source]

TransmuteFunctions wrap a function and add metadata, allowing transmute frameworks to extract that information for their own use (such as web handler generation or automatic documentation)

get_response_by_code(code)[source]

return the return type, by code

get_swagger_operation(context=<transmute_core.context.TransmuteContext object>)[source]

get the swagger_schema operation representation.

process_result(context, result_body, exc, content_type)[source]

given an result body and an exception object, return the appropriate result object, or raise an exception.

transmute_core.function.parameters.get_parameters(signature, transmute_attrs, arguments_to_ignore=None)[source]

given a function, categorize which arguments should be passed by what types of parameters. The choices are:

  • query parameters: passed in as query parameters in the url
  • body parameters: retrieved from the request body (includes forms)
  • header parameters: retrieved from the request header
  • path parameters: retrieved from the uri path

The categorization is performed for an argument “arg” by:

1. examining the transmute parameters attached to the function (e.g. func.transmute_query_parameters), and checking if “arg” is mentioned. If so, it is added to the category.

2. If the argument is available in the path, it will be added as a path parameter.

3. If the method of the function is GET and only GET, then “arg” will be be added to the expected query parameters. Otherwise, “arg” will be added as a body parameter.