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

input_grammar (gemseo.core.grammars.json_grammar.JSONGrammar) – The grammar to take the elements from.
exclude_grammar (gemseo.core.grammars.json_grammar.JSONGrammar) – The grammar containing the elements not to be taken.

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.