Tag Interface

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

_with_new_tags(tags: frozenset[Tag]) → Self

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

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

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

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.

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.