API — Recipe 0.1.0 documentation

# 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)

  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`()

    Return a (potentially cached) list of result objects.

  `as_table`(name=None)

    Return an alias to a table

  `dimensions`(*dimensions)

    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)

    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`()

    Return the first element on the result

  `limit`(limit)

    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)

    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)

    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`()

    Return the first element on the result

  `order_by`(*order_bys)

    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`()

    Generates a query using the ingredients supplied by the recipe.

    Returns: | A SQLAlchemy query

  `shelf`(shelf=None)

    Defines a shelf to use for this recipe

  `subquery`(name=None)

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

  `table`()

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

  `to_sql`()

    A string representation of the SQL this recipe will generate.

## Shelf Object

class `recipe.` `Shelf`(*args, **kwargs)

  Holds ingredients used by a recipe

  Args:

  Returns: | A Shelf object

  `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`()

    Returns a new dict with keys from iterable and values equal to value.

  `ingredients`()

    Return the ingredients in this shelf in a deterministic order

  `items`() → a set-like object providing a view on D's items
  `keys`() → a set-like object providing a view on 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 is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then 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`() → an object providing a view on D's values

class `recipe.` `AutomaticShelf`(table, *args, **kwargs)
  `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`()

    Returns a new dict with keys from iterable and values equal to value.

  `ingredients`()

    Return the ingredients in this shelf in a deterministic order

  `items`() → a set-like object providing a view on D's items
  `keys`() → a set-like object providing a view on 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 is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then 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`() → an object providing a view on D's values

## Ingredients

class `recipe.` `Ingredient`(**kwargs)

  Ingredients combine to make a SQLAlchemy query.

  `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

class `recipe.` `Dimension`(expression, **kwargs)

  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)

  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`

  You can’t build an ingredient this way.

class `recipe.` `BadRecipe`

  You can’t build a recipe this way.

Now, go start some Recipe Development.