Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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
  _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`.