gemseo.core.grammars.base_grammar module#

Base class for validating data structures.

class BaseGrammar(name)[source]#

Bases: Mapping[str, Any]

An abstract base class for grammars with a dictionary-like interface.

A grammar considers a certain type of data defined by mandatory and optional names bound to types. A name-type pair is referred to as a grammar element. A grammar can validate a data from these elements.

The names can include any character except the special character namespaces_separator (default: ":")

Warning

A name can be prefixed by a namespace. Never add a namespace by any other means than the method add_namespace().

Notes

Contrary to the standard dictionary, the :meth:.copy method creates a deep copy.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

name (str) -- The name of the grammar.

Raises:

ValueError -- If the name is empty.

add_namespace(name, namespace)[source]#

Add a namespace prefix to an existing grammar element.

For example, the grammar element named "foo" will be renamed to "ns:foo" when using the namespace named ``"ns". ":" is the default value of the special character namespaces_separator.

Parameters:

  • name (str) -- The element name to rename.

  • namespace (str) -- The name of the namespace.

Raises:

ValueError -- If the element already has a namespace prefix.

Return type:

None

Warning

Never add a namespace by any other means than the method add_namespace(), e.g. do not write my_discipline.io.input_grammar.update_from_names(["ns:foo"]), but write instead:

my_discipline.io.input_grammar.update_from_names(["foo"])
my_discipline.io.input_grammar.add_namespace("foo", "ns")``.
clear()[source]#

Empty the grammar.

Return type:

None

copy()#

Create a deep copy.

Returns:

The copy.

Return type:

Self

has_names(names)[source]#

Return whether names are all element names.

Parameters:

names (Iterable[str]) -- The names to check.

Returns:

Whether the names are all element names.

Return type:

bool

rename_element(current_name, new_name)[source]#

Rename an element.

Parameters:

  • current_name (str) -- The current name of the element.

  • new_name (str) -- The new name of the element.

Return type:

None

restrict_to(names)[source]#

Restrict the grammar to the given names.

Parameters:

names (Iterable[str]) -- The names of the elements to restrict the grammar to.

Raises:

KeyError -- If a name is not in the grammar.

Return type:

None

to_simple_grammar()[source]#

Convert the grammar to a SimpleGrammar.

Returns:

A SimpleGrammar version of the current grammar.

Return type:

SimpleGrammar

update(grammar, excluded_names=(), merge=False)[source]#

Update the grammar from another grammar.

If grammar has namespaces, they will be added to the current grammar.

Parameters:

  • grammar (Self) -- The grammar to update from.

  • excluded_names (Iterable[str]) --

    The names of the elements that shall not be updated.

    By default it is set to ().

  • merge (bool) --

    Whether to merge or update the grammar.

    By default it is set to False.

Return type:

None

update_from_data(data, merge=False)[source]#

Update the grammar from name-value pairs.

The updated elements are required.

Parameters:

  • data (Mapping[str, Any]) -- The data from which to get the names and types, typically {element_name: element_value}.

  • merge (bool) --

    Whether to merge or update the grammar.

    By default it is set to False.

Return type:

None

update_from_names(names, merge=False)[source]#

Update the grammar from names.

The updated elements are required and bind the names to NumPy arrays.

Parameters:

  • names (Iterable[str]) -- The names to update from.

  • merge (bool) --

    Whether to merge or update the grammar.

    By default it is set to False.

Return type:

None

update_from_types(names_to_types, merge=False)[source]#

Update the grammar from names bound to types.

The updated elements are required.

Parameters:

  • names_to_types (SimpleGrammarTypes) -- The mapping defining the data names as keys, and data types as values.

  • merge (bool) --

    Whether to merge or update the grammar.

    By default it is set to False.

Return type:

None

validate(data, raise_exception=True)[source]#

Validate data against the grammar.

Parameters:

  • data (Mapping[str, Any]) -- The data to be checked, with a dictionary-like format: {element_name: element_value}.

  • raise_exception (bool) --

    Whether to raise an exception when the validation fails.

    By default it is set to True.

Raises:

InvalidDataError -- If the validation fails and raise_exception is True.

Return type:

None

DATA_CONVERTER_CLASS: ClassVar[str | type[BaseDataConverter[BaseGrammar]]]#

The class or the class name of the data converter.

property data_converter: BaseDataConverter[BaseGrammar]#

The converter of data values to NumPy arrays and vice versa.

property defaults: GrammarProperties#

The mapping from the names to the default values, if any.

property descriptions: GrammarProperties#

The mapping from the names to the descriptions.

from_namespaced: MutableNamespacesMapping#

The mapping from element names with namespace prefix to element names without namespace prefix.

name: str#

The name of the grammar.

property names: KeysView[str]#

The names of the elements.

property names_without_namespace: Iterator[str]#

The names of the elements without namespace prefixes.

property required_names: RequiredNames#

The names of the required elements.

to_namespaced: MutableNamespacesMapping#

The mapping from element names without namespace prefix to element names with namespace prefix.