recipe

Recipe

exception recipe.BadIngredient[source]

Something is wrong with an ingredient

exception recipe.BadRecipe[source]

Something is wrong with a recipe

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

cauldron_extras

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

id_prop

The label of this dimensions id in the query columns

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

Returns the expression value looked up in a lookup dictionary

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

A simple metric created from a single expression

class recipe.DivideMetric(numerator, denominator, **kwargs)[source]

A metric that divides a numerator by a denominator handling several possible error conditions

The default strategy is to add an small value to the denominator Passing ifzero allows you to give a different value if the denominator is zero.

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

A metric that generates the weighted average of a metric by a weight.

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

A metric that calculates a sum of an expression if a condition is true

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

A metric that calculates a sum of an expression if a condition is true

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

A simple filter created from a single expression.

describe()[source]

Stringify this ingredient to help in debugging.

expression

An accessor for the sqlalchemy expression representing this Ingredient

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

A Having that limits results based on an aggregate boolean clause

describe()[source]

Stringify this ingredient to help in debugging.

expression

An accessor for the sqlalchemy expression representing this Ingredient

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.

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

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

ingredients()[source]

Return the ingredients in this shelf in a deterministic order

metric_ids

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