tlcconfig.property¶

Configuration property descriptor.

This module provides the ConfigProperty descriptor that:

  • Pulls doc from the option (single source of truth for docs)

  • Applies transformation on get

  • Validates on set

  • Delegates storage and notifications to the owner’s _get_value/_set_value

Owners are expected to be either a Configuration or a ConfigGroup; ConfigGroup forwards to its parent Configuration, which owns the cache and notifications. Object-schema registration of serializable properties is performed by Configuration itself (see _add_object_properties_to_schema), not by this descriptor — ConfigProperty only exposes object_property_name for that caller to use.

.. rubric:: Example

from tlcconfig.group import ConfigGroup
from tlcconfig.logic import ConfigLogic
from tlcconfig.property import ConfigProperty
from tlcconfig.options import SERVICE_HOST, SERVICE_PORT

class ServiceConfig(ConfigGroup):
    port: int = ConfigProperty(SERVICE_PORT, validate=ConfigLogic.is_valid_port)
    host: str = ConfigProperty(SERVICE_HOST)

Module Contents¶

Classes¶

Class

Description

ConfigProperty

Descriptor that couples option docs with transformation and validation.

Functions¶

Function

Description

attach_config_property_docs

Class decorator that surfaces Option.description on the rendered API reference.

Data¶

Data

Description

T

API¶

class ConfigProperty(
option: Option[tlcconfig.property.T],
transform: Callable[[Any, ConfigSource, str | None], tlcconfig.property.T] | None = None,
validate: Callable[[tlcconfig.property.T], bool] | None = None,
)¶

Bases: typing.Generic[tlcconfig.property.T]

Descriptor that couples option docs with transformation and validation.

This descriptor provides:

  • __doc__ from the option (single source of truth)

  • Transformation on get (via transform callable)

  • Validation on set (via validate callable)

The descriptor delegates to the owner’s _get_value and _set_value methods, which handle caching, source tracking, and notifications. Typical owners are Configuration or a ConfigGroup attached to one.

Variables:

  • option – The option definition (provides docs, default, key).

  • transform – Optional transformation function for get.

  • validate – Optional validation function for set.

Initialize the property descriptor.

Parameters:

  • option – The option defining this property.

  • transform – Optional function to transform raw values. Signature: (value, source, source_info) -> T. The input is intentionally untyped (Any) because transforms normalize heterogeneous raw inputs (YAML/env strings, pre-parsed objects, None) into the logical type T.

  • validate – Optional function to validate values on set, invoked after transform (or the data_type isinstance check) has produced a T. Signature: (value: T) -> bool (True if valid).

property object_property_name: str¶

The property name to use in Object schema.

Uses option.object_property_name if set, otherwise falls back to the attribute name (set via set_name).

T = TypeVar(...)¶
attach_config_property_docs(
cls: type,
) → type¶

Class decorator that surfaces Option.description on the rendered API reference.

ConfigProperty.__init__ sets self.__doc__ = option.description on the descriptor instance, but Sphinx/autodoc2 read class-attribute docstrings (the """...""" literal following the attribute), not descriptor __doc__. Without this decorator, every ConfigProperty attribute on the class renders with an empty body.

This decorator walks the class’s own attributes for ConfigProperty instances and appends a Napoleon :ivar attr: description block to cls.__doc__ (napoleon_use_ivar=True is set in docs/source/conf.py). Non-serializable options are skipped — Option.serializable=False is the explicit signal that an option is not part of the public, documented surface (credentials, runtime/dev flags).

Idempotent on re-application: a _config_property_docs_attached marker on the class prevents double-injection if the decorator is reapplied.