API Reference

Schemas

drowsy.schema

Classes for building REST API friendly, model based schemas.

class drowsy.schema.ResourceSchemaOpts(meta, *args, **kwargs)

Meta class options for use with a ModelResourceSchema.

instance_cls` must be set.

Defaults id_keys to None, meaning the actual resource class using these opts must manually override its member id_keys property.

Example usage:

class UserSchema(ResourceSchema):
    class Meta:
        # Use username to identify a user resource
        # rather than user_id.
        id_keys = ["username"]
        # Give a class to be used for initializing
        # new instances for this resource.
        instance_cls = User
        # Custom schema level error messages
        error_messages = {
            "permission_denied": "Don't do that."
        }

__init__(meta, *args, **kwargs)

Handle the meta class attached to a ResourceSchema.

Parameters:

meta – The meta class attached to a ResourceSchema.

class drowsy.schema.ModelResourceSchemaOpts(meta, *args, **kwargs)

Meta class options for use with a ModelResourceSchema.

Defaults model_converter to ModelResourceConverter.

Defaults id_keys to None, resulting in the model’s primary keys being used as identifier fields.

Overwrites instance_cls from ResourceSchemaOpts to model.

Example usage:

class UserSchema(ModelResourceSchema):
    class Meta:
        # Note that model will overwrite instance_cls
        model = User
        # Use username to identify a user resource
        # rather than user_id.
        id_keys = ["username"]
        # Alternate converter to dump/load with camel case.
        model_converter = CamelModelResourceConverter

__init__(meta, *args, **kwargs)

Handle the meta class attached to a ModelResourceSchema.

Parameters:

meta – The meta class attached to a ModelResourceSchema.

class drowsy.schema.ResourceSchema(only=None, exclude=(), many=None, load_only=(), dump_only=(), partial=None, unknown=None, context=None, instance=None, parent_resource=None, error_messages=None)

Schema meant to be used with a Resource.

Enables sub-resource embedding, context processing, error translation, and more.

OPTIONS_CLASS

alias of ResourceSchemaOpts

opts: Any = <drowsy.schema.ResourceSchemaOpts object>

__init__(only=None, exclude=(), many=None, load_only=(), dump_only=(), partial=None, unknown=None, context=None, instance=None, parent_resource=None, error_messages=None)

Sets additional member vars on top of ResourceSchema.

Also runs process_context() upon completion.

Parameters:

• only (tuple or list or None) – Fields to be included in the serialized result.

• exclude (tuple or list) – Fields to be excluded from the serialized result.

• many (bool) – True if loading a collection of items.

• load_only (tuple or list) – Fields to be skipped during serialization.

• dump_only (tuple|list) – Fields to be skipped during deserialization.

• partial (bool) – Ignores missing fields when deserializing if True.

• unknown (UnknownOption) – How to handle unknown fields in provided data. Can be EXCLUDE, INCLUDE, or RAISE.

• context (dict or None) – Dictionary of values relevant to the current execution context. Should have a gettext key and callable value for that key if you’re intending to translate error messages.

• instance – Object instance data should be loaded into. If None is provided, an instance will either be determined using the provided data via get_instance(), or if that fails a new instance will be created.

• parent_resource (BaseResourceABC or None) – The parent resource that owns this schema.

make_error(key, data=None, **kwargs)

Raises an exception based on the key provided.

Parameters:

• key (str) – Failure type, used to choose an error message.

• data (dict or None) – The data that caused this issue

• kwargs – Any additional arguments that may be used for generating an error message.

Returns:

PermissionValidationError exception if key is "permission_denied", otherwise a ValidationError.

property fields_by_data_key

Get a dictionary of fields with data_key as the keys.

Returns:

Dictionary of fields with the keys coming from field.data_key.

Return type:

dict

get_instance(data)

Used primarily to retrieve a pre-existing instance.

Should use the provided data to locate the pre-existing instance, but not to populate it.

Parameters:

data (dict) – Data associated with this instance.

Returns:

An object instance if it already exists, or None.

Raises:

ValidationError – If the id_keys in data are of the wrong type.

embed(items)

Embed the list of field names provided.

Parameters:

items (list or str) – A list or single instance of embeddable sub resources or sub resource fields.

Returns:

None

Return type:

None

Raises:

AttributeError – If the schema does not contain the specified field to embed.

property id_keys

Get the fields used to identify a resource instance.

Returns:

List of attribute names that serve as identifiers for each instance of this resource.

Return type:

list of str

make_instance(data, **kwargs)

Deserialize the provided data into an object instance.

Parameters:

data – The data to be deserialized into an instance.

Returns:

An object instance with the provided data deserialized into it.

load(data, *, many=None, partial=None, unknown=None, instance=None, action=None, **kwargs)

Deserialize the provided data into an object.

Parameters:

• data (dict|list<dict>) – Data to be loaded into an instance.

• many (bool|None) – True if loading a collection. None defers to the schema default, other values will act as an override.

• partial (bool) – Ignores missing fields when deserializing if True.

• unknown (UnknownOption) – How to handle unknown fields in provided data. Can be EXCLUDE, INCLUDE, or RAISE.

• instance – Object instance that data should be loaded into. If None is provided at this point or when the class was initialized, an instance will either be determined using the provided data via get_instance(), or if that fails a new instance will be created.

• action (str|None) – Used as part of a permissions check. Possible values include “create” if a new object is being created, “update” is an existing object is being updated, or “delete” if the object is to be deleted. If None is provided, the method will deduce the action based on whether an existing instance is found in the database (“update”) or not (“create”). If loading a collection, any value passed will be applied to all objects.

Returns:

An instance with the provided data loaded into it.

Raises:

• ValidationError – If any errors are encountered.

• PermissionValidationError – If any of the actions being taken are not allowed.

handle_preexisting_create(data)

Handles trying to create an object that already exists.

You’ll have to override this if you want to treat the "create" action like "update" on a pre-existing object.

Parameters:

data (dict) – The user supplied data that triggered this issue.

Returns:

None

Raises:

ValidationError – If not allowed.

check_permission(data, instance, action)

Checks if this action is permissible to attempt.

Does nothing by default, but can be overridden to check if a create, update, or delete action is permissible before performing any other validation or attempting the action.

Parameters:

• data (dict) – The user supplied data to be deserialized.

• instance – A pre-existing instance the data is to be deserialized into. Should be None if not updating an existing object.

• action (str) – Either "create", "update", or "delete".

Returns:

None

Raises:

PermissionValidationError – If the action being taken is not allowed.

process_context()

Override to modify a schema based on context.

class drowsy.schema.ModelResourceSchema(only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None, instance=None, parent_resource=None, session=None)

Schema meant to be used with a ModelResource.

Enables sub-resource embedding, context processing, error translation, and more.

OPTIONS_CLASS

alias of ModelResourceSchemaOpts

opts: Any = <drowsy.schema.ModelResourceSchemaOpts object>

__init__(only=None, exclude=(), many=False, context=None, load_only=(), dump_only=(), partial=False, unknown=None, instance=None, parent_resource=None, session=None)

Sets additional member vars on top of SQLAlchemyAutoSchema.

Also runs process_context() upon completion.

Parameters:

• only (tuple or list or None) – Fields to be included in the serialized result.

• exclude (tuple or list) – Fields to be excluded from the serialized result.

• many (bool) – True if loading a collection of items.

• context (dict or None) – Dictionary of values relevant to the current execution context. Should have a gettext key and callable value for that key if you’re intending to translate error messages.

• load_only (tuple or list) – Fields to be skipped during serialization.

• dump_only (tuple or list) – Fields to be skipped during deserialization.

• partial (bool) – Ignores missing fields when deserializing if True.

• instance – SQLAlchemy model instance data should be loaded into. If None is provided, an instance will either be determined using the provided data via get_instance(), or if that fails a new instance will be created.

• parent_resource (ModelResource or None) – The parent resource that owns this schema.

• session – SQLAlchemy database session.

get_instance(data)

Retrieve an existing record by primary key(s).

Parameters:

data (dict) – Data associated with this instance.

Returns:

An instance fetched from the database using the value of the id_keys in data.

Raises:

ValidationError – If the id_keys in data are of the wrong type.

property id_keys

Get the fields used to identify a resource instance.

Returns:

List of attribute names that serve as identifiers for each instance of this resource.

Return type:

list of str

load(data, *, many=None, partial=None, unknown=None, instance=None, action=None, session=None, **kwargs)

Deserialize the provided data into a SQLAlchemy object.

Parameters:

• data (dict|list<dict>) – Data to be loaded into an instance.

• many (bool|None) – True if loading a collection. None defers to the schema default, other values will act as an override.

• partial (bool) – Ignores missing fields when deserializing if True.

• unknown (UnknownOption) – How to handle unknown fields in provided data. Can be EXCLUDE, INCLUDE, or RAISE.

• instance – SQLAlchemy model instance data should be loaded into. If None is provided at this point or when the class was initialized, an instance will either be determined using the provided data via get_instance(), or if that fails a new instance will be created.

• action (str|None) – Used as part of a permissions check. Possible values include “create” if a new object is being created, “update” is an existing object is being updated, or “delete” if the object is to be deleted. If None is provided, the method will deduce the action based on whether an existing instance is found in the database (“update”) or not (“create”). If loading a collection, any value passed will be applied to all objects.

• session – Optional database session. Will be used in place of self.session if provided.

Returns:

An instance with the provided data loaded into it.

Raises:

• ValidationError – If any errors are encountered.

• PermissionValidationError – If any of the actions being taken are not allowed.

exclude: set[Any] | MutableSet[Any]

unknown: types.UnknownOption

fields: dict[str, Field]

Dictionary mapping field_names -> Field objects

load_fields: dict[str, Field]

dump_fields: dict[str, Field]

Resources

drowsy.resource

Base classes for building resources and model resources.

class drowsy.resource.PaginationInfo(resources_available, page_size=None, current_page=None)

Pagination meta info container.

__init__(resources_available, page_size=None, current_page=None)

Initializes pagination info container.

Parameters:

• resources_available (int) – The total number of matching resources for a query. Used for pagination info.

• page_size (int or None) – The current page number for the result.

• current_page (int or None) – The current page number for the result.

property page_size

Get the number of resources included in a result collection.

Returns:

The size of each page in a result collection.

Return type:

int or None

property current_page

Get the current page of this resource collection.

Returns:

The current page of this resource collection.

Return type:

int or None

property first_page

Get the first page number of this resource collection.

Returns:

1 if pagination is being used, otherwise None.

Return type:

int or None

property last_page

Get the last page number of this resource collection.

Returns:

The number of the last page if pagination is being used, otherwise None.

Return type:

int or None

property previous_page

Get the previous page number based on the current page.

Returns:

The current page number - 1 if pagination is being used, and if the current page isn’t the first page.

Return type:

int or None

property next_page

Get the next page number based on the current page number.

Returns:

The current page number + 1 if pagination is being used, and if the current page isn’t the last page.

Return type:

int or None

class drowsy.resource.ResourceCollection(resources, resources_available, page_size=None, current_page=None)

A simple list subclass that contains some extra meta info.

__init__(resources, resources_available, page_size=None, current_page=None)

Initializes a resource collection.

Parameters:

• resources (iterable) – The resources that were fetched in a query.

• resources_available (int) – The total number of matching resources for a query. Used for pagination info.

• page_size (int or None) – The current page number for the result.

• current_page (int or None) – The current page number for the result.

property resources_fetched

Simple alias for list length.

Returns:

Number of resources that were fetched.

Return type:

int

class drowsy.resource.ResourceOpts(meta)

Meta class options for use with a SchemaResource.

A schema_cls option must be provided.

An options option may be provided as a list in order to explicitly state what actions may be taken on this resource, with GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS as possible values.

An error_messages option may be provided as a dict in order to override some or all of the default error messages for a resource.

A page_max_size option may be provided as an int, callable, or None to specify default page size for this resource. If given a callable, it should the resource itself as an argument.

Example usage:

class UserResource(ModelResource):
    class Meta:
        schema_cls = UserSchema
        options = ["GET", "POST", "PUT", "PATCH]
        error_messages = {
            "validation_failure": "Fix your data."
        }
        page_max_size = 100

__init__(meta)

Handle the meta class attached to a ModelResource.

Parameters:

meta – The meta class attached to a ModelResource.

class drowsy.resource.ResourceMeta(name, bases, attrs)

Meta class inherited by ModelResource.

This is ultimately responsible for attaching an opts object to ModelResource, as well as registering that class with the resource_class_registry.

__init__(name, bases, attrs)

Initializes the meta class for a ModelResource class.

Parameters:

• cls – This ResourceMeta class.

• name – Class name of the ModelResource that this meta class is attached to.

• bases (tuple) – Base classes the associated class inherits from.

• attrs (dict) – Dictionary of info pertaining to the class this meta class is attached to. Includes the __module__ the class is in, the __qualname__ of the class, and potentially __doc__ for the class.

class drowsy.resource.BaseModelResource(session, context=None, page_max_size=None, error_messages=None, parent_field=None)

Model API Resources should inherit from this object.

OPTIONS_CLASS

alias of ResourceOpts

__init__(session, context=None, page_max_size=None, error_messages=None, parent_field=None)

Creates a new instance of the model.

Parameters:

• session (Session or callable) – Database session to use for any resource actions.

• context (dict, callable, or None) – Context used to alter the schema used for this resource. For example, may contain the current authorization status of the current request. If errors should be translated, context should include a "gettext" key referencing a callable that takes in a string and any keyword args.

• page_max_size (int, callable, or None) – Used to determine the maximum number of results to return by get_collection(). Defaults to the page_max_size from the resource’s opts if None is passed in. To explicitly allow no limit, pass in 0. If given a callable, it should accept the resource itself as its first and only argument.

• error_messages (dict or None) – May optionally be provided to override the default error messages for this resource.

• parent_field (Field) – The field that owns this resource, if applicable. Likely some variety of NestedPermissibleABC.

make_error(key, errors=None, exc=None, **kwargs)

Returns an exception based on the key provided.

Parameters:

• key (str) – Failure type, used to choose an error message.

• errors (dict or None) – May be used by the raised exception.

• exc (Exception or None) – If another exception triggered this failure, it may be provided for a more informative failure. In the case of an InvalidMqlException being provided, the exc.message will be used as part of the error message here.

• kwargs – Any additional arguments that may be used for generating an error message.

Returns:

UnprocessableEntityError If key is "validation_failure". Note that in this case, errors should preferably be provided. In all other cases a BadRequestError is returned.

property model

Get the model class associated with this resource.

property session

Get a db session to use for this request.

property query_builder

Returns a ModelResourceQueryBuilder object.

This exists mainly for inheritance purposes.

get_required_filters(alias=None)

Build any required filters for this resource.

Does nothing by default, but can be usefully overridden if you want to enforce certain filters on this resource. A simple example would be a notifications resource where a filter matching the currently logged in user is applied.

e.g.:

model = alias or self.model
return model.user_id == self.context.get("user_id")

Parameters:

alias – Can optionally be supplied if this resource is being used as a subresource and an alias has been applied.

Returns:

Any valid SQL expression(s), to be passed directly into filter(). If multiple expressions, they may be returned in a list or tuple. Defaults to None.

get_required_nested_filters(key)

For a given dot separated data key, return required filters.

Uses get_required_filters() from child resources.

Parameters:

key (str) – Dot notation field name. For example, if trying to query an album, this may look something like "tracks.playlists".

Returns:

Any valid SQL expression(s), to be passed directly into filter(). If multiple expressions, they may be returned in a list or tuple. Defaults to None.

apply_required_filters(query, alias=None)

Apply required filters on this query.

Applies the result of get_required_filters() directly to the provided query.

If you’re looking to define any required filters for a resource, you’ll want to override get_required_filters() rather than this method. Doing so ensures those filters are applied when the resource is used as a child resource as well.

Parameters:

• query (Select) – An already partially constructed sqlalchemy query.

• alias – Can optionally be used if this resource is being used as a subresource and an alias has been applied.

Returns:

A potentially modified query object.

Return type:

Query

property options

Get the available options for this resource.

Returns:

A list of available options for this resource. Values can include GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

Return type:

list

get(ident, subfilters=None, fields=None, embeds=None, query=None, strict=True, head=False)

Get the identified resource.

Parameters:

• ident – A value used to identify this resource. If the schema associated with this resource has multiple id_keys, this value may be a list or tuple.

• subfilters (dict or None) – A dict of MQLAlchemy filters, with each key being the dot notation of the relationship they are to be applied to.

• fields (list or None) – Names of fields to be included in the result.

• embeds (collection or None) – A list of relationship and relationship field names to be included in the result.

• query (Select) – Optional base sqlalchemy query, allowing for sub-resource queries by using :meth:~`sqlalchemy.orm.with_parent`.

• strict (bool) – If True, will raise an exception when bad parameters are passed. If False, will quietly ignore any bad input and treat it as if none was provided.

• head (bool) – If this was a HEAD request. Doesn’t affect anything here, but supplied in case there’s desire to override the method.

Raises:

• ResourceNotFoundError – If no such resource exists.

• BadRequestError – Invalid fields or embeds will result in a raised exception if strict is set to True.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

The resource itself if found.

Return type:

dict

post(data)

Create a new resource and store it in the db.

Parameters:

data (dict) – Data used to create a new resource.

Raises:

• UnprocessableEntityError – If the supplied data cannot be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

The created resource.

Return type:

dict

put(ident, data)

Replace the current object with the supplied one.

Parameters:

• ident – A value used to identify this resource. See get() for more info.

• data (dict) – Data used to replace the resource.

Raises:

• ResourceNotFoundError – If no such resource exists.

• UnprocessableEntityError – If the supplied data cannot be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

The replaced resource.

Return type:

dict

patch(ident, data)

Update the identified resource with the supplied data.

Parameters:

• ident – A value used to identify this resource. See get() for more info.

• data (dict) – Data used to update the resource.

Raises:

• ResourceNotFoundError – If no such resource exists.

• UnprocessableEntityError – If the supplied data cannot be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

The updated resource.

Return type:

dict

delete(ident)

Delete the identified resource.

Parameters:

ident – A value used to identify this resource. See get() for more info.

Raises:

• ResourceNotFoundError – If no such resource exists.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

None

get_collection(filters=None, subfilters=None, fields=None, embeds=None, sorts=None, offset=None, limit=None, query=None, strict=True, head=False)

Get a collection of resources.

Parameters:

• filters (dict or None) – MQLAlchemy filters to be applied on this query.

• subfilters (dict or None) – A dict of MQLAlchemy filters, with each key being the dot notation of the relationship they are to be applied to.

• fields (list or None) – Names of fields to be included in the result.

• embeds (collection or None) – A list of relationship and relationship field names to be included in the result.

• sorts (list of SortInfo, or None) – Sorts to be applied to this query.

• offset (int or None) – Standard SQL offset to be applied to the query.

• limit (int or None) – Standard SQL limit to be applied to the query.

• query (Select) – Optional base sqlalchemy query, allowing for sub-resource queries by using :meth:~`sqlalchemy.orm.with_parent`.

• strict (bool) – If True, will raise an exception when bad parameters are passed. If False, will quietly ignore any bad input and treat it as if none was provided.

• head (bool) – If this was a HEAD request. Doesn’t affect anything here, but supplied in case there’s desire to override the method.

Raises:

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit will result in a raised exception if strict is set to True.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

Resources meeting the supplied criteria.

Return type:

ResourceCollection

post_collection(data)

Create multiple resources in the collection of resources.

Parameters:

data (list) – List of resources to be created.

Raises:

• UnprocessableEntityError – If the supplied data cannot be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

None

put_collection(data)

Raises an error since this method has no obvious use.

Parameters:

data (list) – A list of object data. Would theoretically be used to replace the entire collection.

Raises:

MethodNowAllowedError – When not overridden.

patch_collection(data)

Update a collection of resources.

Individual items may be updated accordingly as part of the request as well.

Parameters:

data (list) – A list of object data. If the object contains a key $op set to "add", the object will be added to the collection; otherwise the object must already be in the collection. If $op is set to "remove", it is accordingly removed from the collection.

Raises:

• UnprocessableEntityError – If the supplied data cannot be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

None

delete_collection(filters=None, query=None, strict=True)

Delete all filter matching members of the collection.

Parameters:

• filters (dict or None) – MQLAlchemy style filters.

• query (Select) – See get() for more info.

• strict (bool) – If True, will raise an exception when bad parameters are passed. If False, will quietly ignore any bad input and treat it as if none was provided.

Raises:

• UnprocessableEntityError – If the deletions are unable to be processed.

• MethodNotAllowedError – If this method hasn’t been marked as allowed in the meta class options.

Returns:

None

class drowsy.resource.ModelResource(session, context=None, page_max_size=None, error_messages=None, parent_field=None)

opts = <drowsy.resource.ResourceOpts object>

Model Converters

drowsy.converter

Convert SQLAlchemy models into Marshmallow schemas.

class drowsy.convert.ModelResourceConverter(schema_cls: type[Schema] | None = None)

Convert a model’s fields for use in a ModelResourceSchema.

property2field(prop, instance=True, field_class=None, **kwargs)

Parameters:

• prop (ColumnProperty or RelationshipProperty) – A column or relationship property used to determine a corresponding field.

• instance – True if this method should return an actual instance of a field, False to return the actual field class.

• field_class (Field) – Class of field to attempt to instantiate.

• kwargs – Keyword args to be used in the construction of the field.

Returns:

Depending on the value of instance, either a field or a field class.

Return type:

Field or type

fields_for_model(model, *, include_fk=False, include_relationships=False, fields=None, exclude=None, base_fields=None, dict_cls=<class 'dict'>)

Generate fields for the provided model.

Parameters:

• model – The SQLAlchemy model the generated fields correspond to.

• include_fk (bool) – True if fields should be generated for foreign keys, False otherwise.

• include_relationships (bool) – True if relationship fields should be generated, False otherwise.

• fields (Iterable or None) – A collection of field names to generate.

• exclude (Iterable or None) – A collection of field names not to generate.

• base_fields (dict or None) – Optional dict of default fields to include in the result.

• dict_cls – Optional specific type of dict to use for the result.

Returns:

Generated fields corresponding to each model property.

Return type:

dict or the provided dict_cls

class drowsy.convert.CamelModelResourceConverter(schema_cls: type[Schema] | None = None)

Convert a model to a schema that uses camelCase field names.

Param Parsers

drowsy.parser

Functions for parsing query info from url parameters.

class drowsy.parser.SortInfo(attr=None, direction='ASC')

Used to transport info regarding sorts around.

__init__(attr=None, direction='ASC')

Instantiates a SortInfo object.

Parameters:

• attr (str) – Name of the attr to be sorted on.

• direction (str) – Must be "ASC" or "DESC".

Raises:

• ValueError – If direction is not "ASC", "DESC", or None.

• TypeError – If any of the provided parameters are not of the specified type.

class drowsy.parser.OffsetLimitInfo(offset=None, limit=None)

Used to transport info regarding offsets and limits around.

__init__(offset=None, limit=None)

Instantiates a OffsetLimitInfo object.

Parameters:

• offset (int or None) – Offset to be applied.

• limit (int or None) – Limit to be applied.

Raises:

• ValueError – If offset or limit is not a positive number or None.

• TypeError – If any of the provided parameters are not of the specified type.

property offset

Get an offset value.

Returns:

An offset value.

Return type:

int or None

property limit

Get a limit value.

Returns:

An limit value.

Return type:

int or None

class drowsy.parser.SubfilterInfo(offset=None, limit=None, filters=None, sorts=None)

Object used to transport info regarding subqueries around.

__init__(offset=None, limit=None, filters=None, sorts=None)

Instantiates a SubfilterInfo object.

Parameters:

• offset (int or None) – Offset to be applied.

• limit (int or None) – Limit to be applied.

• filters (dict or None) – Filters to be applied.

• sorts (list of SortInfo or None) – Any sorts that are to be applied.

Raises:

• ValueError – If offset or limit is not a positive number or None.

• TypeError – If any of the provided parameters are not of the specified type.

property filters

Get the filters to be applied to a subresource.

Returns:

A dictionary of filters for a subresource.

Return type:

dict or None

property sorts

Get the sorts to be applied to a subresource.

Returns:

A collection of sorts for a subresource.

Return type:

list or None

class drowsy.parser.QueryParamParser(query_params=None, error_messages=None, context=None)

Utility class used to parse query parameters.

__init__(query_params=None, error_messages=None, context=None)

Sets up error messages, translations, and query params.

Parameters:

• query_params (dict or None) – Query params potentially containing filters, embeds, fields, and sorts.

• error_messages (dict or None) – Optional dictionary of error messages, useful if you want to override the default errors.

• context (dict, callable, or None) – Optional dictionary of context information. If error messages should be translated, context should include a "gettext" key set to a callable that takes in a string and any kwargs and returns a translated string.

property context

Return the context for this request.

Return type:

dict, callable, or None

make_error(key, **kwargs)

Return an exception based on the key provided.

Parameters:

• key (str) – Failure type, used to choose an error message.

• kwargs – Any additional arguments that may be used for generating an error message.

Returns:

FilterParseError`in cases where there was an issue parsing a filter. `OffsetLimitParseError in cases where there was an issue parsing the offset, limit, or page value. ParseError raised in all other cases.

parse_fields(fields_query_name='fields')

Parse from query params the fields to include in the result.

Parameters:

fields_query_name (str) – The name of the key used to check for fields in the provided query_params.

Returns:

A list of fields to be included in the response.

Return type:

list of str

parse_embeds(embeds_query_name='embeds')

Parse sub-resource embeds from query params.

Parameters:

embeds_query_name (str) – The name of the key used to check for an embed in the provided query_params.

Returns:

A list of embeds to include in the response.

Return type:

list of str

parse_offset_limit(page_max_size=None, page_query_name='page', offset_query_name='offset', limit_query_name='limit', strict=True)

Parse offset and limit from the provided query params.

Parameters:

• page_max_size (int or None) – If page is provided, page_max_size limits the number of results returned. Otherwise, if using limit and offset values from the query_params, page_max_size sets a max number of records to allow.

• page_query_name (str) – The name of the key used to check for a page value in the provided query_params. If page is provided, it is used along with the page_max_size to determine the offset that should be applied to the query. If a page number other than 1 is provided, a page_max_size must also be provided.

• offset_query_name (str) – The name of the key used to check for an offset value in the provided query_params.

• limit_query_name (str) – The name of the key used to check for a limit value in the provided query_params.

• strict – If True, exceptions will be raised for invalid input. Otherwise, invalid input will be ignored.

Raises:

OffsetLimitParseError – Applicable if using strict mode only. If the provided limit is greater than page_max_size, or an invalid page, offset, or limit value is provided, then an OffsetLimitParseError is raised.

Returns:

An offset and limit value for this query.

Return type:

OffsetLimitInfo

parse_sorts(sort_query_name='sort')

Parse sorts from provided the query params.

Parameters:

sort_query_name (str) – The name of the key used to check for sorts in the provided query_params.

Returns:

The sorts that should be applied.

Return type:

list of SortInfo

class drowsy.parser.ModelQueryParamParser(query_params=None, error_messages=None, context=None)

Param parser with added ability to parse MQLAlchemy filters.

parse_subfilters(subquery_name='_subquery_', sublimit_name='_limit_', suboffset_name='_offset_', subsorts_name='_sorts_', strict=True)

Parse nested resource subfilters, limits, offsets, and sorts.

Note that subquery parsing does limited checking on the validity of the subquery itself.

Given a query param “album.artist._subquery_.tracks.track_id” with value “5”, the resulting subfilters returned would be:

result = {
    "album.artist": SubfilterInfo(
        filters={
            "$and": ["tracks.track_id": {"eq": 5}]
        }
    )
}

Parameters:

• subquery_name (str) – The name of the key used to check for a subquery value in the provided query_params.

• sublimit_name (str) – The name of the key used to check for a sublimit value in the provided query_params.

• suboffset_name (str) – The name of the key used to check for a suboffset value in the provided query_params.

• subsorts_name (str) – The name of the key used to check for a subsorts value in the provided query_params.

• strict (bool) – If True, exceptions will be raised for invalid input. Otherwise, invalid input will be ignored.

Raises:

• FilterParseError – Malformed complex queries or invalid query_params will result in an FilterParseError being raised if strict is True.

• OffsetLimitParseError – Raised in cases where there was an issue parsing an offset or limit if strict is True.

• ParseError – Raised if strict is True and there is an issue parsing the provided sorts for a subfilter.

Returns:

A dictionary containing subqueries that can be passed to mqlalchemy for query filtering.

Return type:

dict of str, SubfilterInfo

parse_filters(model_class, complex_query_name='query', only_parse_complex=False, convert_key_names_func=<class 'str'>, subquery_name='_subquery_', sublimit_name='_limit_', suboffset_name='_offset_', subsorts_name='_sorts_', strict=True)

Convert request params into MQLAlchemy friendly search.

Parameters:

• model_class – The SQLAlchemy class being queried.

• complex_query_name (str) – The name of the key used to check for a complex query value in the provided query_params. Note that the complex query should be a json dumped dictionary value.

• only_parse_complex (bool) – Set to True if all simple filters in the query params should be ignored.

• convert_key_names_func (callable or None) – If provided, should take in a dot separated attr name and transform it such that the result is the corresponding dot separated attribute in the model_class being queried. Useful if, for example, you want to allow users to provide an attr name in one format (say camelCase) and convert it to the naming format used for your model objects (likely underscore).

• subquery_name (str or None) – Query param name used to trigger a subquery. Query params that include this name will be ignored.

• sublimit_name (str or None) – Query param name used to trigger a subquery resource limit. Query params that include this name will be ignored.

• suboffset_name (str or None) – Query param name used to trigger a subquery resource offset. Query params that include this name will be ignored.

• subsorts_name (str or None) – Query param name used to trigger a subquery sort. Query params that include this name will be ignored.

• strict (bool) – If True, exceptions will be raised for invalid input. Otherwise, invalid input will be ignored.

Raises:

FilterParseError – Malformed complex queries or invalid query_params will result in an FilterParseError being raised if strict is True.

Returns:

A dictionary containing filters that can be passed to mqlalchemy for query filtering.

Return type:

dict

Query Builders

drowsy.query_builder

Tools for building SQLAlchemy queries.

drowsy.query_builder.manipulate_filters_to_list(filters)

Return filters as a list of filters, regardless of input format.

Parameters:

filters (SQLAlchemy expression, list, tuple, or None) – SQLAlchemy filters to be applied to a query

class drowsy.query_builder.QueryBuilder

Utility class for building a SQLAlchemy query.

row_number_supported(dialect, dialect_override=None)

Given a SQL dialect, figure out if row_number is supported.

Parameters:

• dialect (str) – SQL dialect being used, e.g. "mssql".

• dialect_override (bool) – Can be used to force this method to return True or False.

Returns:

True if the dialect supports row_number or if dialect_override is True. Otherwise False.

Return type:

bool

apply_sorts(query, sorts, convert_key_names_func=<class 'str'>)

Apply sorts to a provided query.

Parameters:

• query (Query) – A SQLAlchemy query; filters must already have been applied.

• sorts (list of SortInfo) – A list of sorts to apply to this query.

• convert_key_names_func (callable) – Used to convert key names. See parse_filters().

Raises:

• AttributeError – If a sort with an invalid attr name is provided.

• ValueError – If a sort not of type SortInfo is provided, or if query isn’t of a single model type.

Returns:

A modified version of the provided query object.

Return type:

Query

apply_offset(query, offset)

Applies offset and limit to the query if appropriate.

Parameters:

• query (Query) – Any desired filters must already have been applied.

• offset (int or None) – Integer used to offset the query result.

Raises:

• ValueError – If a non None offset is provided that is converted to a negative integer.

• TypeError – If a non None offset is provided of a non integer, or integer convertible, type.

Returns:

A modified query object with an offset applied.

Return type:

Query

apply_limit(query, limit)

Applies limit to the query if appropriate.

Parameters:

• query (Query) – Any desired filters must already have been applied.

• limit (int or None) – Integer used to limit the number of results returned.

Raises:

• ValueError – If a non None limit is provided that is converted to a negative integer.

• TypeError – If a non None offset is provided of a non integer, or integer convertible, type.

Returns:

A modified query object with an limit applied.

Return type:

Query

apply_filters(model_class, query, filters, whitelist=None, nested_conditions=None, stack_size_limit=100, convert_key_names_func=<class 'str'>, gettext=None)

Apply filters to a query using MQLAlchemy.

Parameters:

• query – A SQLAlchemy session or query.

• model_class – The model having filters applied to it.

• filters (dict or None) – The MQLAlchemy style filters to apply.

• whitelist (callable, list, set, or None) – Used to determine what attributes are acceptable to be queried.

• nested_conditions (callable, dict, or None) – Callable accepting one param, or dict, where the key/param is a dot separated relationship name, and the return value is any required SQL expressions for filtering that relationship.

• stack_size_limit (int or None) – Used to limit the allowable complexity of the applied filters.

• convert_key_names_func (callable) – Used to convert the attr names from user input (perhaps in camelCase) to the model format (likely in under_score format).

• gettext (callable or None) – Used to translate any errors.

Raises:

InvalidMQLException – Raised in cases where invalid filters were supplied.

Returns:

The query with filters applied.

class drowsy.query_builder.ModelResourceQueryBuilder

Class for building a SQLAlchemy query by using resources.

class SubqueryNode(name, alias=None, parent=None, children=None, subquery=None, limit=None, limit_source=None, offset=None, sorts=None, convert_key_name=None, whitelist=None, relationship_direction=None, joined=False, option=None, join=None, filters=None, id_keys=None, strategy=None, unaliased_filters=None)

Used for building a query with subresource filters included.

Not intended for external access.

__init__(name, alias=None, parent=None, children=None, subquery=None, limit=None, limit_source=None, offset=None, sorts=None, convert_key_name=None, whitelist=None, relationship_direction=None, joined=False, option=None, join=None, filters=None, id_keys=None, strategy=None, unaliased_filters=None)

Parameters:

• name (str) – Name of the subresource.

• alias

• parent (SubqueryNode or None) – The parent of this SubqueryNode. Always has a value, unless this is the root node.

• children (list of SubqueryNode or None) – Holds any child subresource nodes.

• subquery – An aliased SQLAlchemy select statement.

• limit (int or None) – Limit the number of results for this subresource.

• limit_source (str) – Whether the limit was provided by the “user” or was a “default”.

• offset (int or None) – Offset to apply to the query for this node.

• sorts (list of SortInfo) – Any sorts to apply to the query for this node.

• convert_key_name (callable or None) – Function for converting from user facing field names to internal field names.

• whitelist (callable or None) – What fields are acceptable to be queried for this model.

• joined (bool) – True if the subquery has been joined into our final query.

• relationship_direction

• option

build(query, resource, filters, subfilters, embeds=None, offset=None, limit=None, sorts=None, strict=True, stack_size_limit=100, dialect_override=None)

Build a complex query using user supplied parameters.

Parameters:

• query – A SQLAlchemy query.

• resource (BaseModelResource) – Base resource containing the sub resources that are to be filtered.

• filters (dict or None) – The MQLAlchemy style filters to apply.

• subfilters (dict or None) – Dictionary of filters to apply to embedded subresources, with the subresource dot separated name as the key.

• embeds (list or None) – List of subresources and fields to embed.

• offset (int or None) – Integer used to offset the query result.

• limit (int or None) – Integer used to limit the number of results returned.

• sorts (list of SortInfo) – A list of sorts to apply to this query.

• strict (bool) – If True, will raise an exception when bad parameters are passed. If False, will quietly ignore any bad input and treat it as if none was provided.

• stack_size_limit (int or None) – Used to limit the allowable complexity of the applied filters.

• dialect_override (bool|None) – True will build query with row_number support regardless of any db limitations. If False, will avoid using row_number even if the database supports it. Mainly used for testing.

Returns:

query with joins, load options, and subresource filters applied as appropriate.

Raises:

• BadRequestError – Uses the provided resource to raise an error when subfilters or embeds are unable to be successfully applied.

• ValueError – Due to programmer error. Generally Only raised if one of the above parameters is of the wrong type.

apply_subquery_loads(query, resource, subfilters, embeds=None, offset=None, limit=None, sorts=None, strict=True, stack_size_limit=100, dialect_override=None)

Apply joins, load options, and subfilters to a query.

Parameters:

• query – A SQLAlchemy query.

• resource (BaseModelResource) – Base resource containing the sub resources that are to be filtered.

• subfilters – Dictionary of filters to apply to embedded subresources, with the subresource dot separated name as the key.

• embeds (list or None) – List of subresources and fields to embed.

• offset (int or None) – Integer used to offset the query result.

• limit (int or None) – Integer used to limit the number of results returned.

• sorts (list of SortInfo) – A list of sorts to apply to this query.

• strict (bool) – If True, will raise an exception when bad parameters are passed. If False, will quietly ignore any bad input and treat it as if none was provided.

• stack_size_limit (int or None) – Used to limit the allowable complexity of the applied filters.

• dialect_override (bool|None) – True will build query with row_number support regardless of any db limitations. If False, will avoid using row_number even if the database supports it. Mainly used for testing.

Returns:

query with joins, load options, and subresource filters applied as appropriate.

Return type:

Query

Raises:

• BadRequestError – Uses the provided resource to raise an error when subfilters or embeds are unable to be successfully applied.

• ValueError – Due to programmer error. Generally Only raised if one of the above parameters is of the wrong type.

Fields

drowsy.fields

Marshmallow fields used in resource schemas.

class drowsy.fields.EmbeddableRelationshipMixin(*args, **kwargs)

Defaults to returning a relationship’s URL if not embedded.

get_url(obj)

Get the URL for this relationship.

Very likely that you’ll want to override this.

Parameters:

obj – The parent object being serialized.

deserialize(value, *args, **kwargs)

Return the field’s deserialized value.

Parameters:

value – The value provided by the user for this field. If it’s the field’s URL, the value is essentially ignored.

class drowsy.fields.NestedRelated(nested, load_default=<marshmallow.missing>, dump_default=<marshmallow.missing>, exclude=(), only=None, many=False, columns=None, permissions_cls=None, **kwargs)

A nested relationship field for use in ModelResourceSchema.

__init__(nested, load_default=<marshmallow.missing>, dump_default=<marshmallow.missing>, exclude=(), only=None, many=False, columns=None, permissions_cls=None, **kwargs)

Initialize a nested related field.

Parameters:

• nested – The Schema class or class name (string) to nest, or "self" to nest a Schema within itself.

• default – Default value to use if attribute is missing.

• exclude (list, tuple, or None) – Fields to exclude.

• only (tuple, str, or None) – A tuple or string of the field(s) to marshal. If None, all fields will be marshalled. If a field name (string) is given, only a single value will be returned as output instead of a dictionary. This parameter takes precedence over exclude.

• many (bool) – Whether the field is a collection of objects.

• columns (list) – Optional column names on related model. If not provided, the primary key(s) of the related model will be used.

• permissions_cls – The class of permissions to apply to this relationship. Defaults to allowing all relationship operation. May be used to limit the operations that can be done.

• kwargs – The same keyword arguments that Field receives.

property model

The model associated with this relationship.

property related_keys

Gets a list of id keys associated with this nested obj.

Note the hierarchy of id keys to return:

1. If the attached schema for this nested field has an id_keys attr, use those keys.

2. Else, if this field had a columns arg passed when initialized, use those column names.

3. Else, use the primary key columns.

property context

The context dictionary for the parent Schema.

class drowsy.fields.Relationship(*args, **kwargs)

Default relationship field.

When serialized, returns the relationship’s assumed URL if not embedded. Otherwise, returns the nested values of the relationship.

class drowsy.fields.APIUrl(endpoint_name, base_url=None, *args, **kwargs)

Text field, displays the url of the resource it’s attached to.

__init__(endpoint_name, base_url=None, *args, **kwargs)

Initializes an APIUrl field.

Parameters:

• endpoint_name (str) – The name of this URL endpoint and where to access this resource.

• base_url (str or callable) – A str or callable (with no args) that returns the base part of the API url: https://example.com/api

• args – Any field arguments to be passed to the super constructor.

• kwargs – Any field keyword arguments to be passed to the super constructor.

serialize(attr, obj, accessor=None, **kwargs)

Serialize an API url.

Parameters:

• attr (str) – The attribute name of this field. Unused.

• obj – The object to pull any needed info from.

• accessor (callable or None) – Function used to pull values from obj. Defaults to get_value().

Raises:

ValidationError – In case of formatting problem.

Returns:

The serialized API url value.

Routers

drowsy.router

Tools for automatically routing API url paths to resources.

class drowsy.router.ResourceRouterABC(resource, error_messages=None)

Abstract base class for a resource based automatic router.

__init__(resource, error_messages=None)

Sets up router error messages and translations.

Parameters:

• resource (Resource) – A resource instance.

• error_messages (dict or None) – Optional dictionary of error messages, useful if you want to override the default errors.

property context

Return the context used for this request.

make_error(key, **kwargs)

Returns an exception based on the key provided.

Parameters:

• key (str) – Failure type, used to choose an error message.

• kwargs – Any additional arguments that may be used for generating an error message.

Returns:

ResourceNotFoundError, MethodNotAllowedError, or defaults to BadRequestError.

options(path)

Get a list of available options for this resource.

Returns:

The options available for this resource at the supplied path.

Return type:

list

get(path, query_params=None, strict=True, head=False)

Generic API router for GET requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• query_params (dict or None) – Dictionary of query parameters, likely provided as part of a request. Defaults to an empty dict.

• strict (bool) – If True, bad query params will raise non fatal errors rather than ignoring them.

• head (bool) – True if this was a HEAD request.

Returns:

If this is a single entity query, an individual resource in dict form. If this is a collection query, a list of resources in dict form.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit as defined in the provided query params will result in a raised exception if strict is set to True.

put(path, data)

Generic API router for PUT requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of entities to replace the current value with at the given path.

Returns:

If this is a put to a subresource collection, the replaced subresource is returned. If this is a put to an individual resource then the replaced resource is returned. If this is a put to a field, the replaced field value is returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – A put on a top level collection will raise this error.

patch(path, data)

Generic API router for PATCH requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of entities to add or remove at the given path.

Returns:

If this is a patch to a resource collection, None is returned. If this is a patch to a subresource collection, the updated subresource is returned. If this is a patch to an individual resource then the updated resource is returned. If this is a patch to a field, the updated field value is returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – A patch at a valid path may return this due to permission issues.

post(path, data)

Generic API router for POST requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of new entities to add at the given path.

Returns:

If this is a post to a top level resource, then the newly created resource or list of resources will be returned in dict or list of dicts form. If this is a post to a subresource, then the updated subresource data will be returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – Posts to individual properties or resources will cause an error.

delete(path, query_params=None)

Generic API router for DELETE requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• query_params (dict or None) – Dictionary of query parameters, likely provided as part of a request. Defaults to an empty dict.

Returns:

None if successful.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit as defined in the provided query params will result in a raised exception if strict is set to True.

• MethodNotAllowedError – If deleting the resource at the supplied path is not allowed.

dispatcher(method, path, query_params=None, data=None, strict=True)

Route requests based on path and resource.

Parameters:

• method (str) – HTTP verb method used to make this request.

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• query_params (dict) – Dictionary of query parameters, likely provided as part of a request.

• strict (bool) – If True, faulty pagination info, fields, or embeds will result in an error being raised rather than silently ignoring them.

• data – The data supplied as part of the incoming request body. Optional, and the format of this data may vary.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit as defined in the provided query params will result in a raised exception if strict is set to True.

• UnprocessableEntityError – On post, patch, put, and delete requests, if the corresponding action can not be completed, an exception will be raised.

Returns:

Dependent on the method and whether the path refers to a collection or individual resource.

• Get: An individual resource in dict form.

• Head: An individual resource in dict form. Should only

  be used for header info, the actual resource should not be returned to a user.

• Post: The created resource in dict form if successful.

• Patch: The updated resource in dict form if successful.

• Put: The replaced resource in dict form if successful.

• Delete: None if successful.

• Get collection: A list of resources in dict form.

• Head collection: A list of resources in dict form. Should

  only be used for header info, the actual resource should not be returned to a user.

• Patch collection: None if successful.

• Post collection: A list of created resources in dict form.

• Delete collection: None if successful.

class drowsy.router.ModelResourceRouter(resource=None, error_messages=None, context=None, session=None, convert_type_func=None)

Utility class used to route incoming requests.

Currently handles nested resources assuming they’re of ModelResource type.

__init__(resource=None, error_messages=None, context=None, session=None, convert_type_func=None)

Sets up router error messages and translations.

Parameters:

• resource (ModelResource or None) – A resource instance. If none is provided, an attempt to dynamically create a resource upon dispatch using the provided path, context, and session will be made.

• error_messages (dict or None) – Optional dictionary of error messages, useful if you want to override the default errors.

• convert_type_func (callable|None) – Function with two args, the first being a string value, and the second a SQLAlchemy column type to convert that value to. If no value is provided, defaults to using convert_to_alchemy_type from MQLAlchemy.

property context

Return the schema context for this resource.

property session

Return the session for this resource.

put(path, data)

Generic API router for PUT requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of entities to replace the current value with at the given path.

Returns:

If this is a put to a subresource collection, the replaced subresource is returned. If this is a put to an individual resource then the replaced resource is returned. If this is a put to a field, the replaced field value is returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – A put on a top level collection will raise this error.

patch(path, data)

Generic API router for PATCH requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of entities to add or remove at the given path.

Returns:

If this is a patch to a resource collection, None is returned. If this is a patch to a subresource collection, the updated subresource is returned. If this is a patch to an individual resource then the updated resource is returned. If this is a patch to a field, the updated field value is returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – A patch at a valid path may return this due to permission issues.

post(path, data)

Generic API router for POST requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• data – A dict or list of dicts of new entities to add at the given path.

Returns:

If this is a post to a top level resource, then the newly created resource or list of resources will be returned in dict or list of dicts form. If this is a post to a subresource, then the updated subresource data will be returned.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• MethodNotAllowedError – Posts to individual properties or resources will cause an error.

options(path)

Generic API router for OPTIONS requests.

Parameters:

path (str) – The resource path specified. This should not include the root /api or any versioning info.

Returns:

A list of available options for the resource at the supplied path. Such options may include GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

get(path, query_params=None, strict=True, head=False)

Generic API router for GET requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• query_params (dict or None) – Dictionary of query parameters, likely provided as part of a request. Defaults to an empty dict.

• strict (bool) – If True, bad query params will raise non fatal errors rather than ignoring them.

• head (bool) – True if this was a HEAD request.

Returns:

If this is a single entity query, an individual resource or None. If this is a collection query, a list of resources. If it’s an instance field query, the raw field value.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit as defined in the provided query params will result in a raised exception if strict is set to True.

delete(path, query_params=None)

Generic API router for DELETE requests.

Parameters:

• path (str) – The resource path specified. This should not include the root /api or any versioning info.

• query_params (dict or None) – Dictionary of query parameters, likely provided as part of a request. Defaults to an empty dict.

Returns:

None if successful.

Raises:

• ResourceNotFoundError – If no resource can be found at the provided path.

• BadRequestError – Invalid filters, sorts, fields, embeds, offset, or limit as defined in the provided query params will result in a raised exception if strict is set to True.

• MethodNotAllowedError – If deleting the resource at the supplied path is not allowed.

Permissions

drowsy.permissions

Classes for building permissions into an API.

class drowsy.permissions.OpPermissionsABC(**kwargs)

Inherit from this class to implement permissions logic.

__init__(**kwargs)

Stores any given kwargs on the permissions object.

check(operation, obj_data, instance=None, context=None, field=None, **kwargs)

Check if the given action is allowed.

Parameters:

• operation (str) – Action type. Options include "add", "remove", "create", and "replace” for collections, and "set" may be used as an alias for "add" in single object nested situations. Any actions that are part of custom defined field types will also need to be handled.

• obj_data – The user supplied data. Likely a dictionary for a child object.

• instance – An unmodified instance of the object with data yet to be loaded into it.

• context – The context of the current action. May include info such as the current user.

• field – The Marshmallow field that triggered the permission check.

• kwargs – Any additional arguments that may be used for checking permissions.

Returns:

True if no error is raised.

Return type:

bool

class drowsy.permissions.AllowAllOpPermissions(**kwargs)

Allows any and all actions on a relationship.

check(operation, obj_data, instance=None, context=None, field=None, **kwargs)

Check if the given action is allowed.

Always returns True.

Parameters:

• operation (str) – Action type. Options include "add", "remove", "create", and "replace” for collections, and "set" may be used as an alias for "add" in single object nested situations. Any actions that are part of custom defined field types will also need to be handled.

• obj_data – The user supplied data. Likely a dictionary for a child object.

• instance – An unmodified instance of the object with data yet to be loaded into it.

• context – The context of the current action. May include info such as the current user.

• field – The Marshmallow field that triggered the permission check.

• kwargs – Any additional arguments that may be used for checking permissions.

Returns:

True if no error is raised.

Return type:

bool

class drowsy.permissions.DisallowAllOpPermissions(**kwargs)

Disallows any and all actions on a relationship.

check(operation, obj_data, instance=None, context=None, field=None, **kwargs)

Check if the given action is allowed.

Always returns False.

Parameters:

• operation (str) – Action type. Options include "add", "remove", "create", and "replace” for collections, and "set" may be used as an alias for "add" in single object nested situations. Any actions that are part of custom defined field types will also need to be handled.

• obj_data – The user supplied data. Likely a dictionary for a child object.

• instance – An unmodified instance of the object with data yet to be loaded into it.

• context – The context of the current action. May include info such as the current user.

• field – The Marshmallow field that triggered the permission check.

• kwargs – Any additional arguments that may be used for checking permissions.

Returns:

True if no error is raised.

Return type:

bool

Resource Class Registry

Enables a registry of Resource classes.

This allows for string lookup of resources, making it easier to reference them dynamically and avoid circular dependencies.

Warning

This module is treated as private API. Users should not need to use this module directly.

This module was taken directly from Marshmallow. The only core difference is that it serves as a registry of resources rather than schemas. Please see below for the appropriate Marshmallow attribution.

Copyright 2015 Steven Loria

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

drowsy.resource_class_registry.register(classname, cls)

Add a class to the registry of resource classes.

When a class is registered, an entry for both its class name and its full, module-qualified path are added to the registry.

Example:

class MyClass:
    pass

register('MyClass', MyClass)
# Registry:
# {
#   'MyClass': [path.to.MyClass],
#   'path.to.MyClass': [path.to.MyClass],
# }

Parameters:

• classname (str) – Name of the class to be registered.

• cls – The class to be registered.

drowsy.resource_class_registry.get_class(classname, all=False)

Retrieve a class from the registry.

Parameters:

• classname (str) – Name of the class to be retrieved.

• all (bool) – If True, return all classes registered using the given class name.

Raise:

RegistryError if the class cannot be found or if there are multiple entries for the given class name and all is not True.

Returns:

The class matching the name provided if previously registered, or potentially a list of classes if all is True.

Utilities

drowsy.utils

Utility functions for Drowsy.

drowsy.utils.get_error_message(error_messages, key, gettext=None, **kwargs)

Get an error message based on a key name.

If the error message is a callable, kwargs are passed to that callable.

Assuming the resulting error message is a string, self.gettext will be passed that string along with any kwargs to potentially translate and fill in any template variables.

Parameters:

• error_messages (dict) – A dictionary of string or callable errors mapped to key names.

• key (str) – Key used to access the error messages dict.

• gettext (callable or None) – Optional callable that may be used to translate any error messages.

• kwargs (dict) – Any additional arguments that may be passed to a callable error message, or used to translate and/or format an error message string.

Raises:

KeyError – If the error_messages dict does not contain the provided key.

Returns:

An error message with the supplied kwargs injected.

Return type:

str

drowsy.utils.get_field_by_data_key(schema, data_key)

Helper method to get a field from schema by data_key name.

Parameters:

• schema (Schema) – Instantiated schema.

• data_key (str) – Name as the field as it was serialized.

Returns:

The schema field if found, None otherwise.

Return type:

Field or None

Exceptions

drowsy.exc

Exceptions for Drowsy.

exception drowsy.exc.DrowsyError(code, message, **kwargs)

Exception that contains a simple message attribute.

__init__(code, message, **kwargs)

Initializes a new error.

Parameters:

• code (str) – Error code for easier lookup.

• message (str) – Description of the error.

• kwargs (dict) – Any additional arguments may be stored along with the message as well.

exception drowsy.exc.UnprocessableEntityError(code, message, errors, **kwargs)

Exception for when provided data is unable to be deserialized.

__init__(code, message, errors, **kwargs)

Initializes a new unprocessable entity error.

Parameters:

• code (str) – Error code for easier lookup.

• message (str) – Description of the error.

• errors (dict) – A field by field breakdown of errors.

• kwargs (dict) – Any additional arguments may be stored along with the message and errors as well.

exception drowsy.exc.PermissionDeniedError(code, message, errors, **kwargs)

Exception for when provided data is unable to be deserialized.

__init__(code, message, errors, **kwargs)

Initializes a new permission denied error.

Parameters:

• code (str) – Error code for easier lookup.

• message (str) – Description of the error.

• errors (dict) – A field by field breakdown of errors.

• kwargs (dict) – Any additional arguments may be stored along with the message and errors as well.

exception drowsy.exc.BadRequestError(code, message, **kwargs)

Exception for when a request is unable to be processed.

exception drowsy.exc.MethodNotAllowedError(code, message, **kwargs)

Error for when a request is made with an unsupported method.

exception drowsy.exc.ResourceNotFoundError(code, message, **kwargs)

Exception for when a requested resource cannot be found.

exception drowsy.exc.ParseError(code, message, **kwargs)

Generic exception class for parsing errors.

exception drowsy.exc.OffsetLimitParseError(code, message, **kwargs)

Generic exception class for offset or limit parsing errors.

exception drowsy.exc.FilterParseError(code, message, **kwargs)

Generic exception class for filter parsing errors.

exception drowsy.exc.PermissionValidationError(message: str | list | dict, field_name: str = '_schema', data: Mapping[str, Any] | Iterable[Mapping[str, Any]] | None = None, valid_data: list[Any] | dict[str, Any] | None = None, **kwargs)

Generic schema exception class for an unauthorized action.