API

This part of the documentation covers all the interfaces of Recipe.

Recipe Object

class recipe.Recipe(shelf=None, metrics=None, dimensions=None, filters=None, order_by=None, session=None, extension_classes=None, dynamic_extensions=None)[source]

A tool for getting data.

Parameters:
  • shelf (Shelf) – A shelf to use for shared metrics
  • metrics (list of str) – A list of metrics to use from the shelf. These can also be Metric objects.
  • dimensions (list of str) – A list of dimensions to use from the shelf. These can also be Dimension objects.
  • filters (list of str) – A list of filters to use from the shelf. These can also be Filter objects.
  • order_by (list of str) – A list of dimension or metric keys from the shelf to use for ordering. If prefixed by ‘-‘ the ordering will be descending.
  • session (Session)
  • extension_classes (list of RecipeExtension) – Extensions to apply to this recipe.
Returns:

A Recipe object.

all()[source]

Return a (potentially cached) list of result objects.

as_table(name=None)[source]

Return an alias to a table

dimensions(*dimensions)[source]

Add a list of Dimension ingredients to the query. These can either be Dimension objects or strings representing dimensions on the shelf.

The Dimension expression will be added to the query’s select statement and to the group_by.

Parameters:dimensions (list) – Dimensions to add to the recipe. Dimensions can either be keys on the shelf or Dimension objects
dirty

The recipe is dirty if it is flagged dirty or any extensions are flagged dirty

filters(*filters)[source]

Add a list of Filter ingredients to the query. These can either be Filter objects or strings representing filters on the service’s shelf. .filters() are additive, calling .filters() more than once will add to the list of filters being used by the recipe.

The Filter expression will be added to the query’s where clause

Parameters:filters (list) – Filters to add to the recipe. Filters can either be keys on the shelf or Filter objects
first()[source]

Return the first element on the result

limit(limit)[source]

Limit the number of rows returned from the database.

Parameters:limit (int) – The number of rows to return in the recipe. 0 will return all rows.
metrics(*metrics)[source]

Add a list of Metric ingredients to the query. These can either be Metric objects or strings representing metrics on the shelf.

The Metric expression will be added to the query’s select statement. The metric value is a property of each row of the result.

Parameters:metrics (list) – Metrics to add to the recipe. Metrics can either be keys on the shelf or Metric objects
offset(offset)[source]

Offset a number of rows before returning rows from the database.

Parameters:offset (int) – The number of rows to offset in the recipe. 0 will return from the first available row
one()[source]

Return the first element on the result

order_by(*order_bys)[source]

Add a list of ingredients to order by to the query. These can either be Dimension or Metric objects or strings representing order_bys on the shelf.

The Order_by expression will be added to the query’s order_by statement

Parameters:order_bys (list) – Order_bys to add to the recipe. Order_bys can either be keys on the shelf or Dimension or Metric objects. If the key is prefixed by “-” the ordering will be descending.
query()[source]

Generates a query using the ingredients supplied by the recipe.

Returns:A SQLAlchemy query
shelf(shelf=None)[source]

Defines a shelf to use for this recipe

subquery(name=None)[source]

The recipe’s query as a subquery suitable for use in joins or other queries.

table()[source]

A convenience method to determine the table the query is selecting from

to_sql()[source]

A string representation of the SQL this recipe will generate.

Shelf Object

class recipe.Shelf(*args, **kwargs)[source]

Holds ingredients used by a recipe

Args:

Returns:A Shelf object
brew_query_parts()[source]

Make columns, group_bys, filters, havings

clear() → None. Remove all items from D.
copy() → a shallow copy of D
dimension_ids

Return the Dimensions on this shelf in the order in which they were used.

enchant(list, cache_context=None)[source]

Add any calculated values to each row of a resultset generating a new namedtuple

Parameters:
  • list – a list of row results
  • cache_context – optional extra context for caching
Returns:

a list with ingredient.cauldron_extras added for all ingredients

find(obj, filter_to_class=<class 'recipe.ingredients.Ingredient'>, constructor=None)[source]

Find an Ingredient, optionally using the shelf.

Parameters:
  • obj – A string or Ingredient
  • filter_to_class – The Ingredient subclass that obj must be an instance of
  • constructor – An optional callable for building Ingredients from obj
Returns:

An Ingredient of subclass filter_to_class

fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

has_key(k) → True if D has a key k, else False
ingredients()[source]

Return the ingredients in this shelf in a deterministic order

items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
metric_ids

Return the Metrics on this shelf in the order in which they were used.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → list of D's values
viewitems() → a set-like object providing a view on D's items
viewkeys() → a set-like object providing a view on D's keys
viewvalues() → an object providing a view on D's values
class recipe.AutomaticShelf(table, *args, **kwargs)[source]
brew_query_parts()

Make columns, group_bys, filters, havings

clear() → None. Remove all items from D.
copy() → a shallow copy of D
dimension_ids

Return the Dimensions on this shelf in the order in which they were used.

enchant(list, cache_context=None)

Add any calculated values to each row of a resultset generating a new namedtuple

Parameters:
  • list – a list of row results
  • cache_context – optional extra context for caching
Returns:

a list with ingredient.cauldron_extras added for all ingredients

find(obj, filter_to_class=<class 'recipe.ingredients.Ingredient'>, constructor=None)

Find an Ingredient, optionally using the shelf.

Parameters:
  • obj – A string or Ingredient
  • filter_to_class – The Ingredient subclass that obj must be an instance of
  • constructor – An optional callable for building Ingredients from obj
Returns:

An Ingredient of subclass filter_to_class

fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

has_key(k) → True if D has a key k, else False
ingredients()

Return the ingredients in this shelf in a deterministic order

items() → list of D's (key, value) pairs, as 2-tuples
iteritems() → an iterator over the (key, value) items of D
iterkeys() → an iterator over the keys of D
itervalues() → an iterator over the values of D
keys() → list of D's keys
metric_ids

Return the Metrics on this shelf in the order in which they were used.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → list of D's values
viewitems() → a set-like object providing a view on D's items
viewkeys() → a set-like object providing a view on D's keys
viewvalues() → an object providing a view on D's values

Ingredients

class recipe.Ingredient(**kwargs)[source]

Ingredients combine to make a SQLAlchemy query.

build_filter(value, operator=None)[source]

Builds a filter based on a supplied value and optional operator. If no operator is supplied an in filter will be used for a list and a eq filter if we get a scalar value

Parameters:
  • value (object) – The value to use in the filter
  • operator (str) – An operator to override the default interaction
cauldron_extras

Yield extra tuples containing a field name and a callable that takes a row

expression

An accessor for the sqlalchemy expression representing this Ingredient

make_column_suffixes()[source]

Make sure we have the right column suffixes. These will be appended to id when generating the query.

query_columns

Yield labeled columns to be used as a select in a query

class recipe.Dimension(expression, **kwargs)[source]

A simple dimension created from a single expression and optional id_expression

build_filter(value, operator=None)

Builds a filter based on a supplied value and optional operator. If no operator is supplied an in filter will be used for a list and a eq filter if we get a scalar value

Parameters:
  • value (object) – The value to use in the filter
  • operator (str) – An operator to override the default interaction
cauldron_extras

Yield extra tuples containing a field name and a callable that takes a row

expression

An accessor for the sqlalchemy expression representing this Ingredient

id_prop

The label of this dimensions id in the query columns

make_column_suffixes()

Make sure we have the right column suffixes. These will be appended to id when generating the query.

query_columns

Yield labeled columns to be used as a select in a query

class recipe.Metric(expression, **kwargs)[source]

A simple metric created from a single expression

build_filter(value, operator=None)

Builds a filter based on a supplied value and optional operator. If no operator is supplied an in filter will be used for a list and a eq filter if we get a scalar value

Parameters:
  • value (object) – The value to use in the filter
  • operator (str) – An operator to override the default interaction
cauldron_extras

Yield extra tuples containing a field name and a callable that takes a row

expression

An accessor for the sqlalchemy expression representing this Ingredient

make_column_suffixes()

Make sure we have the right column suffixes. These will be appended to id when generating the query.

query_columns

Yield labeled columns to be used as a select in a query

Functions

Exceptions

class recipe.BadIngredient[source]

You can’t build an ingredient this way.

class recipe.BadRecipe[source]

You can’t build a recipe this way.

Now, go start some Recipe Development.