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
-
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.
-
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.
-
-
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"]
-
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
-
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
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
-
paths
¶ return the path section of the final swagger spec, aggregated from the paths added.
-
Shape¶
-
class
transmute_core.response_shape.
ResponseShape
[source]¶ result shapes define the return format of the response.
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)
-
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.