Reference¶

APIs¶

class cosmic.api.API(name, homepage=None)¶

An instance of this class represents a Cosmic API, whether it’s your own API being served or a third-party API being consumed. In the former case, the API object is instantiated by the constructor and is bound to a database ORM and other user-defined functions. In the latter case, it is instantiated by the API.load() method and these functions are replaced by automatically generated HTTP calls.

One of the primary goals of Cosmic is to make local and remote APIs behave as similarly as possible.

Parameters:	name – The API name is required, and should be unique homepage – If you like, the API spec may include a link to your homepage

actions = None¶

In the cosmic.api.API object, the actions are stored in an OrderedDict in a private _actions property:

>>> mathy._actions
OrderedDict([(u'add', <cosmic.actions.Action object at 0x9ca18ec>)])

The standard way of accessing them, however, is through a proxy property actions. Like so:

>>> mathy.actions.add(1, 2)
3

models = None¶

Models are stored in the _models property, but accessed through a proxy like so:

>>> mathy.models.Number
<class '__main__.Number'>

run(port=5000, **kwargs)¶: Simple way to run the API in development. Uses Werkzeug’s werkzeug.serving.run_simple() internally. See Serving for more options.

static load(url, verify=True)¶

Given a URL to a Cosmic API, fetch the API spec and build an API client:

>>> planetarium = API.load("http://localhost:5000/spec.json") 
>>> planetarium.models.Sphere.get_by_id("0") 
{"name": "Earth"}

Parameters:	url – The API spec url, including `/spec.json`
Return type:	`API` instance

action(accepts=None, returns=None)¶

A decorator for creating actions out of functions and registering them with the API.

The accepts parameter is a schema that describes the input of the function, returns is a schema that describes the output of the function. The name of the function becomes the name of the action and the docstring serves as the action’s documentation.

Once registered, an action will become accessible as an attribute of the actions object.

>>> random = API("random")
>>> @random.action(returns=Integer)
... def generate():
...     "Random enough"
...     return 9
>>> random.actions.generate()
9

model(model_cls)¶

A decorator for registering a model with an API. The name of the model class is used as the name of the resulting model.

>>> dictionary = API("dictionary")
>>> @dictionary.model
... class Word(BaseModel):
...    properties = [
...        required("text", String)
...    ]
...

Once registered, a model will become accessible as an attribute of the models object.

Models¶

class cosmic.models.BaseModel¶

Subclasses of this class are fed into the model() decorator to attach models to an API.

properties = []¶

A list of properties which, along with links below, will be used for the model’s representation and patch, defined in the same way Teleport Struct fields are defined:

properties = [
    required('name', String),
    optional('age', Integer),
]

See Representation and Patch.

methods = []¶: A list of methods that this model supports. Possible values are ‘get_by_id’, ‘create’, ‘update’, ‘delete’ and ‘get_list’.

query_fields = []¶: A list of properties for the get_list() handler. They are defined in the same way as properties above.

list_metadata = []¶: A list of properties that can be returned along with the usual response for get_list(). These can be used for things like pagination.

links = []¶: Similar to properties, but encodes a relationship between this model and another. In database terms this would be a foreign key. Use required_link() and optional_link() to specify them.

classmethod validate_patch(patch)¶

Raises cosmic.exceptions.ValidationError:
Parameters:	patch – The model patch

Run before any create() or update() call to validate the patch. All fields are made optional for the patch, so this method is a chance to ensure that the expected values were indeed passed in.

classmethod get_by_id(id)¶

Raises cosmic.exceptions.NotFound:
Parameters:	id –
Returns:	Model representation

classmethod get_list(**kwargs)¶

Parameters:	kwargs – Defined by `query_fields`
Returns:	If model does not define `list_metadata`, returns a list of tuples of models ids and representations. Otherwise returns a tuple where the first element is the above list, and the second is a dict as specified by `list_metadata`.

classmethod create(**validated_patch)¶

Parameters:	validated_patch – The model patch.
Returns:	A tuple of model id and model representation.

classmethod update(id, **validated_patch)¶

Raises cosmic.exceptions.NotFound:
Parameters:	id – validated_patch –
Returns:	The model representation after patch has been applied.

classmethod delete(id)¶

Raises cosmic.exceptions.NotFound:
Parameters:	id –

class cosmic.models.M(model_name)¶

Creates a lazy reference to a model, useful for defining links.

@familytree.model
class Person(BaseModel):
    links = [
        optional_link('mother', M('familytree.Person')),
        optional_link('father', M('familytree.Person')),
    ]

Types¶

class cosmic.types.Model¶

Bases: teleport.BasicWrapper

A Teleport type representing an API model. Its JSON form is a dotted string, the native form is the model object:

>>> Model.to_json(places.models.City)
"places.City"

Note that when deserializing this type, the returned value isn’t exactly a model object, but a M object, a proxy that behaves identically to the model. The reason for this is that sometimes a reference to the model is needed before the model exists, for example, when defining links.

class cosmic.types.Link(param)¶

Bases: teleport.ParametrizedWrapper

A Teleport type representing a link to an object. Its native form is simply a resource id. It takes a Model as parameter:

>>> Link(places.models.City).to_json("3")
{"href": "/City/3"}
>>> Link(places.models.City).from_json({"href": "/City/3"})
"3"

class cosmic.types.Representation(param)¶

Bases: cosmic.types.BaseRepresentation

A Teleport type representing a model representation. Its native form is a dict as defined by properties and links. Links are represented by plain string ids.

It takes a Model as parameter.

class cosmic.types.Patch(param)¶

Bases: cosmic.types.BaseRepresentation

A Teleport type representing a model patch. Its native form is similar to that of Representation, except all fields are optional. To make a field required, use validate_patch().

It takes a Model as parameter.

class cosmic.types.URLParams(param)¶

Bases: teleport.ParametrizedWrapper

A Teleport type that behaves mostly like the Struct type, except it serializes the data into a query string:

>>> p = URLParams([
...     required("foo", Boolean),
...     required("bar", Integer)
... ])
...
>>> p.to_json({"foo": True, "bar": 3})
'foo=true&bar=3'
>>> p.from_json("foo=false&bar=0")
{'foo': False, 'bar': 0}

A string parameter or a parameter whose type is a wrapper over string will not require quotes:

>>> from cosmic.types import DateTime
>>> schema = URLParams([
...     required('birthday', DateTime)
... ])
>>> schema.from_json('birthday=1991-08-12T00%3A00%3A00')
{'birthday': datetime.datetime(1991, 8, 12, 0, 0)}

HTTP Endpoints¶

class cosmic.http.ActionEndpoint(action)¶

Request:

Method:	`POST`
URL:	`/actions/<action>` where action is the action name.
Body:	The action parameters as a JSON-encoded string or empty if the action expects no parameters.
ContentType:	`application/json` if body is not empty.

Response:

Code:	`200` or `204` if body is empty.
Body:	The return value as a JSON-encoded string or empty if the actions has no return value.
ContentType:	`application/json` if body is not empty.

class cosmic.http.GetByIdEndpoint(model_cls)¶

Request:

Method:	`GET`
URL:	`/<model>/<id>` where model is the model name.

Response:

Code:	`200` or `404` if object is not found.
Body:	The object representation as a JSON-encoded string.
ContentType:	`application/json` if body is not empty.

class cosmic.http.CreateEndpoint(model_cls)¶

Request:

Method:	`POST`
URL:	`/<model>` where model is the model name.
Body:	Corresponding model patch as a JSON-encoded string.
ContentType:	`application/json`

Response:

Code:	`201`
Body:	New model representation as a JSON-encoded string.
ContentType:	`application/json`

class cosmic.http.UpdateEndpoint(model_cls)¶

Request:

Method:	`PUT`
URL:	`/<model>/<id>` where model is the model name.
Body:	A corresponding model patch as a JSON-encoded string.
ContentType:	`application/json`

Response:

Code:	`200` or `404` if object is not found.
Body:	New model representation as a JSON-encoded string.
ContentType:	`application/json`

class cosmic.http.DeleteEndpoint(model_cls)¶

Request:

Method:	`DELETE`
URL:	`/<model>/<id>` where model is the model name.

Response:

Code:	`204` or `404` if object is not found.
Body:	Empty.

class cosmic.http.GetListEndpoint(model_cls)¶

Request:

Method:	`GET`
URL:	`/<model>` where model is the model name.
Query:	Query parameters serialized by the model’s query_schema

Response:

Code:

200

ContentType:

application/json

Body:

The syntax follows JSON HAL specification.

{
    "_links": {
        "self": {"href": <self>}
    },
    "_embedded": {
        <model>: [<repr>*]
    },
    <metadata>*
}

In the above, self is the request URL, model is the name of the model that was requested and repr is a JSON-encoded representation of an object matched by the query. Metadata is defined according to list_metadata.

Exceptions¶

class cosmic.exceptions.SpecError¶

class cosmic.exceptions.NotFound¶: Expected to be raised by get_by_id(), update() and delete() when the resource is not found. Cosmic will convert it to a 404 response on the server, and on the client, it will interpret this response by reraising the exception.

class cosmic.exceptions.HTTPError(code, message)¶

class cosmic.exceptions.RemoteHTTPError(code, message)¶

Tools and Helpers¶

cosmic.tools.get_args(func)¶: Given a function, returns a tuple (required, optional), tuples of non-keyword and keyword arguments respectively. If a function contains splats (* or **), a SpecError will be raised.

cosmic.tools.args_to_datum(*args, **kwargs)¶: Takes arbitrary args and kwargs and packs them into a dict if there are more than one. Returns None if there are no arguments. Must be called with either a single argument or multiple keyword arguments.

cosmic.tools.assert_is_compatible(schema, required_args, optional_args)¶: Raises a SpecError if function argument spec (as returned by get_args()) is incompatible with the given schema. By incompatible, it is meant that there exists such a piece of data that is valid according to the schema, but that could not be applied to the function by apply_to_func().

cosmic.tools.deserialize_json(schema, datum)¶

cosmic.tools.serialize_json(schema, datum)¶

cosmic.tools.string_to_json(s)¶

cosmic.tools.json_to_string(box)¶

cosmic.tools.validate_underscore_identifier(id)¶

cosmic.tools.is_string_type(serializer)¶

Reference¶

APIs¶

Models¶

Types¶

HTTP Endpoints¶

Exceptions¶

Tools and Helpers¶

Table Of Contents

Related Topics

This Page