restfulchemy Package

restfulchemy Package

restfulchemy.__init__

A set of utility functions for working with SQLAlchemy.

copyright:(c) 2015 by Nicholas Repole and contributors. See AUTHORS for more details.
license:MIT - See LICENSE for more details.
exception restfulchemy.__init__.AlchemyUpdateException[source]

Bases: exceptions.Exception

Generic exception class for invalid updates.

restfulchemy.__init__.apply_offset_and_limit(query, query_params, page=None, page_max_size=None)[source]

Applies offset and limit to the query if appropriate.

Parameters:
  • query – Any desired filters must already have been applied.
  • query_params – A dictionary in which “$limit”, “~limit”, “$offset”, or “~offset” may be supplied.
  • page – If provided, 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.
  • page_max_size – 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. If a query_param limit of a higher number is provided, it will be ignored.
restfulchemy.__init__.apply_order_by(query, RecordClass, query_params)[source]

Given query_params that contain an order_by key, apply sorts.

Format for order_by is attr_name~ASC-other_attr~DESC, where hyphens separate order_by statements, and tildes are used to denote direction.

restfulchemy.__init__.create_resource(db_session, RecordClass, params, whitelist=None, add_to_session=True, stack_size_limit=None)[source]

Create a new instance of a SQLAlchemy object.

See update_object() for parameter details. The only difference between this function and update_object() is a new object is created and returned rather than being supplied.

restfulchemy.__init__.get_alchemy_primary_keys(RecordClass)[source]

Get a list of primary key fields for a SQLAlchemy class.

restfulchemy.__init__.get_class_attributes(RecordClass, attr_name)[source]

Get info about each attr given a dot notation attr name.

restfulchemy.__init__.get_full_attr_name(attr_name_stack, short_attr_name=None)[source]

Join the attr_name_stack to get a full attribute name.

restfulchemy.__init__.get_primary_key_dict(id_string)[source]

Turns “$id:some_field=6” into {“some_field”: 6}.

restfulchemy.__init__.get_resource(db_session, RecordClass, query_params, whitelist=None, stack_size_limit=None)[source]

Get a single instance of a SQLAlchemy object.

See get_resources_query() and apply_order_by() for details on the parameters. The main difference between this function and get_resources() is this one calls first() on the query object rather than all().

restfulchemy.__init__.get_resources(db_session, RecordClass, query_params, whitelist=None, page=None, page_max_size=None, stack_size_limit=None)[source]

Get a list of SQLAlchemy objects.

See get_resources_query() and apply_order_by() for details on the parameters.

restfulchemy.__init__.get_resources_query(db_session, RecordClass, query_params, whitelist=None, stack_size_limit=None)[source]

Get a query object with filters from query_params applied.

Parameters:
  • db_session – A SQLAlchemy database session or query session.
  • RecordClass – The SQLAlchemy model class you want to query.
  • query_params – A dictionary of query parameters that came in with a web request. In Flask, you probably want to pass in request.values.to_dict(). In CherryPy you’d pass in request.params. Any top level parameters will be considered part of an $and statement. So example.com?name=Nick&age=25 would query for a person who’s name is Nick and is 25. You can also have a more complex $query argument that contains a json dumped string or dictionary of potentially more complex query parameters. These parameters follow the format specified in MQLAlchemy, similar to a MongoDB query. See mqlalchemy.apply_mql_filters() for more info.
  • whitelist – A list of object attributes that are acceptable to query. See mqlalchemy.apply_mql_filters() for more info.
  • stack_size_limit – A way of limiting how complex of a query is allowable. See mqlalchemy.apply_mql_filters() for more info.
restfulchemy.__init__.parse_filters(RecordClass, query_params, only_parse_complex=False)[source]

Convert request params into MQLAlchemy friendly search.

restfulchemy.__init__.update_resource(db_session, instance, params, whitelist=None, add_to_session=True, stack_size_limit=None)[source]

Update a SQLAlchemy model instance based on query params.

To update a relationship item, regardless of if the relationship uses a list or not, you must use $id notation:

update_resource(
    db_session,
    album,
    {"artist.$id:artist_id=1.name": "Nas"}
    whitelist=["artist.name"])

This would update the provided album’s artist name to “Nas”. Note that this probably isn’t what you want to do, but rather want to set the album’s artist relation to a different artist object. To do this, you would write:

update_resource(
    db_session,
    album,
    {"artist.$id:artist_id=5.$add": True}
    whitelist=["artist.$add", "artist.$remove"])

The “artist.$add” allows setting the album.artist relationship to a artist that already exists in the database. For a relationship that doesn’t use a list, setting the relation to a different object implicitly results in the old object (if one exists) to be removed from the parent, thus we must include “artist.$remove” in the whitelist. You may also use $set instead to enable both $add and $remove for a non list using relationship.

Relationships that use lists work slightly differently, as including an $id that isn’t already in the list will simply result in adding that object, but won’t result in any others being removed.

To explicitly remove an object from a relation:

update_resource(
    db_session,
    album,
    {"artist.$id:artist_id=1.$remove": True}
    whitelist=["artist.$remove"])

In this case, since the artist relationship does not use a list, album.artist would simply be set to None. If the relationship was a list, the artist with a matching $id would simply be removed from the relationship list.

Parameters:
  • params – A dictionary of dot notation attribute names that are to be updated. friends.$new0.user_id would denote creating a new friend in the friends relationship and assigning the user_id attribute. Any other params that start with friend.$new0 would denote an attribute assignment on that same new object.
  • whitelist –

    A whitelist of attributes that are allowed to be set.

    Special rules for relationships, using Playlist as a reference:

    • tracks.$create
      Allows the creation of a new track (using the above mentioned $new notation). Whitelist must also include $add or (for non list using relationships) $set to allow this item to actually be added to the relationship.
    • tracks.$add
      Enables appending to the relationship a pre-existing track. So if your update_params includes a field “tracks.$id:track_id=5.$add” set equal to a True expression, and a track with id equal to 5 already exists, that track will be added to album.tracks.
    • tracks.$remove
      Enables removing an object from a relationship. “tracks.$id:track_id=5.$remove” set equal to a True expression will result in removing the track with id equal to 5 from this relationship.
    • tracks
      If you include simply the name of the relationship in the whitelist, $create, $remove, $add, and $set are all enabled.
  • add_to_session – Defaults to True, determines whether newly created objects are automatically added to the database session.

_compat Module

restfulchemy._compat

Python2/Python3 support helper library.

copyright:(c) 2015 by Nicholas Repole and contributors. See AUTHORS for more details.
license:MIT - See LICENSE for more details.