gemseo / core / grammars

json_grammar module

A Grammar based on JSON schema.

Classes:

JSONGrammar(name[, schema_file, schema, ...])

A grammar based on a JSON schema.

Exceptions:

ValidationError

class gemseo.core.grammars.json_grammar.JSONGrammar(name, schema_file=None, schema=None, descriptions=None)[source]

Bases: gemseo.core.grammars.abstract_grammar.AbstractGrammar

A grammar based on a JSON schema.

name

The name of the grammar.

Type

str

schema

The JSON schema.

Type

MutableMappingSchemaBuilder

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

Parameters
  • name – The name to be given to the grammar.

  • schema_file

    The JSON schema file. If None, do not initialize the grammar from a JSON schema file.

    By default it is set to None.

  • schema

    A genson schema to initialize the grammar. If None, do not initialize the grammar from a JSON schema.

    By default it is set to None.

  • descriptions

    The descriptions of the elements, in the form: {element_name: element_meaning}. If None, use the descriptions available in the JSON schema if any.

    By default it is set to None.

Attributes:

OBJECT_FIELD

PROPERTIES_FIELD

REQUIRED_FIELD

TYPES_MAP

TYPE_FIELD

properties_dict

The dictionnary representation of the properties of the schema.

schema_dict

The dictionary representation of the schema.

Methods:

cast_array_to_list(data_dict)

Cast the NumPy arrays to lists for dictionary values.

clear()

Clear the grammar.

get_data_names()

Return the names of the elements.

get_type_from_python_type(python_type)

Return the grammar type that corresponds to a given Python type.

init_from_schema_file(schema_path[, ...])

Set the grammar from a file.

initialize_from_base_dict(typical_data_dict)

Initialize the grammar with types and names from a typical data entry.

initialize_from_data_names(data_names[, ...])

Initialize the grammar from the names and descriptions of the elements.

is_all_data_names_existing(data_names)

Check if the names of the elements are present in the grammar.

is_data_name_existing(data_name)

Check if the name of an element is present in the grammar.

is_required(element_name)

Check if an element is required in the grammar.

is_type_array(data_name)

Check if an element is an array.

load_data(data[, raise_exception])

Load elements values and check their consistency with the grammar.

remove_item(item_name)

Remove an element.

restrict_to(data_names)

Restrict the grammar to the given names.

set_item_value(item_name, item_value)

Set the value of an element.

to_simple_grammar()

Convert to the base SimpleGrammar type.

update_elements([python_typing])

Add or update elements from their names and types.

update_from(input_grammar)

Update the grammar with a second one.

update_from_if_not_in(input_grammar, ...)

Add the elements from a second grammar that are not present in a third one.

update_required_elements(**elements)

Add or update the required elements in the grammar.

write_schema([path])

Write the schema to a file.

OBJECT_FIELD = 'object'
PROPERTIES_FIELD = 'properties'
REQUIRED_FIELD = 'required'
TYPES_MAP = {'array': <class 'numpy.ndarray'>, 'boolean': <class 'bool'>, 'float': <class 'float'>, 'integer': <class 'int'>, 'number': <class 'numbers.Number'>, 'string': <class 'str'>}
TYPE_FIELD = 'type'
classmethod cast_array_to_list(data_dict)[source]

Cast the NumPy arrays to lists for dictionary values.

Parameters

data_dict (Mapping[str, Union[str, float, bool, Sequence[Union[str, float, bool]], numpy.ndarray, numpy.generic, NumPyNestedMappingType]]) – The data mapping.

Returns

The original mapping casted to a dictionary where NumPy arrays have been replaced with lists.

Return type

Mapping[str, Union[str, float, bool, Sequence[Union[str, float, bool]], List[Union[str, float, bool, Sequence[Union[str, float, bool]]]], DictSchemaType]]

clear()[source]

Clear the grammar.

Return type

None

get_data_names()[source]

Return the names of the elements.

Returns

The names of the elements sorted alphabetically.

Return type

List[str]

get_type_from_python_type(python_type)

Return the grammar type that corresponds to a given Python type.

Parameters

python_type (type) – The Python type.

Returns

The equivalent grammar type.

Return type

type

init_from_schema_file(schema_path, descriptions=None)[source]

Set the grammar from a file.

Parameters
  • schema_path (Union[str, pathlib.Path]) – The path to the schema file.

  • descriptions (Optional[Mapping[str, str]]) –

    The descriptions for the elements of the grammar, in the form: {element_name: element_meaning}. If None, use the descriptions from the schema file.

    By default it is set to None.

Raises

FileNotFoundError – If the schema file does not exist.

Return type

None

initialize_from_base_dict(typical_data_dict, description_dict=None)[source]

Initialize the grammar with types and names from a typical data entry.

The keys of the typical_data_dict are the names of the elements. The types of the values of the typical_data_dict will be converted to JSON Schema types and define the elements of the JSON Schema.

Parameters
  • typical_data_dict (Mapping[str, Union[str, float, bool, Sequence[Union[str, float, bool]]]]) – Typical elements values indexed by the elements names.

  • description_dict (Optional[Mapping[str, str]]) –

    The descriptions of the data names, in the form: {element_name: element_meaning}. If None, do not initialize the elements with descriptions.

    By default it is set to None.

Return type

None

initialize_from_data_names(data_names, descriptions=None)[source]

Initialize the grammar from the names and descriptions of the elements.

Use float type.

Parameters
  • data_names (Iterable[str]) – The names of the elements.

  • descriptions (Optional[Mapping[str, str]]) –

    The descriptions of the elements, in the form: {element_name: element_meaning}. If None, do not initialize the elements with descriptions.

    By default it is set to None.

Return type

None

is_all_data_names_existing(data_names)[source]

Check if the names of the elements are present in the grammar.

Parameters

data_names (Iterable[str]) – The names of the elements.

Returns

Whether all the elements names are in the grammar.

Return type

bool

is_data_name_existing(data_name)[source]

Check if the name of an element is present in the grammar.

Parameters

data_name (str) – The name of the element.

Returns

Whether the name of the element is present in the grammar.

Return type

bool

is_required(element_name)[source]

Check if an element is required in the grammar.

Parameters

element_name (str) – The data name to check.

Returns

Whether the element name is required.

Raises

ValueError – If the given element is not in the grammar.

Return type

bool

is_type_array(data_name)[source]

Check if an element is an array.

Parameters

data_name (str) – The name of the element.

Returns

Whether the element is an array.

Raises

ValueError – If the name does not correspond to an element name.

Return type

bool

load_data(data, raise_exception=True)[source]

Load elements values and check their consistency with the grammar.

Parameters
  • data (MutableMapping[str, Union[str, float, bool, Sequence[Union[str, float, bool]]]]) – The elements values to be checked.

  • raise_exception (bool) –

    Whether to raise an exception when the elements values are not consistent with the grammar.

    By default it is set to True.

Returns

The elements values after successful consistency checking.

Raises

InvalidDataException

  • If the passed data is not a dictionary. * If the data is not consistent with the grammar.

Return type

MutableMapping[str, Union[str, float, bool, Sequence[Union[str, float, bool]]]]

property properties_dict

The dictionnary representation of the properties of the schema.

Raises

ValueError – When the schema has no properties.

remove_item(item_name)[source]

Remove an element.

Parameters

item_name (str) – The name of the element to be removed.

Raises

KeyError – When the element is not in the grammar.

Return type

None

restrict_to(data_names)[source]

Restrict the grammar to the given names.

Parameters

data_names (Sequence[str]) – The names of the elements to restrict the grammar to.

Return type

None

property schema_dict

The dictionary representation of the schema.

set_item_value(item_name, item_value)[source]

Set the value of an element.

Parameters
  • item_name (str) – The name of the element.

  • item_value (Dict[str, str]) – The value of the element.

Raises

ValueError – If the item is not in the grammar.

Return type

None

to_simple_grammar()[source]

Convert to the base SimpleGrammar type.

Ignore the features of JSONGrammar that are not supported by SimpleGrammar.

Returns

A SimpleGrammar equivalent to the current grammar.

Return type

gemseo.core.grammars.simple_grammar.SimpleGrammar

update_elements(python_typing=False, **elements)

Add or update elements from their names and types.

Parameters
  • python_typing (bool) –

    If True, handle automatically the conversion from Python type to grammar type.

    By default it is set to False.

  • **elements (Mapping[str, type]) – The names to types bindings of the elements to add or update.

Return type

None

Examples

>>> grammar.update_elements(a=str, b=int)
>>> grammar.update_elements(a=str, b=int, python_typing=True)
>>> grammar.update_elements(**names_to_types)
update_from(input_grammar)[source]

Update the grammar with a second one.

Add the new elements and update the existing ones.

Parameters

input_grammar (gemseo.core.grammars.json_grammar.JSONGrammar) – The grammar to take the elements from.

Raises

TypeError – If the passed grammar is not a JSONGrammar.

Return type

None

update_from_if_not_in(input_grammar, exclude_grammar)[source]

Add the elements from a second grammar that are not present in a third one.

Parameters
Return type

None

update_required_elements(**elements)

Add or update the required elements in the grammar.

Parameters

**elements (Mapping[str, bool]) – The names of the elements bound to whether they shall be required.

Raises
  • KeyError – If a given element name is not in the grammar.

  • TypeError – If a given element name is not associated to a boolean value.

Return type

None

write_schema(path=None)[source]

Write the schema to a file.

Parameters

path (Optional[Path,str]) –

The file path. If None, then write to a file named after the grammar and with .json extension.

By default it is set to None.

Return type

None

exception gemseo.core.grammars.json_grammar.ValidationError[source]

Bases: BaseException

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.