Tagging: Metadata on fields and values

Tagging: Metadata on fields and values#

Fiddle allows annotating fields of Config’s (and Buildable’s more generally) and values within a Fiddle configuration DAG with metadata called Tag’s. Tags make bulk update of values easy, and reduces coupling between a library and its configuration.

Defining Tags#

class fiddle.Tag(*args, **kwds)[source]#

Metadata associated with a Fiddle configurable value.

To see a usage example, please see the documentation on the tagging module.

Note: Tags cannot be instantiated.

classmethod new(default=fdl.NO_VALUE)[source]#

Creates a new TaggedValue with cls as the only tag.

If you would like to create a TaggedValue with multiple tags attached, directly call the TaggedValue constructor:

`py tagged_value = TaggedValue(tags=(Tag1, Tag2, Tag3), default=Foo) `

Parameters:

default (Any) – Optional. The default value for this TaggedValue.

Return type:

Any

Returns:

A TaggedValue tagged with the tag cls.

Tagging Values#

fiddle.TaggedValue(tags, default=fdl.NO_VALUE)[source]#

Declares a value annotated with a set of Tag’s.

This is now basically a fdl.Config(lambda value: value) configuration, since tags can be set on any field.

Parameters:

  • tags (Collection[TagType]) – Set of tags to apply.

  • default (Union[NoValue, TypeVar(T)]) – Default value to the identity function.

Return type:

TaggedValueCls[TypeVar(T)]

Returns:

Tagged value configuration object.

Raises:

ValueError – If tags is empty.

class fiddle.tagging.TaggedValueCls(fn_or_cls, /, *args, **kwargs)[source]#

Placeholder class for TaggedValue instances.

Instances of this class are generally transitory; when passed as an argument of a Fiddle Buildable, will be expanded into that argument’s values and tags. However, they may survive as stand-alone objects within tuples, lists, and dictionaries.

Manipulating tags on fdl.Buildable’s#

Bulk Updates#

fiddle.set_tagged(root, *, tag, value)[source]#

Sets all parameters in root tagged with tag to value.

Parameters:

  • root (Buildable) – The root of a DAG of Buildables.

  • tag (TagType) – The tag to search for.

  • value (Any) – Value to set for all parameters tagged with tag.

Return type:

None

fiddle.tagging.list_tags(root, add_superclasses=False)[source]#

Lists all tags in a buildable.

Parameters:

  • root (Buildable) – The root of a DAG of Buildable’s.

  • add_superclasses – For tags that inherit from other tags, add the superclasses as well.

Return type:

FrozenSet[TagType]

Returns:

Set of tags used in this buildable.

fiddle.tagging.materialize_tags(buildable, tags=None, clear_field_tags=False)[source]#

Materialize tagged fields with assigned values or default values.

Converts: `foo.bar.baz = MyCustomTag.new(4096)`

Into: `foo.bar.baz = 4096`

Parameters:

  • buildable (TypeVar(AnyBuildable, bound= Buildable)) – A fdl.Buildable to materialize tags in. This will not be mutated.

  • tags (Optional[Set[TagType]]) – An optional set of Tags to replace. If this is not specified, all tagged fields with a value assigned or with a default tag value will be materialized. Note, if you would like to exclude a set of tags from being materialized, you can pass tagging.list_tags(buildable) - excluded_tags as the tag parameter.

  • clear_field_tags (bool) – Whether to remove all field tags.

Return type:

TypeVar(AnyBuildable, bound= Buildable)

Returns:

A new fdl.Buildable with its tags replaced by their values.

Buildable-at-a-time#

fiddle.get_tags(buildable, argument)[source]#
Return type:

FrozenSet[TagType]

fiddle.add_tag(buildable, argument, tag)[source]#

Tags name with tag in buildable.

Return type:

None

fiddle.set_tags(buildable, argument, tags)[source]#

Sets tags for a parameter in buildable, overriding existing tags.

Return type:

None

fiddle.remove_tag(buildable, argument, tag)[source]#

Removes a given tag from a named argument of a Buildable.

Return type:

None

fiddle.clear_tags(buildable, argument)[source]#

Removes all tags from a named argument of a Buildable.

Return type:

None

Tagging Errors#

class fiddle.tagging.TaggedValueNotFilledError[source]#

A TaggedValue was not filled when build() was called.

Tag Type#

class fiddle.tag_type.TagType(name, bases, dct)[source]#

All Fiddle tags are instances of this class.

For defining Tags, we leverage Python’s class definition and documentation syntax.

See the documentation on fdl.Tag for instructions on how to use.

__call__(*args, **kwds)[source]#

Call self as a function.

__init__(name, bases, dct)[source]#
property description: str#

A string describing the semantics and intended usecases for this tag.

property name: str#

A unique name for this tag.

Contents