gt4py.eve package

Subpackages

Submodules

gt4py.eve.codegen module

Tools for source code generation.

class gt4py.eve.codegen.BaseTemplate[source]

Bases: gt4py.eve.codegen.Template

Helper class to add source location info of template definitions.

definition: typing_extensions.Any
definition_loc: Optional[tuple[str, int]]
class gt4py.eve.codegen.FormatTemplate(definition: str, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.codegen.BaseTemplate

Template adapter to render regular strings as fully-featured f-strings.

definition: str
render_values(**kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

**kwargs – Placeholder values provided as keyword arguments.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

exception gt4py.eve.codegen.FormatterNameError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveRuntimeError

Run-time error registering a new source code formatter.

info: dict[str, typing_extensions.Any]
exception gt4py.eve.codegen.FormattingError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveRuntimeError

Run-time error applying a source code formatter.

info: dict[str, typing_extensions.Any]
class gt4py.eve.codegen.JinjaTemplate(definition: Union[str, jinja2.environment.Template], **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.codegen.BaseTemplate

Template adapter for jinja2.Template.

definition: jinja2.environment.Template
render_values(**kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

**kwargs – Placeholder values provided as keyword arguments.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

class gt4py.eve.codegen.MakoTemplate(definition: mako.template.Template, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.codegen.BaseTemplate

Template adapter for mako.template.Template.

definition: mako.template.Template
render_values(**kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

**kwargs – Placeholder values provided as keyword arguments.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

class gt4py.eve.codegen.Name(words: Union[str, collections.abc.Iterable[str]])[source]

Bases: object

Text formatter with different case styles for symbol names in source code.

as_case(case_style: gt4py.eve.utils.CaseStyleConverter.CASE_STYLE) → str[source]
classmethod from_string(name: str, case_style: gt4py.eve.utils.CaseStyleConverter.CASE_STYLE) → gt4py.eve.codegen.Name[source]
words: list[str]
gt4py.eve.codegen.SOURCE_FORMATTERS: dict[str, collections.abc.Callable[[str], str]] = {'python': <function format_python_source>}

Global dict storing registered formatters.

class gt4py.eve.codegen.StringTemplate(definition: Union[str, string.Template], **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.codegen.BaseTemplate

Template adapter for string.Template.

definition: string.Template
render_values(**kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

**kwargs – Placeholder values provided as keyword arguments.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

class gt4py.eve.codegen.Template(*args, **kwargs)[source]

Bases: Protocol

Protocol (abstract base class) defining the Template interface.

Direct subclassess of this base class only need to implement the abstract methods to adapt different template engines to this interface.

Raises

TemplateDefinitionError – If the template definition contains errors.

render(mapping: Optional[collections.abc.Mapping[str, str]] = None, **kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

  • mapping – A mapping whose keys match the template placeholders.

  • **kwargs – Placeholder values provided as keyword arguments (they will take precedence over mapping values for duplicated keys.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

abstract render_values(**kwargs: typing_extensions.Any) → str[source]

Render the template.

Parameters

**kwargs – Placeholder values provided as keyword arguments.

Returns

The rendered string.

Raises

TemplateRenderingError – If the template rendering fails.

exception gt4py.eve.codegen.TemplateDefinitionError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveTypeError

Template definition error.

info: dict[str, typing_extensions.Any]
exception gt4py.eve.codegen.TemplateRenderingError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveRuntimeError

Run-time error rendering a template.

info: dict[str, typing_extensions.Any]
class gt4py.eve.codegen.TemplatedGenerator[source]

Bases: gt4py.eve.visitors.NodeVisitor

A code generator visitor using TextTemplate.

The order followed to choose a dump() function for node values is the following:

  1. A self.visit_NODE_CLASS_NAME() method where NODE_CLASS_NAME matches type(node).__name__.

  2. A self.visit_NODE_BASE_CLASS_NAME() method where NODE_BASE_CLASS_NAME matches base.__name__, and base is one of the node base classes (evaluated following the order given in type(node).__mro__).

If node is an instance of eve.Node and a visit_ method has not been found, TemplatedGenerator will look for an appropriate Template definition:

  1. A NODE_CLASS_NAME class variable of type Template, where NODE_CLASS_NAME matches type(node).__name__.

  2. A NODE_BASE_CLASS_NAME class variable of type Template, where NODE_BASE_CLASS_NAME matches base.__name__, and base is one of the node base classes (evaluated following the order given in type(node).__mro__).

In any other case (templates cannot be used for instances of arbitrary types), steps 3 and 4 will be substituted by a call to the self.generic_dump() method.

The following keys are passed to template instances at rendering:

  • **node_fields: all the node children and implementation fields by name.

  • _impl: a dict instance with the results of visiting all the node implementation fields.

  • _children: a dict instance with the results of visiting all the node children.

  • _this_node: the actual node instance (before visiting children).

  • _this_generator: the current generator instance.

  • _this_module: the generator’s module instance.

  • **kwargs: the keyword arguments received by the visiting method.

Visitor methods can trigger regular template rendering for the same node class by explicitly calling generic_visit() (typically at the end), which will continue the search rendering algorithm at step 3. Thus, a common pattern to deal with complicated nodes is to define both a visitor method and a template for the same class, where the visitor method preprocess the node data and calls generic_visit() at the end with additional keyword arguments which will be forwarded to the node template.

classmethod apply(root: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → Union[str, collections.abc.Collection[str]][source]

Public method to build a class instance and visit an IR node.

Parameters

  • root – An IR node.

  • node_templates (optiona) – see NodeDumper.

  • dump_function (optiona) – see NodeDumper.

  • **kwargs (optional) – custom extra parameters forwarded to visit_NODE_TYPE_NAME().

Returns

String (or collection of strings) with the dumped version of the root IR node.

classmethod generic_dump(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → str[source]

Class-specific dump() function for primitive types.

This class could be redefined in the subclasses.

generic_visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → Union[str, collections.abc.Collection[str]][source]
get_template(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]]) → tuple[Optional[gt4py.eve.codegen.Template], Optional[str]][source]

Get a template for a node instance (see class documentation).

render_template(template: gt4py.eve.codegen.Template, node: gt4py.eve.concepts.Node, transformed_children: collections.abc.Mapping[str, typing_extensions.Any], transformed_annexed_items: collections.abc.Mapping[str, typing_extensions.Any], **kwargs: typing_extensions.Any) → str[source]

Render a template using node instance data (see class documentation).

transform_annexed_items(node: gt4py.eve.concepts.Node, **kwargs: typing_extensions.Any) → dict[str, typing_extensions.Any][source]
transform_children(node: gt4py.eve.concepts.Node, **kwargs: typing_extensions.Any) → dict[str, typing_extensions.Any][source]
class gt4py.eve.codegen.TextBlock(*, indent_level: int = 0, indent_size: int = 4, indent_char: str = ' ', end_line: str = '\n')[source]

Bases: object

A block of source code represented as a sequence of text lines.

Check the provided context manager creator method (indented()) for simple indent - append - dedent workflows.

Parameters

  • indent_level – Initial indentation level.

  • indent_size – Number of characters per indentation level.

  • indent_char – Character used in the indentation.

  • end_line – Character or string used as new-line separator.

append(new_line: str, *, update_indent: int = 0) → gt4py.eve.codegen.TextBlock[source]
dedent(steps: int = 1) → gt4py.eve.codegen.TextBlock[source]
empty_line(count: int = 1) → gt4py.eve.codegen.TextBlock[source]
extend(new_lines: Union[collections.abc.Sequence[str], gt4py.eve.codegen.TextBlock], *, dedent: bool = False) → gt4py.eve.codegen.TextBlock[source]
indent(steps: int = 1) → gt4py.eve.codegen.TextBlock[source]
property indent_str: str

Indentation string for new lines (in the current state).

indented(steps: int = 1) → collections.abc.Iterator[gt4py.eve.codegen.TextBlock][source]

Context manager creator for temporary indentation of sources.

This context manager simplifies the usage of indent/dedent in common indent - append - dedent workflows.

Examples

>>> block = TextBlock();
>>> block.append('first line')  
<...>
>>> with block.indented():
...     block.append('second line');  
<...>
>>> block.append('third line')  
<...>
>>> print(block.text)
first line
    second line
third line
property text: str

Single string with the whole block contents.

gt4py.eve.codegen._get_clang_format() → Optional[str][source]

Return the clang-format executable, or None if not available.

gt4py.eve.codegen.format_python_source(source: str, *, line_length: int = 100, python_versions: Optional[set[str]] = None, string_normalization: bool = True) → str[source]

Format Python source code using black formatter.

gt4py.eve.codegen.format_source(language: str, source: str, *, skip_errors: bool = True, **kwargs: typing_extensions.Any) → str[source]

Format source code if a formatter exists for the specific language.

gt4py.eve.codegen.register_formatter(language: str) → collections.abc.Callable[[collections.abc.Callable[[str], str]], collections.abc.Callable[[str], str]][source]

Register source code formatters for specific languages (decorator).

gt4py.eve.concepts module

Definitions of basic Eve concepts.

class gt4py.eve.concepts.AnnexManager[source]

Bases: object

register: ClassVar[dict[str, typing_extensions.Any]] = {'symtable': (True, dict[str, gt4py.eve.concepts.Node], [<class 'gt4py.eve.traits.SymbolTableTrait'>, <class 'gt4py.eve.traits.SymbolRefsValidatorTrait'>])}
classmethod register_user()[source]
class gt4py.eve.concepts.FrozenNode[source]

Bases: gt4py.eve.concepts.Node

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.concepts.GenericNode[source]

Bases: gt4py.eve.datamodels.core.GenericDataModel, gt4py.eve.concepts.Node

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.concepts.Node[source]

Bases: gt4py.eve.datamodels.core.DataModel, gt4py.eve.trees.Tree

Base class representing a node in a syntax tree.

Implemented as a eve.datamodels.DataModel with some extra features.

Field values should be either:

  • builtin types: bool, bytes, int, float, str

  • enum.Enum types

  • other Node subclasses

  • other eve.datamodels.DataModel subclasses

  • supported collections (List, Dict, Set)

    of any of the previous items

The annex attribute is used to dynamically add data to a node, even to frozen classes. Data in the annex do not affect the hash or equality comparisons of the node, since it is not really a field. Thus, visitors and pipeline passes can freely attach computed attributes into the instance annex.

property annex: gt4py.eve.utils.Namespace
bfs_walk_items(*, __key__: Optional[Union[int, str]] = None, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs by tree levels (Breadth-First Search).

bfs_walk_values(*, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]]

Create a tree traversal iterator of values by tree levels (Breadth-First Search).

copy(update: dict[str, typing_extensions.Any]) → gt4py.eve.concepts._T[source]
iter_children_items() → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]][source]
iter_children_values() → collections.abc.Iterable[source]
post_walk_items(*, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a post-order tree traversal iterator of (key, value) pairs.

post_walk_values() → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a post-order tree traversal iterator of values.

pre_walk_items(*, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a pre-order tree traversal iterator of (key, value) pairs.

pre_walk_values() → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a pre-order tree traversal iterator of values.

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

walk_items(traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs.

walk_values(traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[typing_extensions.Any]

Create a tree traversal iterator of values.

class gt4py.eve.concepts.SourceLocation(line: int, column: int, source: str, *, end_line: Optional[int] = None, end_column: Optional[int] = None)[source]

Bases: object

Source code location (line, column, source).

column: int
end_column: Optional[int]
end_line: Optional[int]
classmethod from_AST(ast_node: ast.AST, source: Optional[str] = None) → gt4py.eve.concepts.SourceLocation[source]
line: int
source: str
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.concepts.SourceLocationGroup(*locations: gt4py.eve.concepts.SourceLocation, context: Optional[Union[str, tuple[str, ...]]] = None)[source]

Bases: object

A group of merged source code locations (with optional info).

context: Optional[Union[str, tuple[str, ...]]]
locations: tuple[gt4py.eve.concepts.SourceLocation, ...]
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.concepts.SymbolName(value: str)[source]

Bases: gt4py.eve.type_definitions.ConstrainedStr

String value containing a valid symbol name for typical programming conventions.

regex: ClassVar[re.Pattern] = re.compile('^[a-zA-Z_]\\w*$')
class gt4py.eve.concepts.SymbolRef(value: str)[source]

Bases: gt4py.eve.type_definitions.ConstrainedStr

Reference to a symbol name.

regex: ClassVar[re.Pattern] = re.compile('^[a-zA-Z_]\\w*$')
class gt4py.eve.concepts.VType(name: str)[source]

Bases: gt4py.eve.datamodels.core.FrozenModel

name: str
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

gt4py.eve.concepts.eq_nonlocated(a: gt4py.eve.concepts.Node, b: gt4py.eve.concepts.Node) → bool[source]

Compare two nodes, ignoring their SourceLocation or SourceLocationGroup.

gt4py.eve.concepts.register_annex_user()

gt4py.eve.exceptions module

Definitions of specific Eve exceptions.

class gt4py.eve.exceptions.EveError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: object

Base class for Eve-specific exceptions.

Notes

This base class has to be always inherited together with a standard exception, and thus it should not be used as direct superclass for custom exceptions. Inherit directly from EveTypeError, EveTypeError, etc. instead.

info: dict[str, typing_extensions.Any]
message_template = 'Generic Eve error [{info}]'
exception gt4py.eve.exceptions.EveRuntimeError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveError, RuntimeError

Base class for Eve-specific run-time errors.

info: dict[str, typing_extensions.Any]
message_template = 'Runtime error [{info}]'
exception gt4py.eve.exceptions.EveTypeError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveError, TypeError

Base class for Eve-specific type errors.

info: dict[str, typing_extensions.Any]
message_template = 'Invalid or unexpected type [{info}]'
exception gt4py.eve.exceptions.EveValueError(message: Optional[str] = None, **kwargs: typing_extensions.Any)[source]

Bases: gt4py.eve.exceptions.EveError, ValueError

Base class for Eve-specific value errors.

info: dict[str, typing_extensions.Any]
message_template = 'Invalid value [{info}]'

gt4py.eve.extended_typing module

Typing definitions working across different Python versions (via typing_extensions).

Definitions in ‘typing_extensions’ take priority over those in ‘typing’.

gt4py.eve.extended_typing.ReadOnlyBuffer

alias of Union[bytes, SupportsBytes]

gt4py.eve.extended_typing.ReadableBuffer

alias of Union[bytes, SupportsBytes, bytearray, memoryview, array.array, mmap.mmap, pickle.PickleBuffer]

gt4py.eve.extended_typing.StdGenericAliasType: Final[Type] = <class 'types.GenericAlias'>

Represent a PEP 585 generic type

E.g. for t = list[int], t.__origin__ is list and t.__args__ is (int,).

gt4py.eve.extended_typing.WriteableBuffer

alias of Union[bytearray, memoryview, array.array, mmap.mmap, pickle.PickleBuffer]

gt4py.eve.extended_typing._ArtefactTypes: tuple[type, ...] = (<class 'types.GenericAlias'>, typing_extensions.Any)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

gt4py.eve.extended_typing._TypingGenericAliasType: Final[Type] = <class 'typing._BaseGenericAlias'>

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

gt4py.eve.extended_typing._TypingSpecialFormType: Final[Type] = <class 'typing._SpecialForm'>

gt4py.eve.pattern_matching module

Basic pattern matching utilities.

class gt4py.eve.pattern_matching.ObjectPattern(cls: type, **fields: typing_extensions.Any)[source]

Bases: object

Class to pattern match general objects.

A pattern matches an object if it is an instance of the specified class and all attributes of the pattern (recursively) match the objects attributes.

Examples

>>> class Foo:
...    def __init__(self, bar, baz):
...        self.bar = bar
...        self.baz = baz
>>> assert ObjectPattern(Foo, bar=1).match(Foo(1, 2))
cls: type
fields: dict[str, typing_extensions.Any]
match(other: typing_extensions.Any, *, raise_exception: bool = False) → bool[source]

Return True if object pattern matches other using get_differences().

If raise_exception is specified raises an exception with all differences found.

gt4py.eve.pattern_matching.get_differences(a: typing_extensions.Any, b: typing_extensions.Any, path: str = '') → collections.abc.Iterator[tuple[str, str]][source]

Compare two objects and return a list of differences.

If the arguments are lists or dictionaries comparison is recursively per item. Objects are compared using equality operator or if the left-hand-side is an ObjectPattern its type and attributes are compared to the right-hand-side object. Only the attributes of the ObjectPattern are used for comparison, disregarding potential additional attributes of the right-hand-side.

gt4py.eve.traits module

Definitions of node and visitor trait classes.

class gt4py.eve.traits.SymbolRefsValidatorTrait[source]

Bases: object

Node trait adding automatic validation of symbol references appearing the node tree.

It assumes that the symbol table with the actual definitions is stored as a dict in the annex.symtable attribute (like SymbolTableTrait does).

class SymbolRefsValidator[source]

Bases: gt4py.eve.visitors.NodeVisitor

classmethod apply(node: gt4py.eve.concepts.Node, *, symtable: dict[str, typing_extensions.Any]) → set[str][source]
visit_Node(node: gt4py.eve.concepts.Node, *, symtable: dict[str, typing_extensions.Any], **kwargs: typing_extensions.Any) → None[source]
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.traits.SymbolTableTrait[source]

Bases: object

Node trait adding an automatically created symbol table to the parent node.

The actual symbol table dict will be stored in the annex.symtable attribute. To inject extra symbol definitions, add the nodes to a class attribute called _NODE_SYMBOLS_.

class SymbolsCollector[source]

Bases: gt4py.eve.visitors.NodeVisitor

classmethod apply(node: gt4py.eve.concepts.Node) → dict[str, gt4py.eve.concepts.Node][source]
visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
visit_Node(node: gt4py.eve.concepts.Node, /) → None[source]
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.traits.ValidatedSymbolTableTrait[source]

Bases: gt4py.eve.traits.SymbolRefsValidatorTrait, gt4py.eve.traits.SymbolTableTrait

Node trait adding an automatically created and validated symbol table.

It is just the combination of the SymbolTableTrait and SymbolRefsValidatorTrait traits.

class gt4py.eve.traits.VisitorWithSymbolTableTrait[source]

Bases: gt4py.eve.visitors.NodeVisitor

Visitor trait to update or add the symtable to kwargs in the visitor calls.

Visitors inhering from this trait will automatically pass the active symbol table to visitor methods as the ‘symtable’ keyword argument.

visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]

gt4py.eve.trees module

Iterator utils.

class gt4py.eve.trees.TraversalOrder(value)[source]

Bases: enum.Enum

An enumeration.

BFS_ORDER = 'bfs'
POST_ORDER = 'post'
PRE_ORDER = 'pre'
class gt4py.eve.trees.Tree(*args, **kwargs)[source]

Bases: Protocol

abstract iter_children_items() → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]][source]
abstract iter_children_values() → collections.abc.Iterable[source]
class gt4py.eve.trees.TreeLike[source]

Bases: abc.ABC

gt4py.eve.trees._bfs_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]][source]

Create a tree traversal iterator of (key, value) pairs by tree levels (Breadth-First Search).

gt4py.eve.trees._bfs_walk_values(node: gt4py.eve.trees.TreeLike, *, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]][source]

Create a tree traversal iterator of values by tree levels (Breadth-First Search).

gt4py.eve.trees._post_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]][source]

Create a post-order tree traversal iterator of (key, value) pairs.

gt4py.eve.trees._post_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]][source]

Create a post-order tree traversal iterator of values.

gt4py.eve.trees._pre_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]][source]

Create a pre-order tree traversal iterator of (key, value) pairs.

gt4py.eve.trees._pre_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]][source]

Create a pre-order tree traversal iterator of values.

gt4py.eve.trees.bfs_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs by tree levels (Breadth-First Search).

gt4py.eve.trees.bfs_walk_values(node: gt4py.eve.trees.TreeLike, *, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]]

Create a tree traversal iterator of values by tree levels (Breadth-First Search).

gt4py.eve.trees.iter_children_items(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]][source]
gt4py.eve.trees.iter_children_items(_: str)
gt4py.eve.trees.iter_children_items(_: bytes)
gt4py.eve.trees.iter_children_items(x: collections.abc.Sequence)
gt4py.eve.trees.iter_children_items(x: collections.abc.Set)
gt4py.eve.trees.iter_children_items(x: collections.abc.Mapping)

Create an iterator to traverse values as Eve tree nodes.

gt4py.eve.trees.iter_children_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[source]
gt4py.eve.trees.iter_children_values(_: str)
gt4py.eve.trees.iter_children_values(_: bytes)
gt4py.eve.trees.iter_children_values(x: collections.abc.Sequence)
gt4py.eve.trees.iter_children_values(x: collections.abc.Set)
gt4py.eve.trees.iter_children_values(x: collections.abc.Mapping)

Create an iterator to traverse values as Eve tree nodes.

gt4py.eve.trees.post_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a post-order tree traversal iterator of (key, value) pairs.

gt4py.eve.trees.post_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a post-order tree traversal iterator of values.

gt4py.eve.trees.pre_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a pre-order tree traversal iterator of (key, value) pairs.

gt4py.eve.trees.pre_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a pre-order tree traversal iterator of values.

gt4py.eve.trees.register_tree_like(*types: type[_T], iter_values_fn: collections.abc.Callable[[gt4py.eve.trees._T], collections.abc.Iterable], iter_items_fn: collections.abc.Callable[[gt4py.eve.trees._T], collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]]]) → None[source]
gt4py.eve.trees.walk_items(node: gt4py.eve.trees.TreeLike, traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[tuple[Union[int, str, NoneType], typing_extensions.Any]][source]

Create a tree traversal iterator of (key, value) pairs.

gt4py.eve.trees.walk_values(node: gt4py.eve.trees.TreeLike, traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[typing_extensions.Any][source]

Create a tree traversal iterator of values.

gt4py.eve.type_definitions module

Definitions of useful field and general types.

class gt4py.eve.type_definitions.ConstrainedStr(value: str)[source]

Bases: str

Base string subclass allowing to restrict values to those satisfying a regular expression.

Subclasses should define the specific constraint pattern in the regex class keyword argument or as class variable.

Examples

>>> class OnlyLetters(ConstrainedStr, regex=re.compile(r"^[a-zA-Z]*$")): pass
>>> OnlyLetters("aabbCC")
OnlyLetters('aabbCC')

>>> OnlyLetters("aabbCC33")
Traceback (most recent call last):
    ...
ValueError: OnlyLetters('aabbCC33') does not satisfies RE constraint re.compile('^[a-zA-Z]*$').
regex: ClassVar[re.Pattern]
class gt4py.eve.type_definitions.FrozenList(iterable=(), /)[source]

Bases: tuple[gt4py.eve.type_definitions._Tc, …]

Tuple subtype which works as an alias of Tuple[_Tc, ...].

class gt4py.eve.type_definitions.NOTHING[source]

Bases: object

Marker to avoid confusion with None in contexts where None could be a valid value.

class gt4py.eve.type_definitions.NothingType[source]

Bases: type

Metaclass of NOTHING setting its bool value to False.

class gt4py.eve.type_definitions.StrEnum(value)[source]

Bases: str, enum.Enum

enum.Enum subclass whose members are considered as real strings.

_generate_next_value_(start, count, last_values)

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_value: the last value assigned or None

gt4py.eve.type_validation module

Generic interface and implementations of run-time type validation for arbitrary values.

class gt4py.eve.type_validation.FixedTypeValidator(*args, **kwargs)[source]

Bases: Protocol

abstract __call__(value: typing_extensions.Any, **kwargs: typing_extensions.Any) → None[source]

Protocol for callables checking that value matches a fixed type_annotation.

Parameters

value – value to be checked against the typing annotation.

Keyword Arguments

**kwargs – arbitrary implementation-defined arguments (e.g. for memoization).

Raises

TypeError – if there is a type mismatch.

class gt4py.eve.type_validation.SimpleTypeValidatorFactory[source]

Bases: gt4py.eve.type_validation.TypeValidatorFactory

A simple TypeValidatorFactory implementation.

Check FixedTypeValidator and TypeValidatorFactory for details.

Keyword Arguments

strict_int (bool) – do not accept bool values as int (default: True).

__call__()[source]

Protocol for :class:`FixedTypeValidator`s.

The arguments match the specification in TypeValidator.

Raises

  • TypeError – if there is a type mismatch.

  • ValueError – if required is True and type_annotation is not supported.

static _make_is_any(name: str) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for any type.

static combine_optional(name: str, actual_validator: gt4py.eve.type_validation.FixedTypeValidator) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for an optional constraint.

static combine_validators_as_or(name: str, *validators: gt4py.eve.type_validation.FixedTypeValidator, error_type: type[Exception] = <class 'TypeError'>) → gt4py.eve.type_validation.FixedTypeValidator[source]
static make_is_instance_of(name: str, type_: type) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for a specific type.

static make_is_instance_of_int(name: str) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for int values which fails with bool values.

static make_is_iterable_of(name: str, member_validator: gt4py.eve.type_validation.FixedTypeValidator, iterable_validator: Optional[gt4py.eve.type_validation.FixedTypeValidator] = None) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for deep checks of typed iterables.

static make_is_literal(name: str, literal_value: typing_extensions.Any) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for a literal value.

static make_is_mapping_of(name: str, key_validator: gt4py.eve.type_validation.FixedTypeValidator, value_validator: gt4py.eve.type_validation.FixedTypeValidator, mapping_validator: Optional[gt4py.eve.type_validation.FixedTypeValidator] = None) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for deep checks of typed mappings.

static make_is_tuple_of(name: str, item_validators: collections.abc.Sequence[gt4py.eve.type_validation.FixedTypeValidator], tuple_type: type[tuple]) → gt4py.eve.type_validation.FixedTypeValidator[source]

Create an FixedTypeValidator validator for tuple types.

class gt4py.eve.type_validation.TypeValidator(*args, **kwargs)[source]

Bases: Protocol

abstract __call__()[source]

Protocol for callables checking that value matches type_annotation.

Parameters

  • value – value to be checked against the typing annotation.

  • type_annotation – a valid typing annotation.

  • name – the name of the checked value (used for error messages).

Keyword Arguments

  • globalns – globals dict used in the evaluation of the annotations.

  • localns – locals dict used in the evaluation of the annotations.

  • required – if True, raise ValueError when provided type annotation is not supported.

  • **kwargs – arbitrary implementation-defined arguments (e.g. for memoization).

Raises

  • TypeError – if there is a type mismatch.

  • ValueError – if required is True and type_annotation is not supported.

class gt4py.eve.type_validation.TypeValidatorFactory(*args, **kwargs)[source]

Bases: Protocol

abstract __call__()[source]

Protocol for :class:`FixedTypeValidator`s.

The arguments match the specification in TypeValidator.

Raises

  • TypeError – if there is a type mismatch.

  • ValueError – if required is True and type_annotation is not supported.

gt4py.eve.type_validation.simple_type_validator()[source]

Check that value satisfies a type definition (a simple TypeValidator implementation).

Check TypeValidator and SimpleTypeValidatorFactory for details.

Keyword Arguments

strict_int (bool) – do not accept bool values as int (default: True).

gt4py.eve.type_validation.simple_type_validator_factory: Final = <function optional_lru_cache.<locals>._decorator.<locals>.inner>

Public (with optional cache) entry point for SimpleTypeValidatorFactory.

gt4py.eve.utils module

General utility functions. Some functionalities are directly imported from dependencies.

class gt4py.eve.utils.CaseStyleConverter[source]

Bases: object

Utility class to convert name strings to different case styles.

Functionality exposed through split(), join() and convert() methods.

class CASE_STYLE(value)[source]

Bases: enum.Enum

An enumeration.

CAMEL = 'camel'
CANONICAL = 'canonical'
CONCATENATED = 'concatenated'
KEBAB = 'kebab'
PASCAL = 'pascal'
SNAKE = 'snake'
classmethod convert(name: str, source_style: Union[CASE_STYLE, str], target_style: Union[CASE_STYLE, str]) → str[source]
classmethod join(words: AnyWordsIterable, case_style: Union[CASE_STYLE, str]) → str[source]
static join_camel_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
static join_canonical_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
static join_concatenated_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
static join_kebab_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
static join_pascal_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
static join_snake_case(words: Union[str, collections.abc.Iterable[str]]) → str[source]
classmethod split(name: str, case_style: Union[CASE_STYLE, str]) → List[str][source]
static split_camel_case(name: str) → list[str][source]
static split_canonical_case(name: str) → list[str][source]
static split_kebab_case(name: str) → list[str][source]
static split_pascal_case(name: str) → list[str]
static split_snake_case(name: str) → list[str][source]
class gt4py.eve.utils.FrozenNamespace[source]

Bases: gt4py.eve.utils.Namespace[gt4py.eve.utils.T]

An immutable version of Namespace.

Examples

>>> ns = FrozenNamespace(a=10, b="hello")
>>> ns.a
10
>>> ns.a = 20
Traceback (most recent call last):
   ...
TypeError: Trying to modify immutable 'FrozenNamespace' instance.

>>> ns = FrozenNamespace(a=10, b="hello")
>>> list(ns.items())
[('a', 10), ('b', 'hello')]

>>> ns = FrozenNamespace(a=10, b="hello")
>>> hashed = hash(ns)
>>> assert isinstance(hashed, int)
>>> hashed == hash(ns) == ns.__cached_hash_value__
True
class gt4py.eve.utils.Namespace[source]

Bases: types.SimpleNamespace, Generic[gt4py.eve.utils.T]

A types.SimpleNamespace-like class with additional dict-like interface.

Examples

>>> ns = Namespace(a=10, b="hello")
>>> ns.a
10
>>> ns.b = 20
>>> ns.b
20

>>> ns = Namespace(a=10, b="hello")
>>> list(ns.keys())
['a', 'b']

>>> list(ns.values())
[10, 'hello']

>>> list(ns.items())
[('a', 10), ('b', 'hello')]
as_dict() → dict[str, T][source]
asdict() → dict[str, T]
items() → collections.abc.Iterable[tuple[str, T]][source]
keys() → collections.abc.Iterable[str][source]
reset(data: Optional[dict[str, typing_extensions.Any]] = None) → None[source]
values() → collections.abc.Iterable[gt4py.eve.utils.T][source]
class gt4py.eve.utils.UIDGenerator(prefix: Optional[str] = None, width: Optional[int] = None, warn_unsafe: Optional[bool] = None)[source]

Bases: object

Simple unique id generator using different methods.

prefix: Optional[str] = None
random_id(*, prefix: Optional[str] = None, width: Optional[int] = None) → str[source]

Generate a random globally unique id.

reset_sequence(start: int = 1, *, warn_unsafe: Optional[bool] = None) → gt4py.eve.utils.UIDGenerator[source]

Reset generator counter.

It returns the same instance to allow resetting at initialization:

Example

>>> generator = UIDGenerator().reset_sequence(3)

Notes

If the new start value is lower than the last generated UID, new IDs are not longer guaranteed to be unique.

sequential_id(*, prefix: Optional[str] = None, width: Optional[int] = None) → str[source]

Generate a sequential unique id (for the current session).

warn_unsafe: Optional[bool] = None
width: Optional[int] = None
class gt4py.eve.utils.XIterable(it: Union[collections.abc.Iterable[gt4py.eve.utils.T], collections.abc.Iterator[gt4py.eve.utils.T]])[source]

Bases: collections.abc.Iterable[gt4py.eve.utils.T]

Iterable wrapper supporting method chaining for extra functionality.

accumulate(func: collections.abc.Callable[[typing_extensions.Any, gt4py.eve.utils.T], typing_extensions.Any] = <built-in function add>, *, init: typing.Optional[typing_extensions.Any] = None) → gt4py.eve.utils.XIterable[source]

Reduce an iterator using a callable.

Equivalent to itertools.accumulate(self, func, init).

Keyword Arguments

init – initial value for the accumulation.

For detailed information check itertools.accumulate() reference.

Examples

>>> it = xiter(range(5))
>>> list(it.accumulate())
[0, 1, 3, 6, 10]

>>> it = xiter(range(5))
>>> list(it.accumulate(init=10))
[10, 10, 11, 13, 16, 20]

>>> it = xiter(range(1, 5))
>>> list(it.accumulate((lambda x, y: x * y), init=-1))
[-1, -1, -2, -6, -24]
chain(*others: collections.abc.Iterable) → gt4py.eve.utils.XIterable[Union[gt4py.eve.utils.T, gt4py.eve.utils.S]][source]

Chain iterators.

Equivalent to itertools.chain(self, *others).

For detailed information check itertools.chain() reference.

Examples

>>> it_a, it_b = xiter(range(2)), xiter(['a', 'b'])
>>> list(it_a.chain(it_b))
[0, 1, 'a', 'b']

>>> it_a = xiter(range(2))
>>> list(it_a.chain(['a', 'b'], ['A', 'B']))
[0, 1, 'a', 'b', 'A', 'B']
diff(*others: collections.abc.Iterable, default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>, key: typing.Union[<class 'gt4py.eve.type_definitions.NOTHING'>, collections.abc.Callable] = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[tuple[T, S]][source]

Diff iterators.

Equivalent to toolz.itertoolz.diff(self, *others).

Keyword Arguments

  • default – returned value for missing items.

  • key – callable computing the key to use per item in the sequence.

For detailed information check toolz.itertoolz.diff() reference.

Examples

>>> it_a, it_b = xiter([1, 2, 3]), xiter([1, 3, 5])
>>> list(it_a.diff(it_b))
[(2, 3), (3, 5)]

>>> it_a, it_b, it_c = xiter([1, 2, 3]), xiter([1, 3, 5]), xiter([1, 2, 5])
>>> list(it_a.diff(it_b, it_c))
[(2, 3, 2), (3, 5, 5)]

Adding missing values:

>>> it_a = xiter([1, 2, 3, 4])
>>> list(it_a.diff([1, 3, 5], default=None))
[(2, 3), (3, 5), (4, None)]

Use a key function:

>>> it_a, it_b = xiter(["Apples", "Bananas"]), xiter(["apples", "oranges"])
>>> list(it_a.diff(it_b, key=str.lower))
[('Bananas', 'oranges')]
filter(func: collections.abc.Callable[[...], bool]) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements with callables.

Equivalent to filter(func, self).

For detailed information check filter() reference.

Examples

>>> it = xiter(range(4))
>>> list(it.filter(lambda x: x % 2 == 0))
[0, 2]

>>> it = xiter(range(4))
>>> list(it.filter(lambda x: x % 2 == 0).filter(lambda x: x > 1))
[2]

Notes

lambdas, partial and curried functions are supported (see map()).

getattr(*names: str, default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[typing_extensions.Any][source]

Get provided attributes from each item in a sequence.

Equivalent to map(attrgetter_(*names, default=default), self).

Keyword Arguments

default – returned value if the item does not contain an attribute with the provided name.

For detailed information check attrgetter_() and operator.attrgetter() reference.

Examples

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y'])
>>> it = xiter([Point(1.0, -1.0), Point(2.0, -2.0), Point(3.0, -3.0)])
>>> list(it.getattr('y'))
[-1.0, -2.0, -3.0]

>>> it = xiter([Point(1.0, -1.0), Point(2.0, -2.0), Point(3.0, -3.0)])
>>> list(it.getattr('x', 'z', default=None))
[(1.0, None), (2.0, None), (3.0, None)]
getitem(*indices: typing.Union[int, str], default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[typing_extensions.Any][source]

Get provided indices data from each item in a sequence.

Equivalent to toolz.itertoolz.pluck(indices, self).

Keyword Arguments

default – returned value if the item does not contain an index with the provided value.

For detailed information check toolz.itertoolz.pluck() reference.

>>> it = xiter([('a', 1), ('b', 2), ('c', 3)])
>>> list(it.getitem(0))
['a', 'b', 'c']

>>> it = xiter([
...     dict(name="AA", age=20, country="US"),
...     dict(name="BB", age=30, country="UK"),
...     dict(name="CC", age=40, country="EU"),
...     dict(country="CH")
... ])
>>> list(it.getitem("name", "age", default=None))
[('AA', 20), ('BB', 30), ('CC', 40), (None, None)]
groupby(key: str, *other_keys: str, as_dict: bool = 'False') → gt4py.eve.utils.XIterable[tuple[typing_extensions.Any, list[T]]][source]
groupby(key: list[typing_extensions.Any], *, as_dict: bool = 'False') → gt4py.eve.utils.XIterable[tuple[typing_extensions.Any, list[T]]]
groupby(key: collections.abc.Callable[[gt4py.eve.utils.T], typing_extensions.Any], *, as_dict: bool = 'False') → gt4py.eve.utils.XIterable[tuple[typing_extensions.Any, list[T]]]

Group a sequence by a given key.

More or less equivalent to toolz.itertoolz.groupby(key, self) with some caveats.

The key argument is used in the following way:

  • if key is a callable, it will be passed directly to toolz.itertoolz.groupby() to compute an actual key value for each item in the sequence.

  • if key is a str or (multiple str args) they will be used as attributes names (operator.attrgetter()).

  • if key is a list of values, they will be used as index values for operator.itemgetter().

Keyword Arguments

as_dict – if True, it will return the groups dict instead of a XIterable instance over groups.items().

For detailed information check toolz.itertoolz.groupby() reference.

Examples

>>> it = xiter([(1.0, -1.0), (1.0,-2.0), (2.2, -3.0)])
>>> list(it.groupby([0]))
[(1.0, [(1.0, -1.0), (1.0, -2.0)]), (2.2, [(2.2, -3.0)])]

>>> data = [
...     {'x': 1.0, 'y': -1.0, 'z': 1.0},
...     {'x': 1.0, 'y': -2.0, 'z': 1.0},
...     {'x': 2.2, 'y': -3.0, 'z': 2.2}
... ]
>>> list(xiter(data).groupby(['x']))
[(1.0, [{'x': 1.0, 'y': -1.0, 'z': 1.0}, {'x': 1.0, 'y': -2.0, 'z': 1.0}]), (2.2, [{'x': 2.2, 'y': -3.0, 'z': 2.2}])]
>>> list(xiter(data).groupby(['x', 'z']))
[((1.0, 1.0), [{'x': 1.0, 'y': -1.0, 'z': 1.0}, {'x': 1.0, 'y': -2.0, 'z': 1.0}]), ((2.2, 2.2), [{'x': 2.2, 'y': -3.0, 'z': 2.2}])]

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y', 'z'])
>>> data = [Point(1.0, -2.0, 1.0), Point(1.0, -2.0, 1.0), Point(2.2, 3.0, 2.0)]
>>> list(xiter(data).groupby('x'))
[(1.0, [Point(x=1.0, y=-2.0, z=1.0), Point(x=1.0, y=-2.0, z=1.0)]), (2.2, [Point(x=2.2, y=3.0, z=2.0)])]
>>> list(xiter(data).groupby('x', 'z'))
[((1.0, 1.0), [Point(x=1.0, y=-2.0, z=1.0), Point(x=1.0, y=-2.0, z=1.0)]), ((2.2, 2.0), [Point(x=2.2, y=3.0, z=2.0)])]

>>> it = xiter(['Alice', 'Bob', 'Charlie', 'Dan', 'Edith', 'Frank'])
>>> list(it.groupby(len))
[(5, ['Alice', 'Edith', 'Frank']), (3, ['Bob', 'Dan']), (7, ['Charlie'])]
if_contains(*values: typing_extensions.Any) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using operator.contains() checks.

Equivalent to xiter(item for item in self if all(v in item for v in values)).

Examples

>>> it = xiter([None, (0, 1, 2), "a", (1, 2, 3), (2, 3, 4), "b"])
>>> list(it.if_contains(2))
[(0, 1, 2), (1, 2, 3), (2, 3, 4)]

>>> it = xiter([None, (0, 1, 2), "a", (1, 2, 3), (2, 3, 4), "b"])
>>> list(it.if_contains(1, 2))
[(0, 1, 2), (1, 2, 3)]
if_hasattr(*names: str) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using hasattr() checks.

Equivalent to filter(attrchecker(names), self).

Examples

>>> it = xiter([1, '2', 3.3, [4, 5], {6, 7}])
>>> list(it.if_hasattr('__len__'))
['2', [4, 5], {6, 7}]

>>> it = xiter([1, '2', 3.3, [4, 5], {6, 7}])
>>> list(it.if_hasattr('__len__', 'index'))
['2', [4, 5]]
if_in(collection: collections.abc.Collection[gt4py.eve.utils.T]) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using operator.contains() checks.

Equivalent to xiter(item for item in self if item in collection).

Examples

>>> it = xiter(range(8))
>>> list(it.if_in([0, 2, 4, 6]))
[0, 2, 4, 6]
if_is(obj: typing_extensions.Any) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using operator.is_() checks.

Equivalent to xiter(item for item in self if item is obj).

Examples

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is(None))
[None, None]

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is(1))
[1, 1]

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is(123456789))
[]
if_is_not(obj: typing_extensions.Any) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using negated operator.is_() checks.

Equivalent to xiter(item for item in self if item is not obj).

Examples

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is_not(None))
[1, 1, 123456789, 123456789]

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is_not(1))
[None, 123456789, None, 123456789]

>>> it = xiter([1, None, 1, 123456789, None, 123456789])
>>> list(it.if_is_not(123456789))
[1, None, 1, 123456789, None, 123456789]
if_isinstance(*types: type) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using isinstance() checks.

Equivalent to xiter(item for item in self if isinstance(item, types)).

Examples

>>> it = xiter([1, '2', 3.3, [4, 5], {6, 7}])
>>> list(it.if_isinstance(int, float))
[1, 3.3]
if_not_in(collection: collections.abc.Collection[gt4py.eve.utils.T]) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using negated operator.contains() checks.

Equivalent to xiter(item for item in self if item not in collection).

Examples

>>> it = xiter(range(8))
>>> list(it.if_not_in([0, 2, 4, 6]))
[1, 3, 5, 7]
if_not_isinstance(*types: type) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Filter elements using negated isinstance() checks.

Equivalent to xiter(item for item in self if not isinstance(item, types)).

Examples

>>> it = xiter([1, '2', 3.3, [4, 5], {6, 7}])
>>> list(it.if_not_isinstance(int, float))
['2', [4, 5], {6, 7}]
islice(__stop: int) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]
islice(__start: int, __stop: int, __step: int = 1) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T]

Select elements from an iterable.

Equivalent to itertools.islice(iterator, start, stop, step).

For detailed information check itertools.islice() reference.

Examples

>>> it = xiter(range(10))
>>> list(it.islice(2))
[0, 1]

>>> it = xiter(range(10))
>>> list(it.islice(2, 8))
[2, 3, 4, 5, 6, 7]

>>> it = xiter(range(10))
>>> list(it.islice(2, 8, 2))
[2, 4, 6]
iterator: collections.abc.Iterator[gt4py.eve.utils.T]
map(func: collections.abc.Callable) → gt4py.eve.utils.XIterable[typing_extensions.Any][source]

Apply a callable to every iterator element.

Equivalent to map(func, self).

For detailed information check map() reference.

Examples

>>> it = xiter(range(3))
>>> list(it.map(str))
['0', '1', '2']

>>> it = xiter(range(3))
>>> list(it.map(lambda x: -x).map(str))
['0', '-1', '-2']

If the callable requires additional arguments, lambda of functools.partial() functions can be used:

>>> def times(a, b):
...     return a * b
>>> times_2 = functools.partial(times, 2)
>>> it = xiter(range(4))
>>> list(it.map(lambda x: x + 1).map(times_2))
[2, 4, 6, 8]

Curried functions generated by toolz.curry() will also work as expected:

>>> @toolz.curry
... def mul(x, y):
...     return x * y
>>> it = xiter(range(4))
>>> list(it.map(lambda x: x + 1).map(mul(5)))
[5, 10, 15, 20]
partition(n: int, *, exact: bool = False, fill: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[tuple[T, ...]][source]

Partition iterator into tuples of length n (exact=True) or at most n (exact=False).

Equivalent to toolz.itertoolz.partition(n, self) or toolz.itertoolz.partition_all(n, self).

For detailed information check toolz.itertoolz.partition() and toolz.itertoolz.partition_all() reference.

Keyword Arguments

  • exact – if True, it will return tuples of length n. If False, the last tuple could have a smaller size if there are not enough items in the sequence.

  • fill – if provided together with exact=True, this value will be used to fill the last tuple until it has exactly length n.

Examples

>>> it = xiter(range(7))
>>> list(it.partition(3))
[(0, 1, 2), (3, 4, 5), (6,)]

>>> it = xiter(range(7))
>>> list(it.partition(3, exact=True))
[(0, 1, 2), (3, 4, 5)]

>>> it = xiter(range(7))
>>> list(it.partition(3, exact=True, fill=None))
[(0, 1, 2), (3, 4, 5), (6, None, None)]
product(other: Union[collections.abc.Iterable[gt4py.eve.utils.S], int]) → Union[gt4py.eve.utils.XIterable[tuple[T, S]], gt4py.eve.utils.XIterable[tuple[T, T]]][source]

Product of iterators.

Equivalent to itertools.product(it_a, it_b).

For detailed information check itertools.product() reference.

Examples

>>> it_a, it_b = xiter([0, 1]), xiter(['a', 'b'])
>>> list(it_a.product(it_b))
[(0, 'a'), (0, 'b'), (1, 'a'), (1, 'b')]

Product of an iterator with itself:

>>> it_a = xiter([0, 1])
>>> list(it_a.product(3))
[(0, 0, 0), (1, 1, 1)]
reduce(bin_op_func: collections.abc.Callable[[typing_extensions.Any, gt4py.eve.utils.T], typing_extensions.Any], *, init: Optional[typing_extensions.Any] = None) → typing_extensions.Any[source]

Reduce an iterator using a callable.

Equivalent to functools.reduce(bin_op_func, self, init).

Keyword Arguments

init – initial value for the reduction.

For detailed information check functools.reduce() reference.

Examples

>>> it = xiter(range(5))
>>> it.reduce((lambda accu, i: accu + i), init=0)
10

>>> it = xiter(['a', 'b', 'c', 'd', 'e'])
>>> sorted(it.reduce((lambda accu, item: (accu or set()) | {item} if item in 'aeiou' else accu)))
['a', 'e']
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: str, *, as_dict: Literal[False], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → gt4py.eve.utils.XIterable[tuple[str, S]][source]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: str, __attr_keys1: str, *attr_keys: str, as_dict: Literal[False], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → gt4py.eve.utils.XIterable[tuple[tuple[str, ...], S]]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: str, *, as_dict: Literal[True], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → dict[str, S]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: str, __attr_keys1: str, *attr_keys: str, as_dict: Literal[True], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → dict[tuple[str, ...], S]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: list[K], *, as_dict: Literal[False], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → gt4py.eve.utils.XIterable[tuple[K, S]]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: list[K], *, as_dict: Literal[True], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → dict[K, S]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: collections.abc.Callable[[gt4py.eve.utils.T], gt4py.eve.utils.K], *, as_dict: Literal[False], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → gt4py.eve.utils.XIterable[tuple[K, S]]
reduceby(bin_op_func: collections.abc.Callable[[gt4py.eve.utils.S, gt4py.eve.utils.T], gt4py.eve.utils.S], key: collections.abc.Callable[[gt4py.eve.utils.T], gt4py.eve.utils.K], *, as_dict: Literal[True], init: Union[gt4py.eve.utils.S, gt4py.eve.type_definitions.NothingType]) → dict[K, S]

Group a sequence by a given key and simultaneously perform a reduction inside the groups.

More or less equivalent to toolz.itertoolz.reduceby(key, bin_op_func, self, init) with some caveats.

The key argument is used in the following way:

  • if key is a callable, it will be passed directly to toolz.itertoolz.reduceby() to compute an actual key value for each item in the sequence.

  • if key is a str or (multiple str args) they will be used as attributes names (operator.attrgetter()).

  • if key is a list of values, they will be used as index values for operator.itemgetter().

Keyword Arguments

  • init – initial value for the reduction.

  • as_dict – if True, it will return the groups dict instead of a XIterable instance over groups.items().

For detailed information check toolz.itertoolz.reduceby() reference.

Examples

>>> it = xiter([(1.0, -1.0), (1.0,-2.0), (2.2, -3.0)])
>>> list(it.reduceby((lambda accu, _: accu + 1), [0], init=0))
[(1.0, 2), (2.2, 1)]

>>> data = [
...     {'x': 1.0, 'y': -1.0, 'z': 1.0},
...     {'x': 1.0, 'y': -2.0, 'z': 1.0},
...     {'x': 2.2, 'y': -3.0, 'z': 2.2}
... ]
>>> list(xiter(data).reduceby((lambda accu, _: accu + 1), ['x'], init=0))
[(1.0, 2), (2.2, 1)]
>>> list(xiter(data).reduceby((lambda accu, _: accu + 1), ['x', 'z'], init=0))
[((1.0, 1.0), 2), ((2.2, 2.2), 1)]

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y', 'z'])
>>> data = [Point(1.0, -2.0, 1.0), Point(1.0, -2.0, 1.0), Point(2.2, 3.0, 2.0)]
>>> list(xiter(data).reduceby((lambda accu, _: accu + 1), 'x', init=0))
[(1.0, 2), (2.2, 1)]
>>> list(xiter(data).reduceby((lambda accu, _: accu + 1), 'x', 'z', init=0))
[((1.0, 1.0), 2), ((2.2, 2.0), 1)]

>>> it = xiter(['Alice', 'Bob', 'Charlie', 'Dan', 'Edith', 'Frank'])
>>> list(it.reduceby(lambda nvowels, name: nvowels + sum(i in 'aeiou' for i in name), len, init=0))
[(5, 4), (3, 2), (7, 3)]
select(selectors: collections.abc.Iterable[bool]) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Return only the elements which have a corresponding element in selectors that evaluates to True.

Equivalent to itertools.compress(self, selectors).

For detailed information check itertools.compress() reference.

Examples

>>> it = xiter([1, 2, 3, 1, 3])
>>> list(it.select([True, False, 1, False, 0]))
[1, 3]
take_nth(n: int) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Take every nth item in sequence.

Equivalent to toolz.itertoolz.take_nth(n, self).

For detailed information check toolz.itertoolz.take_nth() reference.

Examples

>>> it = xiter(range(7))
>>> list(it.take_nth(3))
[0, 3, 6]
to_list() → list[T][source]

Expand iterator into a list.

Equivalent to list(self).

Examples

>>> it = xiter(range(5))
>>> it.to_list()
[0, 1, 2, 3, 4]
to_set() → set[T][source]

Expand iterator into a set.

Equivalent to set(self).

Examples

>>> it = xiter([1, 2, 3, 1, 3, -1])
>>> it.to_set()
{1, 2, 3, -1}
unique(*, key: typing.Union[<class 'gt4py.eve.type_definitions.NOTHING'>, collections.abc.Callable] = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[gt4py.eve.utils.T][source]

Return only unique elements of a sequence.

Equivalent to toolz.itertoolz.unique(self).

Keyword Arguments

key – callable computing the key to use per item in the sequence.

For detailed information check toolz.itertoolz.unique() reference.

Examples

>>> it = xiter([1, 2, 3, 1, 3])
>>> list(it.unique())
[1, 2, 3]

>>> it = xiter(['cat', 'mouse', 'dog', 'hen'])
>>> list(it.unique(key=len))
['cat', 'mouse']
unzip() → gt4py.eve.utils.XIterable[tuple[typing_extensions.Any, ...]][source]

Unzip iterator.

Equivalent to zip(*self).

For detailed information check zip() reference.

Examples

>>> it = xiter([('a', 1), ('b', 2), ('c', 3)])
>>> list(it.unzip())
[('a', 'b', 'c'), (1, 2, 3)]
zip(*others: collections.abc.Iterable, fill: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → gt4py.eve.utils.XIterable[tuple[T, S]][source]

Zip iterators.

Equivalent to zip(self, *others) or itertools.zip_longest(self, *others, fillvalue=fill).

Keyword Arguments

fill – value used to fill the result for sequences with fewer items.

For detailed information check zip() and itertools.zip_longest() reference.

Examples

>>> it_a = xiter(range(3))
>>> it_b = ['a', 'b', 'c']
>>> list(it_a.zip(it_b))
[(0, 'a'), (1, 'b'), (2, 'c')]

>>> it = xiter(range(3))
>>> list(it.zip(['a', 'b', 'c'], ['A', 'B', 'C']))
[(0, 'a', 'A'), (1, 'b', 'B'), (2, 'c', 'C')]

>>> it = xiter(range(5))
>>> list(it.zip(['a', 'b', 'c'], ['A', 'B', 'C'], fill=None))
[(0, 'a', 'A'), (1, 'b', 'B'), (2, 'c', 'C'), (3, None, None), (4, None, None)]
gt4py.eve.utils.as_xiter(iterator_func: collections.abc.Callable[[gt4py.eve.utils.P], collections.abc.Iterable[gt4py.eve.utils.T]]) → collections.abc.Callable[[gt4py.eve.utils.P], gt4py.eve.utils.XIterable[gt4py.eve.utils.T]][source]

Wrap the provided callable to convert its output in a XIterable.

gt4py.eve.utils.attrchecker(*names: str) → collections.abc.Callable[[typing_extensions.Any], bool][source]

Return a callable object that checks if operand has all names attributes.

Examples

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y'])
>>> point = Point(1.0, 2.0)
>>> checker = attrchecker('x')
>>> checker(point)
True

>>> checker = attrchecker('x', 'y')
>>> checker(point)
True

>>> checker = attrchecker('z')
>>> checker(point)
False
gt4py.eve.utils.attrgetter_(*names: str, default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → collections.abc.Callable[[typing_extensions.Any], typing_extensions.Any][source]

Return a callable object that gets names attributes from its operand.

Similar to operator.attrgetter() but accepts a default value.

Examples

>>> from collections import namedtuple
>>> Point = namedtuple('Point', ['x', 'y'])
>>> point = Point(1.0, 2.0)
>>> getter = attrgetter_('x')
>>> getter(point)
1.0

>>> import math
>>> getter = attrgetter_('z', default=math.nan)
>>> getter(point)
nan

>>> import math
>>> getter = attrgetter_('x', 'y', 'z', default=math.nan)
>>> getter(point)
(1.0, 2.0, nan)
gt4py.eve.utils.content_hash(*args: Any, hash_algorithm: str | xtyping.HashlibAlgorithm | None = None) → str[source]

Stable content-based hash function using instance serialization data.

It provides a customizable hash function for any kind of data. Unlike the builtin hash function, it is stable (same hash value across interpreter reboots) and it does not use hash customizations on user classes (it uses pickle internally to get a byte stream).

Parameters

hash_algorithm – object implementing the hash algorithm interface from hashlib or canonical name (str) of the hash algorithm as defined in hashlib. Defaults to xxhash.xxh64.

gt4py.eve.utils.ddiff

Shortcut for deepdiff.DeepDiff.

Check https://zepworks.com/deepdiff/current/diff.html for more info.

gt4py.eve.utils.dhash(obj: typing_extensions.Any, **kwargs: typing_extensions.Any) → str[source]

Shortcut for deepdiff.deephash.DeepHash.

Check https://zepworks.com/deepdiff/current/deephash.html for more info.

gt4py.eve.utils.getitem_(obj: typing_extensions.Any, key: typing_extensions.Any, default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → typing_extensions.Any[source]

Return the value of obj at index key.

Similar to operator.getitem() but accepts a default value.

Examples

>>> d = {'a': 1}
>>> getitem_(d, 'a')
1

>>> d = {'a': 1}
>>> getitem_(d, 'b', 'default')
'default'
gt4py.eve.utils.is_noninstantiable(cls: type[_T]) → bool[source]

Return True if model is a non-instantiable class.

gt4py.eve.utils.isinstancechecker(type_info: Union[type, collections.abc.Iterable[type]]) → collections.abc.Callable[[typing_extensions.Any], bool][source]

Return a callable object that checks if operand is an instance of type_info.

Examples

>>> checker = isinstancechecker((int, str))
>>> checker(3)
True
>>> checker('3')
True
>>> checker(3.3)
False
gt4py.eve.utils.itemgetter_(key: typing_extensions.Any, default: typing_extensions.Any = <class 'gt4py.eve.type_definitions.NOTHING'>) → collections.abc.Callable[[typing_extensions.Any], typing_extensions.Any][source]

Return a callable object that gets key item from its operand.

Similar to operator.itemgetter() but accepts a default value.

Examples

>>> d = {'a': 1}
>>> getter = itemgetter_('a')
>>> getter(d)
1

>>> d = {'a': 1}
>>> getter = itemgetter_('b', 'default')
>>> getter(d)
'default'
gt4py.eve.utils.noninstantiable(cls: type[_T]) → type[_T][source]

Make a class without abstract method non-instantiable (subclasses should be instantiable).

gt4py.eve.utils.optional_lru_cache(func: Optional[collections.abc.Callable[[gt4py.eve.utils._P], gt4py.eve.utils._T]] = None, *, maxsize: Optional[int] = 128, typed: bool = False) → Union[collections.abc.Callable[[gt4py.eve.utils._P], gt4py.eve.utils._T], collections.abc.Callable[[collections.abc.Callable[[gt4py.eve.utils._P], gt4py.eve.utils._T]], collections.abc.Callable[[gt4py.eve.utils._P], gt4py.eve.utils._T]]][source]

Wrap functools.lru_cache() to fall back to the original function if arguments are not hashable.

Examples

>>> @optional_lru_cache(typed=True)
... def func(a, b):
...     print(f"Inside func({a}, {b})")
...     return a + b
...
>>> print(func(1, 3))
Inside func(1, 3)
4
>>> print(func(1, 3))
4
>>> print(func([1], [3]))
Inside func([1], [3])
[1, 3]
>>> print(func([1], [3]))
Inside func([1], [3])
[1, 3]

Notes

Based on typing._tp_cache().

gt4py.eve.utils.pprint_ddiff(old: typing_extensions.Any, new: typing_extensions.Any, *, pprint_opts: Optional[dict[str, typing_extensions.Any]] = None, **kwargs: typing_extensions.Any) → None[source]

Pretty printing of deepdiff.DeepDiff objects.

Keyword Arguments

pprint_opts – kwargs dict with options for pprint.pprint.

gt4py.eve.utils.register_subclasses(*subclasses: type) → collections.abc.Callable[[type], type][source]

Class decorator to automatically register virtual subclasses.

Examples

>>> import abc
>>> class MyVirtualSubclassA:
...     pass
...
>>> class MyVirtualSubclassB:
...    pass
...
>>> @register_subclasses(MyVirtualSubclassA, MyVirtualSubclassB)
... class MyBaseClass(abc.ABC):
...    pass
...
>>> issubclass(MyVirtualSubclassA, MyBaseClass) and issubclass(MyVirtualSubclassB, MyBaseClass)
True
gt4py.eve.utils.xiter

alias of gt4py.eve.utils.XIterable

gt4py.eve.visitors module

Visitor classes to work with IR trees.

class gt4py.eve.visitors.NodeTranslator[source]

Bases: gt4py.eve.visitors.NodeVisitor

Special NodeVisitor to translate nodes and trees.

A NodeTranslator instance will walk the tree exactly as a regular NodeVisitor while building an output tree using the return values of the visitor methods. If the return value is eve.NOTHING, the node will be removed from its location in the output tree, otherwise it will be replaced with this new value. The default visitor method (generic_visit()) returns a deepcopy of the original node.

Keep in mind that if the node you’re operating on has child nodes you must either transform the child nodes yourself or call the generic_visit() method for the node first.

Usually you use a NodeTranslator like this:

output_node = YourTranslator.apply(input_node)

Notes

Check NodeVisitor documentation for more details.

generic_visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
class gt4py.eve.visitors.NodeVisitor[source]

Bases: object

Simple node visitor class based on ast.NodeVisitor.

A NodeVisitor instance walks a node tree and calls a visitor function for every item found. This class is meant to be subclassed, with the subclass adding visitor methods.

Visitor functions for tree elements are named with a standard pattern: visit_ + class name of the node. Thus, the visitor function for a BinOpExpr node class should be called visit_BinOpExpr. If no visitor function exists for a specific node, the dispatcher mechanism looks for the visitor of each one of its parent classes in the order define by the class’ __mro__ attribute. Finally, if no visitor function has been found, the generic_visit visitor is used instead. A concise summary of the steps followed to find an appropriate visitor function is:

  1. A self.visit_NODE_CLASS_NAME() method where NODE_CLASS_NAME matches type(node).__name__.

  2. A self.visit_NODE_BASE_CLASS_NAME() method where NODE_BASE_CLASS_NAME matches base.__name__, and base is one of the node base classes (evaluated following the order given in type(node).__mro__).

  3. self.generic_visit().

This dispatching mechanism is implemented in the main visit() method and can be overriden in subclasses. Therefore, a simple way to extend the behavior of a visitor is by inheriting from lightweight trait classes with a custom visit() method, which wraps the call to the superclass’ visit() and adds extra pre and post visit logic. Check eve.traits for further information.

Note that return values are not forwarded to the caller in the default generic_visit() implementation. If you want to return a value from a nested node in the tree, make sure all the intermediate nodes explicitly return children values.

The recommended idiom to use and define NodeVisitors can be summarized as:

  • Inside visitor functions:

    • call self.visit(child_node) to visit children.

    • call self.generic_visit(node) to continue the tree traversal in the usual way.

  • Define an apply() classmethod as a shortcut to create an instance and start the visit:

    class Visitor(NodeVisitor)
    @classmethod
    def apply(cls, tree, init_var, foo, bar=5, **kwargs):
        instance = cls(init_var)
        return instance(tree, foo=foo, bar=bar, **kwargs)

    ...

result = Visitor.apply(...)

  • If the visitor has internal state, make sure visitor instances are never reused or clean up the state at the end.

Notes

If you want to apply changes to nodes during the traversal, use the NodeMutator subclass, which handles correctly structural modifications of the visited tree.

generic_visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]

Module contents

Eve framework with general utils for development of DSL toolchains in Python.

The internal dependencies between modules are the following (each module depends on some of the previous ones):

  1. extended_typing

  2. exceptions, pattern_matching, type_definitions

  3. utils

  4. type_validation

  5. datamodels

  6. trees

  7. concepts

  8. visitors

  9. traits

  10. codegen

class gt4py.eve.AnnexManager[source]

Bases: object

register: ClassVar[dict[str, typing_extensions.Any]] = {'symtable': (True, dict[str, gt4py.eve.concepts.Node], [<class 'gt4py.eve.traits.SymbolTableTrait'>, <class 'gt4py.eve.traits.SymbolRefsValidatorTrait'>])}
classmethod register_user()[source]
class gt4py.eve.ConstrainedStr(value: str)[source]

Bases: str

Base string subclass allowing to restrict values to those satisfying a regular expression.

Subclasses should define the specific constraint pattern in the regex class keyword argument or as class variable.

Examples

>>> class OnlyLetters(ConstrainedStr, regex=re.compile(r"^[a-zA-Z]*$")): pass
>>> OnlyLetters("aabbCC")
OnlyLetters('aabbCC')

>>> OnlyLetters("aabbCC33")
Traceback (most recent call last):
    ...
ValueError: OnlyLetters('aabbCC33') does not satisfies RE constraint re.compile('^[a-zA-Z]*$').
regex: ClassVar[re.Pattern]
class gt4py.eve.DataModel[source]

Bases: object

Base class to automatically convert any subclass into a Data Model.

Inheriting from this class is equivalent to apply the datamodel() decorator to a class, except that the slots option is always False (since it generates a new class) and all descendants will be also converted automatically in Data Models with the same options of the parent class (which does not happen when explicitly applying the decorator).

See datamodel() for the description of the parameters.

class gt4py.eve.Enum(value)[source]

Bases: object

Generic enumeration.

Derive from this class to define new enumerations.

_generate_next_value_(start, count, last_values)[source]

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_value: the last value assigned or None

name

The name of the Enum member.

value

The value of the Enum member.

class gt4py.eve.FrozenModel[source]

Bases: gt4py.eve.datamodels.core.DataModel

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.FrozenNode[source]

Bases: gt4py.eve.concepts.Node

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.GenericDataModel[source]

Bases: gt4py.eve.datamodels.core.DataModel

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.GenericNode[source]

Bases: gt4py.eve.datamodels.core.GenericDataModel, gt4py.eve.concepts.Node

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.IntEnum(value)[source]

Bases: int, enum.Enum

Enum where members are also (and must be) ints

_generate_next_value_(start, count, last_values)

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_value: the last value assigned or None

class gt4py.eve.NOTHING[source]

Bases: object

Marker to avoid confusion with None in contexts where None could be a valid value.

class gt4py.eve.Node[source]

Bases: gt4py.eve.datamodels.core.DataModel, gt4py.eve.trees.Tree

Base class representing a node in a syntax tree.

Implemented as a eve.datamodels.DataModel with some extra features.

Field values should be either:

  • builtin types: bool, bytes, int, float, str

  • enum.Enum types

  • other Node subclasses

  • other eve.datamodels.DataModel subclasses

  • supported collections (List, Dict, Set)

    of any of the previous items

The annex attribute is used to dynamically add data to a node, even to frozen classes. Data in the annex do not affect the hash or equality comparisons of the node, since it is not really a field. Thus, visitors and pipeline passes can freely attach computed attributes into the instance annex.

property annex: gt4py.eve.utils.Namespace
bfs_walk_items(*, __key__: Optional[Union[int, str]] = None, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs by tree levels (Breadth-First Search).

bfs_walk_values(*, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]]

Create a tree traversal iterator of values by tree levels (Breadth-First Search).

copy(update: dict[str, typing_extensions.Any]) → gt4py.eve.concepts._T[source]
iter_children_items() → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]][source]
iter_children_values() → collections.abc.Iterable[source]
post_walk_items(*, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a post-order tree traversal iterator of (key, value) pairs.

post_walk_values() → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a post-order tree traversal iterator of values.

pre_walk_items(*, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a pre-order tree traversal iterator of (key, value) pairs.

pre_walk_values() → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a pre-order tree traversal iterator of values.

classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

walk_items(traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs.

walk_values(traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[typing_extensions.Any]

Create a tree traversal iterator of values.

class gt4py.eve.NodeTranslator[source]

Bases: gt4py.eve.visitors.NodeVisitor

Special NodeVisitor to translate nodes and trees.

A NodeTranslator instance will walk the tree exactly as a regular NodeVisitor while building an output tree using the return values of the visitor methods. If the return value is eve.NOTHING, the node will be removed from its location in the output tree, otherwise it will be replaced with this new value. The default visitor method (generic_visit()) returns a deepcopy of the original node.

Keep in mind that if the node you’re operating on has child nodes you must either transform the child nodes yourself or call the generic_visit() method for the node first.

Usually you use a NodeTranslator like this:

output_node = YourTranslator.apply(input_node)

Notes

Check NodeVisitor documentation for more details.

generic_visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
class gt4py.eve.NodeVisitor[source]

Bases: object

Simple node visitor class based on ast.NodeVisitor.

A NodeVisitor instance walks a node tree and calls a visitor function for every item found. This class is meant to be subclassed, with the subclass adding visitor methods.

Visitor functions for tree elements are named with a standard pattern: visit_ + class name of the node. Thus, the visitor function for a BinOpExpr node class should be called visit_BinOpExpr. If no visitor function exists for a specific node, the dispatcher mechanism looks for the visitor of each one of its parent classes in the order define by the class’ __mro__ attribute. Finally, if no visitor function has been found, the generic_visit visitor is used instead. A concise summary of the steps followed to find an appropriate visitor function is:

  1. A self.visit_NODE_CLASS_NAME() method where NODE_CLASS_NAME matches type(node).__name__.

  2. A self.visit_NODE_BASE_CLASS_NAME() method where NODE_BASE_CLASS_NAME matches base.__name__, and base is one of the node base classes (evaluated following the order given in type(node).__mro__).

  3. self.generic_visit().

This dispatching mechanism is implemented in the main visit() method and can be overriden in subclasses. Therefore, a simple way to extend the behavior of a visitor is by inheriting from lightweight trait classes with a custom visit() method, which wraps the call to the superclass’ visit() and adds extra pre and post visit logic. Check eve.traits for further information.

Note that return values are not forwarded to the caller in the default generic_visit() implementation. If you want to return a value from a nested node in the tree, make sure all the intermediate nodes explicitly return children values.

The recommended idiom to use and define NodeVisitors can be summarized as:

  • Inside visitor functions:

    • call self.visit(child_node) to visit children.

    • call self.generic_visit(node) to continue the tree traversal in the usual way.

  • Define an apply() classmethod as a shortcut to create an instance and start the visit:

    class Visitor(NodeVisitor)
    @classmethod
    def apply(cls, tree, init_var, foo, bar=5, **kwargs):
        instance = cls(init_var)
        return instance(tree, foo=foo, bar=bar, **kwargs)

    ...

result = Visitor.apply(...)

  • If the visitor has internal state, make sure visitor instances are never reused or clean up the state at the end.

Notes

If you want to apply changes to nodes during the traversal, use the NodeMutator subclass, which handles correctly structural modifications of the visited tree.

generic_visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
class gt4py.eve.NothingType[source]

Bases: type

Metaclass of NOTHING setting its bool value to False.

class gt4py.eve.SourceLocation(line: int, column: int, source: str, *, end_line: Optional[int] = None, end_column: Optional[int] = None)[source]

Bases: object

Source code location (line, column, source).

column: int
end_column: Optional[int]
end_line: Optional[int]
classmethod from_AST(ast_node: ast.AST, source: Optional[str] = None) → gt4py.eve.concepts.SourceLocation[source]
line: int
source: str
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.SourceLocationGroup(*locations: gt4py.eve.concepts.SourceLocation, context: Optional[Union[str, tuple[str, ...]]] = None)[source]

Bases: object

A group of merged source code locations (with optional info).

context: Optional[Union[str, tuple[str, ...]]]
locations: tuple[gt4py.eve.concepts.SourceLocation, ...]
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.StrEnum(value)[source]

Bases: str, enum.Enum

enum.Enum subclass whose members are considered as real strings.

_generate_next_value_(start, count, last_values)

Generate the next value when not given.

name: the name of the member start: the initial start value or None count: the number of existing members last_value: the last value assigned or None

class gt4py.eve.SymbolName(value: str)[source]

Bases: gt4py.eve.type_definitions.ConstrainedStr

String value containing a valid symbol name for typical programming conventions.

regex: ClassVar[re.Pattern] = re.compile('^[a-zA-Z_]\\w*$')
class gt4py.eve.SymbolRef(value: str)[source]

Bases: gt4py.eve.type_definitions.ConstrainedStr

Reference to a symbol name.

regex: ClassVar[re.Pattern] = re.compile('^[a-zA-Z_]\\w*$')
class gt4py.eve.SymbolTableTrait[source]

Bases: object

Node trait adding an automatically created symbol table to the parent node.

The actual symbol table dict will be stored in the annex.symtable attribute. To inject extra symbol definitions, add the nodes to a class attribute called _NODE_SYMBOLS_.

class SymbolsCollector[source]

Bases: gt4py.eve.visitors.NodeVisitor

classmethod apply(node: gt4py.eve.concepts.Node) → dict[str, gt4py.eve.concepts.Node][source]
visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
visit_Node(node: gt4py.eve.concepts.Node, /) → None[source]
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.VType(name: str)[source]

Bases: gt4py.eve.datamodels.core.FrozenModel

name: str
classmethod update_forward_refs(localns: Optional[dict[str, typing_extensions.Any]] = None) → type[_DataModelT]

Update Data Model class meta-information replacing forwarded type annotations with actual types.

Parameters

localns – locals dict used in the evaluation of the annotations (globals are automatically taken from model.__module__).

Returns

The provided class (so it can be used as a decorator too).

class gt4py.eve.ValidatedSymbolTableTrait[source]

Bases: gt4py.eve.traits.SymbolRefsValidatorTrait, gt4py.eve.traits.SymbolTableTrait

Node trait adding an automatically created and validated symbol table.

It is just the combination of the SymbolTableTrait and SymbolRefsValidatorTrait traits.

class gt4py.eve.VisitorWithSymbolTableTrait[source]

Bases: gt4py.eve.visitors.NodeVisitor

Visitor trait to update or add the symtable to kwargs in the visitor calls.

Visitors inhering from this trait will automatically pass the active symbol table to visitor methods as the ‘symtable’ keyword argument.

visit(node: Union[gt4py.eve.concepts.NodeT, list[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], dict[typing_extensions.Any, Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]], set[Union[NodeT, bool, bytes, int, float, str, enum.IntEnum, gt4py.eve.type_definitions.StrEnum]]], **kwargs: typing_extensions.Any) → typing_extensions.Any[source]
gt4py.eve.bfs_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a tree traversal iterator of (key, value) pairs by tree levels (Breadth-First Search).

gt4py.eve.bfs_walk_values(node: gt4py.eve.trees.TreeLike, *, __queue__: Optional[list] = None) → collections.abc.Iterable[tuple[Union[int, str], typing_extensions.Any]]

Create a tree traversal iterator of values by tree levels (Breadth-First Search).

gt4py.eve.concretize(datamodel_cls: type[GenericDataModelT], /, *type_args: type, class_name: Optional[str] = None, module: Optional[str] = None, support_pickling: bool = True, overwrite_definition: bool = True) → type[DataModelT][source]

Generate a new concrete subclass of a generic Data Model.

Parameters

  • datamodel_cls – Generic Data Model to be subclassed.

  • type_args – Type definitions replacing the TypeVars in datamodel_cls.__parameters__.

Keyword Arguments

  • class_name – Name of the new concrete class. The default value is the same of the generic Data Model replacing the TypeVars by the provided type_args in the name.

  • module – Value of the __module__ attribute of the new class. The default value is the name of the module containing the generic Data Model.

  • support_pickling – If True, support for pickling will be added by actually inserting the new class into the target module.

  • overwrite_definition – If True, a previous definition of the class in the target module will be overwritten.

gt4py.eve.datamodel(cls: Optional[Type[_T]] = None, /, *, repr: bool = True, eq: bool = True, order: bool = False, unsafe_hash: bool = False, frozen: bool | Literal['strict'] = False, match_args: bool = True, kw_only: bool = False, slots: bool = False, coerce: bool = False, generic: bool = False, type_validation_factory: Optional[FieldTypeValidatorFactory] = <function field_type_validator_factory.<locals>._field_type_validator_factory>) → Union[Type[_T], Callable[[Type[_T]], Type[_T]]][source]

Add generated special methods to classes according to the specified attributes (class decorator).

It converts the class to an attrs with some extra features. Adding strict type validation functions for the fields is done by means of the type_validation_factory argument, falling back to the default factory

(DefaultFieldTypeValidatorFactory). The generated field type

validators are generated by using PEP 526 __annotations__ to determine field types and creating validation functions for them.

Parameters

cls – Original class definition.

Keyword Arguments

  • repr – If True (default), a __repr__() method will be generated if it does not overwrite a custom implementation defined in this class (not inherited).

  • eq – If True (default), __eq__() and __ne__() methods will be generated if they do not overwrite custom implementations defined in this class (not inherited). The generated method compares the class as if it were a tuple of its fields, but both instances in the comparison must be of identical type.

  • order – If True (default is False), add __lt__(), __le__(), __gt__(), and __ge__() methods that behave like eq above and allow instances to be ordered. If None mirror value of eq.

  • unsafe_hash – If False, a __hash__() method is generated in a safe way according to how eq and frozen are set, or set to None (disabled) otherwise. If True, a __hash__() method is generated anyway (use with care). See dataclasses.dataclass() for the complete explanation (or other sources like: https://hynek.me/articles/hashes-and-equality/).

  • frozen – If True (default is False), assigning to fields will generate an exception. This emulates read-only frozen instances. The __setattr__() and __delattr__() methods should not be defined in the class.

  • match_args – If True (default) and __match_args__ is not already defined in the class, set __match_args__ on the class to support PEP 634 (Structural Pattern Matching). It is a tuple of all positional-only __init__ parameter names on Python 3.10 and later. Ignored on older Python versions.

  • kw_only – If True (default is False), make all fields keyword-only in the generated __init__ (if init is False, this parameter is ignored).

  • slots – slots: If True (the default is False), __slots__ attribute will be generated and a new slotted class will be returned instead of the original one.

  • coerce – If True (default is False), an automatic type converter will be generated for all fields.

  • generic – If True (default is False) the class should be a Generic[] class, and the generated Data Model will support creation of new Data Model subclasses when using concrete types as arguments of DataModelClass[some_concret_type].

  • type_validation_factory – Type validation factory used to build the field type validators. If None, type validators will not be generators.

gt4py.eve.field(*, default: Any = <class 'gt4py.eve.type_definitions.NOTHING'>, default_factory: Optional[Callable[[], Any]] = None, init: bool = True, repr: bool = True, hash: Optional[bool] = None, compare: bool = True, metadata: Optional[Mapping[Any, Any]] = None, kw_only: bool = False, converter: Callable[[Any], Any] | Literal['coerce'] | None = None, validator: AttrsValidator | FieldValidator | Sequence[AttrsValidator | FieldValidator] | None = None) → Any[source]

Define a new attribute on a class with advanced options.

Keyword Arguments

  • default – If provided, this will be the default value for this field. This is needed because the field() call itself replaces the normal position of the default value.

  • default_factory – If provided, it must be a zero-argument callable that will be called when a default value is needed for this field. Among other purposes, this can be used to specify fields with mutable default values. It is an error to specify both default and default_factory.

  • init – If True (default), this field is included as a parameter to the generated __init__() method.

  • repr – If True (default), this field is included in the string returned by the generated __repr__() method.

  • hash – This can be a bool or None (default). If True, this field is included in the generated __hash__() method. If None, use the value of compare, which would normally be the expected behavior: a field should be considered in the hash if it is used for comparisons. Setting this value to anything other than None is discouraged.

  • compare – If True (default), this field is included in the generated equality and comparison methods (__eq__(), __gt__(), et al.).

  • metadata – An arbitrary mapping, not used at all by Data Models, and provided only as a third-party extension mechanism. Multiple third-parties can each have their own key, to use as a namespace in the metadata.

  • kw_only – If True (default is False), make this field keyword-only in the generated __init__ (if init is False, this parameter is ignored).

  • converter – Callable that is automatically called to convert attribute’s value. It is given the passed-in value, and the returned value will be used as the new value of the attribute before being passed to the validator, if any. If "coerce" is passed, a naive coercer converter will be generated. The automatic converter basically calls the constructor of the type indicated in the type hint, so it is assumed that new instances of this type can be created like type_name(value). For collection types, there is not attempt to convert its items, only the collection type.

  • validator – FieldValidator or list of FieldValidators to be used with this field. (Note that validators can also be set using decorator notation).

Examples

>>> from typing import List
>>> @datamodel
... class C:
...     mylist: List[int] = field(default_factory=lambda : [1, 2, 3])
>>> c = C()
>>> c.mylist
[1, 2, 3]
gt4py.eve.frozenmodel(cls: Optional[Type[_T]] = None, /, *, repr: bool = True, eq: bool = True, order: bool = False, unsafe_hash: bool = False, frozen: bool | Literal['strict'] = True, match_args: bool = True, kw_only: bool = False, slots: bool = False, coerce: bool = False, generic: bool = False, type_validation_factory: Optional[FieldTypeValidatorFactory] = <function field_type_validator_factory.<locals>._field_type_validator_factory>) → Union[Type[_T], Callable[[Type[_T]], Type[_T]]]

Add generated special methods to classes according to the specified attributes (class decorator).

It converts the class to an attrs with some extra features. Adding strict type validation functions for the fields is done by means of the type_validation_factory argument, falling back to the default factory

(DefaultFieldTypeValidatorFactory). The generated field type

validators are generated by using PEP 526 __annotations__ to determine field types and creating validation functions for them.

Parameters

cls – Original class definition.

Keyword Arguments

  • repr – If True (default), a __repr__() method will be generated if it does not overwrite a custom implementation defined in this class (not inherited).

  • eq – If True (default), __eq__() and __ne__() methods will be generated if they do not overwrite custom implementations defined in this class (not inherited). The generated method compares the class as if it were a tuple of its fields, but both instances in the comparison must be of identical type.

  • order – If True (default is False), add __lt__(), __le__(), __gt__(), and __ge__() methods that behave like eq above and allow instances to be ordered. If None mirror value of eq.

  • unsafe_hash –

    If False, a __hash__() method is generated in a safe way according to how eq and frozen are set, or set to None (disabled) otherwise. If True, a __hash__() method is generated anyway (use with care). See dataclasses.dataclass() for the complete explanation (or other sources like: https://hynek.me/articles/hashes-and-equality/).

  • frozen – If True (default is False), assigning to fields will generate an exception. This emulates read-only frozen instances. The __setattr__() and __delattr__() methods should not be defined in the class.

  • match_args – If True (default) and __match_args__ is not already defined in the class, set __match_args__ on the class to support PEP 634 (Structural Pattern Matching). It is a tuple of all positional-only __init__ parameter names on Python 3.10 and later. Ignored on older Python versions.

  • kw_only – If True (default is False), make all fields keyword-only in the generated __init__ (if init is False, this parameter is ignored).

  • slots – slots: If True (the default is False), __slots__ attribute will be generated and a new slotted class will be returned instead of the original one.

  • coerce – If True (default is False), an automatic type converter will be generated for all fields.

  • generic – If True (default is False) the class should be a Generic[] class, and the generated Data Model will support creation of new Data Model subclasses when using concrete types as arguments of DataModelClass[some_concret_type].

  • type_validation_factory – Type validation factory used to build the field type validators. If None, type validators will not be generators.

gt4py.eve.post_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a post-order tree traversal iterator of (key, value) pairs.

gt4py.eve.post_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a post-order tree traversal iterator of values.

gt4py.eve.pre_walk_items(node: gt4py.eve.trees.TreeLike, *, __key__: Optional[Union[int, str]] = None) → collections.abc.Iterable[tuple[Union[int, str, NoneType], typing_extensions.Any]]

Create a pre-order tree traversal iterator of (key, value) pairs.

gt4py.eve.pre_walk_values(node: gt4py.eve.trees.TreeLike) → collections.abc.Iterable[tuple[typing_extensions.Any]]

Create a pre-order tree traversal iterator of values.

gt4py.eve.register_annex_user()
gt4py.eve.walk_items(node: gt4py.eve.trees.TreeLike, traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[tuple[Union[int, str, NoneType], typing_extensions.Any]][source]

Create a tree traversal iterator of (key, value) pairs.

gt4py.eve.walk_values(node: gt4py.eve.trees.TreeLike, traversal_order: gt4py.eve.trees.TraversalOrder = TraversalOrder.PRE_ORDER) → gt4py.eve.utils.XIterable[typing_extensions.Any][source]

Create a tree traversal iterator of values.