cookbase.validation¶

Module contents¶

The cookbase.validation package provides tools for parsing and validating Cookbase Data Model (CBDM) objects.

Submodules¶

cookbase.validation.cba¶

cookbase.validation.cba.unroll(cba: Dict[str, Any]) → Dict[str, Any][source]¶

Returns an augmented Cookbase Appliance (CBA) by retrieving its parent CBAs recursively.

If the CBA has a parent, unroll() is recursively called returning an augmented structure with inherited data on functions, materials, and the id field updated to a list that include all the parent ids; if the CBA has no parents, it is returned with no modifications.

Parameters:	cba (dict[str, Any]) – A CBA to be unrolled
Returns:	An augmented CBA
Return type:	dict[str, Any]
Raises:	KeyError – An attempt on accessing a key in the provided or any parent CBA failed

cookbase.validation.cbr¶

class cookbase.validation.cbr.ValidationResult(schema_validated: bool = True, rules_results: Dict[str, cookbase.validation.rules.AppliedRuleResult] = NOTHING, cbrgraph: Optional[cookbase.graph.cbrgraph.CBRGraph] = None, storing_result: Optional[cookbase.db.handler.InsertCBRResult] = None)[source]¶

Bases: object

A class used to handle the results produced by the Validator.validate() method.

Parameters:

schema_validated (bool) – A flag indicating if the evaluated Cookbase Recipe (CBR) was valid against the given CBR Schema, defaults to True
rules_results (dict[str, rules.AppliedRuleResult]) – A dictionary whose keys are the names of the functions implementing the rules that were applied for evaluation, and the values are the rules.AppliedRuleResult objects obtained after each rule application
cbrgraph (CBRGraph, optional) – An object containing the Cookbase Recipe Graph (CBRGraph) data generated during validation
storing_result (handler.InsertCBRResult, optional) –

is_valid(strict: bool = True) → bool[source]¶

Indicates whether the validation process is evaluated as valid or not.

The strict flag indicates the policy for the evaluation of the rule application results: if set to True (the default), any registered warning or error from any rule will cause the evaluation invalid; if set to False, only registering errors –disregarding on warnings– will result in a negative evaluation.

Parameters:	strict (bool, optional) – A flag indicating the validation policy, defaults to `True`
Returns:	A value indicating whether the validation resulted successful (returning `True`) or unsuccessful (returning `False`)
Return type:	bool

class cookbase.validation.cbr.Validator(schema_url: str = 'http://landarltracker.com/schemas/cbr/cbr.json')[source]¶

Bases: object

A class that performs validation and Cookbase Recipe Graph (CBRGraph) construction of recipes in Cookbase Recipe (CBR) format.

Parameters:	schema_url (str, optional) – A URL to where the CBR Schema is to be retrieved, defaults to `cookbase.validation.globals.Definitions.cbr_schema_url`
Raises:	Exception – The HTTP response from requesting the CBR Schema is empty
Variables:	schema (dict[str, Any]) – The CBR schema

apply_validation_rules(cbr: Dict[str, Any]) → cookbase.validation.cbr.ValidationResult[source]¶

Validates a CBR against the set of definition rules.

Validation rules defined in cookbase.validation.rules are applied sequentially to ensure that the recipe document satisfies the CBR definition.

Parameters:	cbr (dict[str, Any]) – The CBR to be validated
Returns:	The results from applying the set of validation rules
Return type:	ValidationResult

validate(cbr: Dict[str, Any], store: bool = False, strict: bool = True) → cookbase.validation.cbr.ValidationResult[source]¶

Main function of the class, it performs the validation of a CBR and builds the CBRGraph.

The validation process is implemented in two stages: firstly, a JSON Schema validation is performed, and, secondly, validating rules are sequentially applied to ensure that the recipe document satisfies the CBR definition.

Parameters:	cbr (dict[str, Any]) – The CBR to be validated store (bool, optional) – A flag indicating whether the validated CBR and CBRGraph should be stored in database, defaults to `False` strict (bool, optional) – A flag indicating the validation policy, defaults to `True`
Returns:	The results from applying the set of validation rules
Return type:	ValidationResult

cookbase.validation.exceptions¶

exception cookbase.validation.exceptions.ApplianceNotAvailableError(appliance: str, process: str)[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when trying to use an unavailable appliance.

Variables:	appliance (str) – CBR Appliance identifier process (str) – CBR Process identifier

exception cookbase.validation.exceptions.CBRValidationException[source]¶

Bases: Exception

Base class for Cookbase Recipe (CBR) validation errors.

exception cookbase.validation.exceptions.IngredientsNotUsedError(foodstuffs: Set[str])[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when remaining CBR Ingredients are found after end of preparation flow.

Variables:	foodstuffs (set[str]) – A set of CBR Ingredient identifiers

exception cookbase.validation.exceptions.NecessaryAppliancesError(process: str)[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when the conditions of necessary CBR Appliances are not met.

Variables:	process (str) – CBR Process identifier

exception cookbase.validation.exceptions.NoApplianceUsedAfterError(process: str)[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when there is no CBR Appliance remaining used after a given CBR Process.

Variables:	process (str) – CBR Process identifier

exception cookbase.validation.exceptions.PreparationFlowError[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when the CBR does not fulfill the preparation flow requirements.

exception cookbase.validation.exceptions.PreparationKeyError(key: str)[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when an identifier is not found in the JSON document.

Variables:	key (str) – The identifier attempted to access

exception cookbase.validation.exceptions.StorageError[source]¶

Bases: cookbase.validation.exceptions.CBRValidationException

Raised when there was an error storing the CBR and/or the Cookbase Recipe Graph (CBRGraph) in the database.

cookbase.validation.globals¶

class cookbase.validation.globals.Definitions[source]¶

Bases: object

Class that provides global definitions for the Cookbase platform.

Variables:

schema_base_url (str) – The base URL to the Cookbase Data Model (CBDM) Schemas
definitions_url (str) – The URL to the CBDM common definitions document
cbr_schema_url (str) – The URL to the Cookbase Recipe (CBR) Schema
materials (list[str]) – The list of Cookbase Appliance (CBA) materials
appliance_functions (list[str]) – The list of CBA functions
foodstuff_keywords (list[str]) – The list of Cookbase Process (CBP) foodstuff keywords

appliance_functions = ['bakes', 'contains', 'contains to bake', 'contains to boil', 'contains to cook', 'cooks', 'covers', 'cuts', 'heats', 'measures', 'props', 'protects', 'scoops', 'scrapes', 'stirs', 'tableware', 'transfers']¶

cbr_schema_url = 'http://landarltracker.com/schemas/cbr/cbr.json'¶

definitions_url = 'http://landarltracker.com/schemas/cb-common-definitions.json'¶

foodstuff_keywords = ['foodstuff', 'foodstuffsList', 'base', 'onTop', 'sauce', 'liquid', 'toSoak']¶

materials = ['ceramic', 'fabric', 'glass', 'metal', 'metal:steel', 'metal:iron', 'polymer', 'polymer:pe', 'polymer:teflon', 'polymer:silicone', 'stone', 'stone:marble', 'wood']¶

schema_base_url = 'http://landarltracker.com/schemas'¶

cookbase.validation.rules¶

A module implementing the validation rules required by cookbase.validation.cbr.Validator, following the premises exposed in the Assumptions and conditions section of this documentation.

The validation rules are subdivided in two classes, Semantics and Graph. Although the different methods provide a certainly modular approach to the application of the validation rules, they are implemented from a problem optimization perspective, and attending to this priority in some cases several tests are collapsed into a single function.

class cookbase.validation.rules.AppliedRuleResult(errors: List[str] = NOTHING, warnings: List[str] = NOTHING)[source]¶

Bases: object

A class containing the results of applying a validation rule defined in the cookbase.validation.rules module.

Parameters:	errors (list[str], optional) – Field containing all the errors produced during the application of a rule, defaults to an empty list `[]` warnings (list[str], optional) – Field containing all the warnings produced during the application of a rule, defaults to an empty list `[]`

has_passed(strict: bool = True) → bool[source]¶

Indicates whether the application of a rule resulted successful or not.

The strict flag indicates the policy for the evaluation of the rule application results: if set to True (the default), any registered warning or error will cause the evaluation not to be passed; if set to False, only registering errors –disregarding on warnings– will result in a negative evaluation.

Parameters:	strict (bool, optional) – A flag indicating the policy for the results evaluation, defaults to `True`
Returns:	A value indicating whether the application of a rule resulted successful (returning `True`) or unsuccessful (returning `False`)
Return type:	bool

include_result(result: cookbase.validation.rules.AppliedRuleResult)[source]¶

class cookbase.validation.rules.Graph[source]¶

Bases: object

A class that holds the set of methods that impose graph consistency conditions in order to validate a Cookbase Recipe (CBR) analyzing its corresponding Cookbase Recipe Graph (CBRGraph).

All messages notifying validation errors or warnings are passed to the cookbase.logging.logger instance.

static appliances_not_in_conflict(graph: cookbase.graph.cbrgraph.CBRGraph) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks whether there are not any CBR Appliance in a given CBRGraph that may be in conflict, that is, potentially used by two or more concurrent CBR Processes at the same time.

The following messages will be logged if the corresponding problems are found:

Warning: A CBR Appliance is required by more than one concurrent CBR Process in the analyzed CBR.

Parameters:	graph (cookbase.graph.cbrgraph.CBRGraph) – The CBRGraph generated from the CBR to be validated
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static ingredients_used_exactly_once(graph: cookbase.graph.cbrgraph.CBRGraph) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks that every CBR Ingredient in a given CBRGraph is directly used by a CBR Process exactly once.

The following messages will be logged if the corresponding problems are found:

Error: A given CBR Ingredient is used more than once in the preparation section of the analyzed CBR.
Warning: A given CBR Ingredient is not used in the preparation section of the analyzed CBR.

Parameters:	graph (cookbase.graph.cbrgraph.CBRGraph) – The CBRGraph generated from the CBR to be validated
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static single_final_process(graph: cookbase.graph.cbrgraph.CBRGraph) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks if there is only one CBR Process in a given CBRGraph acting as the end process.

The following messages will be logged if the corresponding problems are found:

Error: There are more than one ending CBR Process in the analyzed CBR.

Parameters:	graph (cookbase.graph.cbrgraph.CBRGraph) – The CBRGraph generated from the CBR to be validated
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

class cookbase.validation.rules.Semantics[source]¶

Bases: object

A class that holds the set of methods that impose semantic conditions in order to validate a Cookbase Recipe (CBR).

All messages notifying validation errors or warnings are passed to the cookbase.logging.logger instance.

static appliance_is_valid(appliance: Dict[str, Any], cba: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks whether a CBR Appliance is valid according to a given Cookbase Appliance (CBA).

The following messages will be logged if the corresponding problems are found:

Warning: The given CBR Appliance’s name language code is not found in the CBA definition.
Warning: The given CBR Appliance’s name does not match any name available from the CBA definition.

Parameters:	appliance (dict[str, Any]) – A dictionary containing a CBR Appliance from the CBR to be validated cba (dict[str, Any]) – A dictionary containing the CBA referred by the CBR Appliance contained in appliance
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static cbas_satisfy_cbp(cbas: List[Dict[str, Any]], cbp: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks if a set of CBAs satisfy at least one of the condition clauses provided by the data.validation.conditions.requiredAppliances property of a given CBP.

The provided CBAs are assumed to exist in the database.

Parameters:	cbas (list[dict[str, Any]]) – A list containing the CBAs to be verified cbp (dict[str, Any]) – The dictionary containing the CBP whose conditions clauses are to be checked for satisfaction
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static foodstuff_and_appliance_references_are_consistent(ingredients: Dict[str, Any], appliances: Dict[str, Any], processes: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks for the consistency of a CBR on the scope of its CBR Ingredient, CBR Appliance and CBR Process references.

The function checks if:

All foodstuff and appliance references appearing in the CBR Processes exist in the context of the given CBR (which may either be references to CBR Ingredients, CBR Appliances or CBR Processes, as explained in the Cookbase Data Model (CBDM) documentation on the preparation section of a CBR).
There are no unreferenced CBR Ingredients or CBR Appliances in the given CBR.

The following messages will be logged if the corresponding problems are found:

Error: There is no CBR Ingredient nor CBR Process matching a foodstuff reference from a CBR Process in the given CBR.
Error: There is no CBR Appliance matching an appliance reference from a CBR Process in the given CBR.
Warning: A CBR Ingredient is not referenced by any CBR Process in the given CBR.
Warning: A CBR Appliance is not referenced by any CBR Process in the given CBR.

Parameters:	ingredients (dict[str, Any]) – The dictionary containing the `ingredients` property from the CBR to be validated, which holds a set of CBR Ingredients appliances – The dictionary containing the `appliances` property from the CBR to be validated, which holds a set of CBR Appliances processes (dict[str, Any]) – The dictionary containing the `preparation` property from the CBR to be validated, which holds a set of CBR Processes
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static ingredients_are_valid(ingredients: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks whether the CBR Ingredients present in a CBR are correct and their respective CBIs exist in the database.

The following messages will be logged if the corresponding problems are found:

Error: A given CBI is not found in the database by its identifier.
Warning: A given CBR Ingredient’s name does not match any name available from the its referred CBI definition.

Parameters:	ingredients (dict[str, Any]) – The dictionary containing the `ingredients` property from the CBR to be validated, which holds a set of CBR Ingredients
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static process_is_valid(process: Dict[str, Any], cbp: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks whether a CBR Process is valid according to a given Cookbase Process (CBP).

The following messages will be logged if the corresponding problems are found:

Warning: The given CBR Process’s name language code is not found in the CBP definition.
Warning: The given CBR Process’s name does not match any name available from the CBP definition.

Parameters:	process (dict[str, Any]) – A dictionary containing a CBR Process from the CBR to be validated cbp (dict[str, Any]) – A dictionary containing the CBP referred by the CBR Process contained in process
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static processes_and_appliances_are_valid_and_processes_requirements_met(appliances: Dict[str, Any], processes: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks correctness and consistency on the CBR Appliances and CBR Processes present in a CBR.

The function checks if:

All CBR Appliances and CBR Processes are correct and their respective CBAs and CBPs exist in the database.
All CBR Processes find there appliance requirements met.

The following messages will be logged if the corresponding problems are found:

Error: A given CBA is not found in the database by its identifier.
Error: A given CBP is not found in the database by its identifier.
Error: The appliance requirements of a given CBR Process are not met.
Messages from the appliance_is_valid() and process_is_valid() calls.

Parameters:	appliances (dict[str, Any]) – The dictionary containing the `appliances` property from the CBR to be validated, which holds a set of CBR Appliances processes (dict[str, Any]) – The dictionary containing the `preparation` property from the CBR to be validated, which holds a set of CBR Processes
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult

static processes_are_valid(processes: Dict[str, Any]) → cookbase.validation.rules.AppliedRuleResult[source]¶

Checks whether the CBR Processes present in a CBR are correct and their respective CBPs exist in the database.

The following messages will be logged if the corresponding problems are found:

Error: A given CBP is not found in the database by its identifier.
Messages from the process_is_valid() calls.

Note

Do not call if processes_and_appliances_are_valid_and_processes_requirements_met() is executed, as this test will be redundant.

Parameters:	processes (dict[str, Any]) – The dictionary containing the `preparation` property from the CBR to be validated, which holds a set of CBR Processes
Returns:	An `AppliedRuleResult` object containing the errors and warnings registered during rule application
Return type:	AppliedRuleResult