class cosmic.models.BaseModel

Subclasses of this class are fed into the model() decorator to attach models to an API. The API object doesn’t care about how you implement this class, it just copies the necessary properties and leaves the class alone.


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.

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.


A list of methods that this model supports. Possible values are 'get_by_id', 'create', 'update', 'delete' and 'get_list'.


A list of properties for the get_list() handler. They are defined in the same way as properties above.


A list of properties that can be returned along with the usual response for get_list(). These can be used for things like pagination.

classmethod get_by_id(id)
Returns:Model representation
Raises cosmic.exceptions.NotFound:
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(**valid_patch)
Parameters:validated_patch – The model patch.
Returns:A tuple of model id and model representation.
classmethod update(id, **valid_patch)
  • id
  • validated_patch

The model representation after patch has been applied.

Raises cosmic.exceptions.NotFound:

classmethod delete(id)
Raises cosmic.exceptions.NotFound:
classmethod validate_patch(patch)
Parameters:patch – The model patch
Raises cosmic.exceptions.ValidationError:

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.


HTTP Endpoints


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