json_grammar module¶

A Grammar based on JSON schema.

class gemseo.core.grammars.json_grammar.JSONGrammar(name, file_path='', descriptions=mappingproxy({}), **kwargs)[source]¶

Bases: BaseGrammar

A grammar based on a JSON schema.

For the dictionary-like methods similar to update, when a key exists in both grammars, the values can be merged instead of being updated by passing merge = True. In that case, the resulting grammar will allow any of the values.

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

Parameters:

name (str) – The name of the grammar.
file_path (str | Path) –
The path to a JSON schema file. If None, do not initialize the grammar from a JSON schema file.

By default it is set to “”.
descriptions (Mapping[str, str]) –
The descriptions of the elements read from file_path, 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 {}.
**kwargs (Any) – These arguments are not used.

Raises:

ValueError – If the name is empty.

DATA_CONVERTER_CLASS¶: alias of DataConverter

add_namespace(name, namespace)¶

Add a namespace prefix to an existing grammar element.

The updated element name will be namespace``+:data:`~gemseo.core.namespaces.namespace_separator`+``name.

Parameters:

name (str) – The element name to rename.
namespace (str) – The name of the namespace.

Raises:

ValueError – If the variable already has a namespace.

Return type:

None

clear()¶

Empty the grammar.

Return type:: None

copy()¶

Create a shallow copy.

Returns:: The shallow copy.
Return type:: Self

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

is_array(name, numeric_only=False)[source]¶

Check if an element is an array.

Parameters:

name (str) – The name of the element.
numeric_only (bool) –
Whether to check if the array elements are numbers.

By default it is set to False.

Returns:

Whether the element is an array.

Raises:

KeyError – If the element is not in the grammar.

Return type:

bool

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

rename_element(current_name, new_name)¶

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

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

set_descriptions(descriptions)[source]¶

Set the properties descriptions.

Parameters:: descriptions (Mapping[str, str]) – The descriptions, mapping properties names to the description.
Return type:: None

to_file(path='')[source]¶

Write the grammar ,schema to a json file.

Parameters:

path (Path | str) –

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

By default it is set to “”.

Return type:

None

to_json(*args, **kwargs)[source]¶

Return the JSON representation of the grammar schema.

Parameters:

*args (Any) – The positional arguments passed to json.dumps().
**kwargs (Any) – The keyword arguments passed to json.dumps().

Returns:

The JSON representation of the schema.

Return type:

str

to_simple_grammar()¶

Convert the grammar to a SimpleGrammar.

Returns:: A SimpleGrammar version of the current grammar.
Return type:: SimpleGrammar

update(grammar, exclude_names=(), merge=False)¶

Update the grammar from another grammar.

Parameters:

grammar (Self) – The grammar to update from.
exclude_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)¶

Update the grammar from name-value pairs.

The updated elements are required.

Parameters:

data (Data) – 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_file(path, merge=False)[source]¶

Update the grammar from a schema file.

Parameters:

path (str | Path) – The path to the schema file.
merge (bool) –
Whether to merge or update the grammar.

By default it is set to False.

Raises:

FileNotFoundError – If the schema file does not exist.

Return type:

None

update_from_names(names, merge=False)¶

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_schema(schema, merge=False)[source]¶

Update the grammar from a json schema.

Parameters:

schema (Schema) – The schema 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)¶

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

Validate data against the grammar.

Parameters:

data (Data) – 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

values() → an object providing a view on D's values¶

property data_converter: BaseDataConverter[BaseGrammar]¶: The converter of data values to NumPy arrays and vice versa.

property defaults: Defaults¶: The mapping from the names to the default values, if any.

from_namespaced: NamespacesMapping¶: 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 required_names: RequiredNames¶: The names of the required elements.

property schema: Schema¶: The dictionary representation of the schema.

to_namespaced: NamespacesMapping¶: The mapping from element names without namespace prefix to element names with namespace prefix.

Examples using JSONGrammar¶

Merge or update a JSONGrammar