Tag Interface

pytools.tag.check_tag_uniqueness(tags: FrozenSet[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[Tag] = frozenset({}))

Parent class for objects with a tags attribute.

tags

A frozenset of Tag instances

__init__(tags: FrozenSet[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().

_with_new_tags(tags: FrozenSet[Tag]) → _Self_Taggable

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

tagged(tags: Iterable[Tag] | Tag | None) → _Self_Taggable

Return a copy of self with the specified tag or tags added to the set of tags. If the resulting set of tags violates the rules on pytools.tag.UniqueTag, an error is raised.

Parameters:

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

without_tags(tags: Iterable[Tag] | Tag | None, verify_existence: bool = True) → _Self_Taggable

Return a copy of self without the specified tags.

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.

tags_of_type(tag_t: Type[TagT]) → FrozenSet[TagT]

Returns self’s tags of type tag_t.

tags_not_of_type(tag_t: Type[TagT]) → FrozenSet[Tag]

Returns self’s tags that are not of type tag_t.

Added 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.

class pytools.tag.IgnoredForEqualityTag

A superclass for tags that are ignored when testing equality of instances of Taggable.

When testing equality of two instances of Taggable, the equality of the tags of both instances is tested after removing all instances of IgnoredForEqualityTag. Instances of IgnoredForEqualityTag are removed for hashing instances of Taggable.

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) → 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.TagT

A type variable with lower bound Tag.

class pytools.tag._Self_Taggable

A type variable with lower bound Taggable.