Tag Interface

pytools.tag.check_tag_uniqueness(tags: FrozenSet[pytools.tag.Tag])

Ensure that tags obeys the rules set forth in UniqueTag. If not, raise NonUniqueTagError. If any tags are not subclasses of Tag, a TypeError will be raised.

Returns

tags

class pytools.tag.Taggable(tags: FrozenSet[pytools.tag.Tag] = frozenset({}))

Parent class for objects with a tags attribute.

tags

A frozenset of Tag instances

__init__(tags: FrozenSet[pytools.tag.Tag] = frozenset({}))

Constructor for all objects that possess a tags attribute.

Parameters

tags – a frozenset of Tag objects. Tags can be modified via the tagged() and without_tags() routines. Input checking of tags should be performed before creating a Taggable instance, using check_tag_uniqueness().

copy(**kwargs: Any) → pytools.tag.T_co

Returns of copy of self with the specified tags. This method should be overridden by subclasses.

tagged(tags: Optional[Union[Iterable[pytools.tag.Tag], pytools.tag.Tag]]) → pytools.tag.T_co

Return a copy of self with the specified tag or tags unioned. If tags is a pytools.tag.UniqueTag and other tags of this type are already present, an error is raised Assumes self.copy(tags=<NEW VALUE>) is implemented.

Parameters

tags – An instance of Tag or an iterable with instances therein.

without_tags(tags: Optional[Union[Iterable[pytools.tag.Tag], pytools.tag.Tag]], verify_existence: bool = True) → pytools.tag.T_co

Return a copy of self without the specified tags. self.copy(tags=<NEW VALUE>) is implemented.

Parameters

• tags – An instance of Tag or an iterable with instances therein.

• verify_existence – If set to True, this method raises an exception if not all tags specified for removal are present in the original set of tags. Default True.

New in version 2021.1.

class pytools.tag.Tag

Generic metadata, applied to, among other things, pytato Arrays.

tag_name

A fully qualified DottedName that reflects the class name of the tag.

Instances of this type must be immutable, hashable, picklable, and have a reasonably concise __repr__() of the form dotted.name(attr1=value1, attr2=value2). Positional arguments are not allowed.

__repr__()

Return repr(self).

class pytools.tag.UniqueTag

A superclass for tags that are unique on each Taggable.

Each instance of Taggable may have no more than one instance of each subclass of UniqueTag in its set of tags. Multiple UniqueTag instances of different (immediate) subclasses are allowed.

Supporting Functionality

class pytools.tag.DottedName(name_parts: Tuple[str, ...])

name_parts

A tuple of strings, each of which is a valid Python identifier. No name part may start with a double underscore.

The name (at least morally) exists in the name space defined by the Python module system. It need not necessarily identify an importable object.

classmethod from_class(argcls: Any) → pytools.tag.DottedName

class pytools.tag.NonUniqueTagError

Raised when a Taggable object is instantiated with more than one UniqueTag instances of the same subclass in its set of tags.

Internal stuff that is only here because the documentation tool wants it

class pytools.tag.T_co

A covariant type variable used in, e.g. Taggable.copy().