`granular_configuration_language` `.yaml.decorators`

class granular_configuration_language.yaml.decorators.TagDecoratorBase( tag: Tag, category: str = 'General', *, sort_as: str | None = None, )[source]

Bases: Generic[T], ABC

Base class for Tag Decorator factories.

You must implement the user_friendly_type property and define the generic type.

Example:

class string_tag(TagDecoratorBase[str]):
    Type: typing.TypeAlias = str

    @property
    def user_friendly_type(self) -> str:
        return "str"

You must override at least one of scalar_node_type_check(), sequence_node_type_check(),or mapping_node_type_check().

For scalar_node_type_check() to be called the YAML has already be tested to be a str.
For sequence_node_type_check() to be called the YAML has already be tested to be a Sequence.
For mapping_node_type_check() to be called the YAML has already be tested to be a Mapping.

If these are enough, then you may just return True in the override method. Otherwise, implement the override as a TypeGuard.

If the value needs to be altered before being passed to Tag functions, override scalar_node_transformer(), scalar_node_transformer(), or mapping_node_transformer(), as needed.

The transformer is called if the associated node type check passes, just before the value is passed to tag function.

final __init__( tag: Tag, category: str = 'General', *, sort_as: str | None = None, ) → None[source]

Parameters:

tag (Tag) – Value of Tag. Expected to be constructed inline using Tag (e.g. Tag("!Tag")). Must start with !.
category (str, optional) – Category of Tag. Used by available_tags and available_plugins to organize tags, defaults to General.
sort_as (str, optional) – Alternative Tag string. Used for sorting tags different to its explicit value. Used by available_tags and available_plugins.

mapping_node_transformer( value: Any, ) → T[source]

Defaults to an identity operation. Override if the value needs to be altered before being passed to Tag functions.

Only called if mapping_node_type_check() return True.

Parameters:: value (Any) – YAML value
Returns:: Transformed value
Return type:: T

mapping_node_type_check( value: Mapping, ) → TypeGuard[T][source]

Defaults to False. Override to enable Mapping Node support.

Parameters:: value (Mapping) – YAML value
Returns:: Return True, if value is supported.
Return type:: TypeGuard[T]

scalar_node_transformer( value: Any, ) → T[source]

Defaults to an identity operation. Override if the value needs to be altered before being passed to Tag functions.

Only called if scalar_node_type_check() return True.

As an example, a float tag could be supported by:

def scalar_node_type_check(self, value: str) -> TypeGuard[float]:
    try:
        float(value)
        return True
    except ValueError:
        return False


def scalar_node_transformer(self, value: Any) -> float:
    return float(value)

Parameters:: value (Any) – YAML value
Returns:: Transformed value
Return type:: T

scalar_node_type_check( value: str, ) → TypeGuard[T][source]

Defaults to False. Override to enable Scalar Node support.

Parameters:: value (str) – YAML value
Returns:: Return True, if value is supported.
Return type:: TypeGuard[T]

sequence_node_transformer( value: Any, ) → T[source]

Defaults to an identity operation. Override if the value needs to be altered before being passed to Tag functions.

Only called if sequence_node_type_check() return True.

Parameters:: value (Any) – YAML value
Returns:: Transformed value
Return type:: T

sequence_node_type_check( value: Sequence, ) → TypeGuard[T][source]

Defaults to False. Override to enable Sequence Node support.

Parameters:: value (Sequence) – YAML value
Returns:: Return True, if value is supported.
Return type:: TypeGuard[T]

abstract property user_friendly_type: str

User-friendly of the type expected by Tag Decorator.

Note

Use Python types for consistent communication.
This is used when generating exception messages.

Returns:: User-friendly string
Return type:: str

class granular_configuration_language.yaml.decorators.mapping_of_any_tag( tag: Tag, category: str = 'General', *, sort_as: str | None = None, )[source]

Bases: TagDecoratorBase[Configuration]

A decorator factory for Tags that take a YAML mapping as argument.

Example:

@mapping_of_any_tag(Tag("!Tag"))
@as_lazy
def tag(value: Configuration) -> Any: ...

Type: alias of Configuration

__init__( tag: Tag, category: str = 'General', *, sort_as: str | None = None, ) → None

Parameters:

tag (Tag) – Value of Tag. Expected to be constructed inline using Tag (e.g. Tag("!Tag")). Must start with !.
category (str, optional) – Category of Tag. Used by available_tags and available_plugins to organize tags, defaults to General.
sort_as (str, optional) – Alternative Tag string. Used for sorting tags different to its explicit value. Used by available_tags and available_plugins.

class granular_configuration_language.yaml.decorators.sequence_of_any_tag( tag: Tag, category: str = 'General', *, sort_as: str | None = None, )[source]

Bases: TagDecoratorBase[Sequence[Any]]

A decorator factory for Tags that take a YAML sequence as argument.

Example:

@sequence_of_any_tag(Tag("!Tag"))
@as_lazy
def tag(value: Sequence[Any]) -> Any: ...

__init__( tag: Tag, category: str = 'General', *, sort_as: str | None = None, ) → None

Parameters:

tag (Tag) – Value of Tag. Expected to be constructed inline using Tag (e.g. Tag("!Tag")). Must start with !.
category (str, optional) – Category of Tag. Used by available_tags and available_plugins to organize tags, defaults to General.
sort_as (str, optional) – Alternative Tag string. Used for sorting tags different to its explicit value. Used by available_tags and available_plugins.

Type

TypeAlias for this Tag factory

alias of Sequence[Any]

class granular_configuration_language.yaml.decorators.string_or_twople_tag( tag: Tag, category: str = 'General', *, sort_as: str | None = None, )[source]

Bases: TagDecoratorBase[str | tuple[str, Any]]

A decorator factory for Tags that take a YAML string or tuple of a YAML strings and YAML object as argument.

Example:

@string_or_twople_tag(Tag("!Tag"))
@as_lazy
def tag(value: string_or_twople_tag.Type) -> Any: ...

__init__( tag: Tag, category: str = 'General', *, sort_as: str | None = None, ) → None

Parameters:

tag (Tag) – Value of Tag. Expected to be constructed inline using Tag (e.g. Tag("!Tag")). Must start with !.
category (str, optional) – Category of Tag. Used by available_tags and available_plugins to organize tags, defaults to General.
sort_as (str, optional) – Alternative Tag string. Used for sorting tags different to its explicit value. Used by available_tags and available_plugins.

Type: TypeAlias = str | tuple[str, typing.Any]: TypeAlias for this Tag factory

class granular_configuration_language.yaml.decorators.string_tag( tag: Tag, category: str = 'General', *, sort_as: str | None = None, )[source]

Bases: TagDecoratorBase[str]

A decorator factory for Tags that take a YAML string as argument.

Example:

@string_tag(Tag("!Tag"))
@as_lazy
def tag(value: str) -> Any: ...

Type: alias of str

__init__( tag: Tag, category: str = 'General', *, sort_as: str | None = None, ) → None

Parameters:

tag (Tag) – Value of Tag. Expected to be constructed inline using Tag (e.g. Tag("!Tag")). Must start with !.
category (str, optional) – Category of Tag. Used by available_tags and available_plugins to organize tags, defaults to General.
sort_as (str, optional) – Alternative Tag string. Used for sorting tags different to its explicit value. Used by available_tags and available_plugins.

granular_configuration_language.yaml.decorators.as_lazy( func: Callable[[T], RT], /, ) → Callable[[Tag, T, StateHolder], LazyEval[RT]][source]

Wraps the “Tag” function in a LazyEval, so that the function being wrapped is run just-in-time.

Positional Parameters for “Tag” function

(T) - YAML value

Parameters:

func (Callable[[T], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[[Tag, T, StateHolder], LazyEval[RT]]

Example:

@string_tag(Tag("!Tag"))
@as_lazy
def tag(value: str) -> Any: ...

granular_configuration_language.yaml.decorators.as_lazy_with_load_options( func: Callable[[T, LoadOptions], RT], ) → Callable[[Tag, T, StateHolder], LazyEval[RT]][source]

Wraps the “Tag” function in a LazyEval, so that the function being wrapped is run just-in-time.

Positional Parameters for “Tag” function

(T) - YAML value
(LoadOptions) - A LoadOptions instance

Parameters:

func (Callable[[T, LoadOptions], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[[Tag, T, StateHolder], LazyEval[RT]]

Example:

@string_tag(Tag("!Tag"))
@as_lazy_with_load_options
def tag(value: str, options: LoadOptions) -> Any: ...

granular_configuration_language.yaml.decorators.as_lazy_with_root( func: Callable[[T, Root], RT] | None = None, /, *, needs_root_condition: Callable[[T], bool] | None = None, ) → Callable[[Tag, T, StateHolder], LazyEval[RT]] | Callable[[Callable[[T, Root], RT]], Callable[[Tag, T, StateHolder], LazyEval[RT]]][source]

Wraps the “Tag” function in a LazyEval, so that the function being wrapped is run just-in-time.

Positional Parameters for “Tag” function

(T) – YAML value
(Root) – Configuration Root

Documentation Issue

sphinx.ext.autodoc isn’t exposing the typing.overload(). See the example for a clearer type signatures

Typing Stub

# Decorator
# Uses as: ``@as_lazy_with_root``
@overload
def as_lazy_with_root(
    func: Callable[[T, Root], RT],
) -> Callable[[Tag, T, StateHolder], LazyEval[RT]]: ...


# Decorator Factory
# Uses as: ``@as_lazy_with_root(needs_root_condition=condition)``
@overload
def as_lazy_with_root(
    *, needs_root_condition: Callable[[T], bool]
) -> Callable[
    [Callable[[T, Root], RT]],
    Callable[[Tag, T, StateHolder], LazyEval[RT]],
]: ...

Parameters:

func (Callable[[T, Root], RT]) – Function to be wrapped
needs_root_condition (Callable[[T], bool], optional) –
- A Boolean Condition used to test the raw YAML value.
  - If True, Root is set to the Configuration Root.
  - If False, Root is set to None.
- Used as a decorator factory:
  - @as_lazy_with_root(needs_root_condition= ... )

Returns:

Wrapped Function

Return type:

Callable[[Tag, T, StateHolder], LazyEval[RT]]

Example:

# Typical usage
@string_tag(Tag("!Tag"))
@as_lazy_with_root
def tag(value: str, root: Root) -> Any: ...


# Using `needs_root_condition`
@string_tag(Tag("!Tag"))
@as_lazy_with_root(needs_root_condition=interpolation_needs_ref_condition)
@interpolate_value_with_ref
def tag(value: str, root: Root) -> Any: ...

granular_configuration_language.yaml.decorators.as_lazy_with_root_and_load_options( func: Callable[[T, Root, LoadOptions], RT], /, ) → Callable[[Tag, T, StateHolder], LazyEval[RT]][source]

Wraps the “Tag” function in a LazyEval, so that the function being wrapped is run just-in-time.

Positional Parameters for “Tag” function

(T) – YAML value
(Root) – Configuration root
(LoadOptions) – A LoadOptions instance

Parameters:

func (Callable[[T, Root, LoadOptions], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[[Tag, T, StateHolder], LazyEval[RT]]

Example:

@string_tag(Tag("!Tag"))
@as_lazy_with_root_and_load_options
def tag(value: str, root: Root, options: LoadOptions) -> Any: ...

granular_configuration_language.yaml.decorators.as_not_lazy( func: Callable[[T], RT], /, ) → Callable[[Tag, T, StateHolder], RT][source]

Wraps the “Tag” function, but does not make it lazy. The function being wrapped is run at load time.

Positional Parameters for “Tag” function

(T) - YAML value

Parameters:

func (Callable[[T], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[[Tag, T, StateHolder], LazyEval[RT]]

Example:

@string_tag(Tag("!Tag"))
@as_not_lazy
def tag(value: str) -> Any:
    ...

granular_configuration_language.yaml.decorators.interpolate_value_with_ref( func: Callable[[Concatenate[str, Root, P]], RT], /, ) → Callable[[Concatenate[str, Root, P]], RT][source]

Replaces the YAML string value with the interpolated value before calling the tag function

“with_ref” does full interpolation, supporting references (e.g. ${$.value} and ${/value}).

Compatible Laziness Decorators

as_lazy_with_root()
as_lazy_with_root_and_load_options()

Parameters:

func (Callable[Concatenate[str, Root, P], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[Concatenate[str, Root, P], RT]

Example:

@string_tag(Tag("!Tag"))
@as_lazy_with_root
@interpolate_value_with_ref
def tag(value: str, root: Root) -> Any: ...


@string_tag(Tag("!Tag"))
@as_lazy_with_root_and_load_options
@interpolate_value_with_ref
def tag_with_options(value: str, root: Root, options: LoadOptions) -> Any: ...

granular_configuration_language.yaml.decorators.interpolate_value_without_ref( func: Callable[[Concatenate[str, P]], RT], /, ) → Callable[[Concatenate[str, P]], RT][source]

Replaces the YAML string value with the interpolated value before calling the tag function

“without_ref” does a limited interpolation that does not support references (e.g. ${$.value} and ${/value})

Compatible Laziness Decorators

as_lazy()
as_lazy_with_root()
as_lazy_with_root_and_load_options()

Parameters:

func (Callable[Concatenate[str, P], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[Concatenate[str, P], RT]

Example:

@string_tag(Tag("!Tag"))
@as_lazy
@interpolate_value_with_ref
def tag(value: str) -> Any: ...


@string_tag(Tag("!Tag"))
@as_lazy_with_load_options
@interpolate_value_with_ref
def tag_with_options(value: str, options: LoadOptions) -> Any: ...

granular_configuration_language.yaml.decorators.with_tag( func: Callable[[Concatenate[Tag, P]], RT], /, ) → Callable[[P], RT][source]

Added in version 2.3.0.

Injects your tag as the first parameter to your “Tag” Function

The wrapped function has the Tag parameter removed.

Parameters:

func (Callable[Concatenate[Tag, P], RT]) – Function to be wrapped

Returns:

Wrapped Function

Return type:

Callable[P, RT]

Example:

@string_tag(Tag("!Tag"))
@as_lazy
@interpolate_value_without_ref
@with_tag
def tag(tag: Tag, value: str) -> Any: ...

granular_configuration_language .yaml.decorators

`granular_configuration_language` `.yaml.decorators`