trulens.core.experimental¶

trulens.core.experimental ¶

Attributes¶

_FEATURE_SETUPS `module-attribute` ¶

_FEATURE_SETUPS: Dict[Feature, str] = {
    OTEL_TRACING: "trulens.experimental.otel_tracing._feature"
}

Mapping from experimental flags to their setup class module by name (module containing _FeatureSetup class).

Using name here as we don't want to import them until they are needed and also importing them here would result in a circular import.

This is used to check if the optional imports are available before enabling the feature flags.

Classes¶

Feature ¶

Bases: str, Enum

Experimental feature flags.

Use TruSession.experimental_enable_feature to enable these features:

Examples:

from trulens.core.session import TruSession
from trulens.core.experimental import Feature

session = TruSession()

session.experimental_enable_feature(Feature.OTEL_TRACING)

Attributes¶

OTEL_TRACING `class-attribute` `instance-attribute` ¶

OTEL_TRACING = 'otel_tracing'

OTEL-like tracing.

Warning

This changes how wrapped functions are processed. This setting cannot be changed after any wrapper is produced.

Functions¶

_repr_all `classmethod` ¶

_repr_all() -> str

Return a string representation of all the feature flags.

_FeatureSetup ¶

Bases: BaseModel

Abstract class for utilities that manage experimental features.

Attributes¶

FEATURE `class-attribute` ¶

FEATURE: Feature

The feature flag enabling this feature.

REQUIREMENT `class-attribute` ¶

REQUIREMENT: ImportErrorMessages

The optional imports required to use the feature.

Functions¶

assert_optionals_installed `abstractmethod` `staticmethod` ¶

assert_optionals_installed() -> None

Assert that the optional requirements for the feature are installed.

are_optionals_installed `abstractmethod` `staticmethod` ¶

are_optionals_installed() -> bool

Check if the optional requirements for the feature are installed.

assert_can_enable `staticmethod` ¶

assert_can_enable(feature: Feature) -> None

Asserts that the given feature can be enabled.

This is used to check if the optional imports are available before enabling the feature flags.

can_enable `staticmethod` ¶

can_enable(feature: Feature) -> bool

Check if the given feature can be enabled.

This is used to check if the optional imports are available before enabling the feature flags.

load_setup `staticmethod` ¶

load_setup(modname: str) -> Type[_FeatureSetup]

Load the setup class for the given module.

_Setting ¶

Bases: Generic[T]

A setting that attains some value and can be prevented from further changes ("frozen").

Attributes¶

value `instance-attribute` ¶

value: T = default

The stored value.

frozen_by `instance-attribute` ¶

frozen_by: Set[str] = set()

Set of representations of frames (not in trulens) that have frozen this value.

If empty, it has not been frozen and can be changed.

is_frozen `property` ¶

is_frozen: bool

Determine if the setting is frozen.

Functions¶

set ¶

set(value: Optional[T] = None, freeze: bool = False) -> T

Set/Get the value.

Set the value first if a value is provided. Make it unchangeable if freeze is set.

RAISES	DESCRIPTION
`ValueError`	If the setting has already been frozen and the value is different from the current value.

get ¶

get(freeze: bool = False) -> T

Get the value of this setting.

If freeze is True, freeze the setting so it cannot be changed.

freeze ¶

freeze(value: Optional[T] = None) -> T

Lock the value of this setting.

If a value is provided, attempt to set the setting first to that value.

RAISES	DESCRIPTION
`ValueError`	If the setting has already been frozen and the value is different from the current value.

_Settings ¶

A collection of settings to enable/disable experimental features.

A feature can be enabled/disabled and/or frozen so that once it is set, it cannot be changed again. Locking is necessary for some features like OTEL tracing as once components have been instrumented with old or new tracing, the instrumentation cannot be changed.

Attributes¶

settings `instance-attribute` ¶

settings: Dict[Feature, _Setting[bool]] = defaultdict(
    lambda: _Setting(default=False)
)

The settings for the experimental features.

Functions¶

is_frozen ¶

is_frozen(flag: Union[Feature, str]) -> bool

Determine if the given setting is frozen.

set ¶

set(
    flag: Union[Feature, str],
    *,
    value: Optional[bool] = None,
    freeze: bool = False
) -> bool

Get/Set the given feature flag to the given value.

Sets the flag to the given value if the value parameter is set. Freezes the flag if the freeze parameter is set to True.

RAISES	DESCRIPTION
`ValueError`	If the flag was already frozen to a different value.

freeze ¶

freeze(
    flag: Union[Feature, str],
    *,
    value: Optional[bool] = None
) -> bool

Lock the given feature flag to the given value.

If the value is not provided, freeze the flag to its current value.

RAISES	DESCRIPTION
`ValueError`	If the flag has already been frozen to a different value.

get ¶

get(
    flag: Union[str, Feature], *, freeze: bool = False
) -> bool

Determine the value of the given feature flag.

enable ¶

enable(
    flag: Union[Feature, str], *, freeze: bool = False
) -> bool

Enable the given feature flag.

Freeze the flag if the freeze parameter is set to True.

RAISES	DESCRIPTION
`ValueError`	If the flag was already frozen to disabled.

disable ¶

disable(
    flag: Union[Feature, str], *, freeze: bool = False
) -> bool

Disable the given feature flag.

Freezes the flag if the freeze parameter is set to True.

RAISES	DESCRIPTION
`ValueError`	If the flag was already frozen to enabled.

set_multiple ¶

set_multiple(
    flags: Union[
        Iterable[Union[str, Feature]],
        Mapping[Union[str, Feature], bool],
    ],
    freeze: bool = False,
)

Set multiple feature flags.

If freeze is set, freeze the flags. If a dictionary is passed, the keys are the feature flags and the values are the values to set them to. If a list is passed, the flags are set to True.

RAISES	DESCRIPTION
`ValueError`	If any of the flags are already frozen to a different value than specified.

_WithExperimentalSettings ¶

Bases: BaseModel, WithIdentString

Mixin to add experimental flags and control methods.

Prints out messages when features are enabled/disabled, frozen, and when a setting fails to take up due to earlier freeze.

Attributes¶

_experimental_feature_flags `class-attribute` `instance-attribute` ¶

_experimental_feature_flags: _Settings = PrivateAttr(
    default_factory=_Settings
)

EXPERIMENTAL: Flags to control experimental features.

Functions¶

_ident_str ¶

_ident_str() -> str

Get a string to identify this instance in some way without overburdening the output with details.

_experimental_feature ¶

_experimental_feature(
    flag: Union[str, Feature],
    *,
    value: Optional[bool] = None,
    freeze: bool = False
) -> bool

Get and/or set the value of the given feature flag.

Set it first if value is given. Freeze it if freeze is set.

RAISES	DESCRIPTION
`ValueError`	If the flag is frozen to a different value.

_experimental_freeze_feature ¶

_experimental_freeze_feature(
    flag: Union[str, Feature]
) -> bool

Get and freeze the given feature flag.

experimental_enable_feature ¶

experimental_enable_feature(
    flag: Union[str, Feature]
) -> bool

Enable the given feature flag.

RAISES	DESCRIPTION
`ValueError`	If the flag is already frozen to disabled.

experimental_disable_feature ¶

experimental_disable_feature(
    flag: Union[str, Feature]
) -> bool

Disable the given feature flag.

RAISES	DESCRIPTION
`ValueError`	If the flag is already frozen to enabled.

experimental_feature ¶

experimental_feature(
    flag: Union[str, Feature], *, freeze: bool = False
) -> bool

Determine the value of the given feature flag.

If freeze is set, the flag will be frozen to the value returned.

experimental_set_features ¶

experimental_set_features(
    flags: Optional[
        Union[
            Iterable[Union[str, Feature]],
            Mapping[Union[str, Feature], bool],
        ]
    ],
    freeze: bool = False,
)

Set multiple feature flags.

If freeze is set, the flags will be frozen to the values given.

RAISES	DESCRIPTION
`ValueError`	If any flag is already frozen to a different value than

_experimental_assert_feature ¶

_experimental_assert_feature(
    flag: Feature, purpose: Optional[str] = None
)

Raise a ValueError if the given feature flag is not enabled.

Gives instructions on how to enable the feature flag if error gets raised.

_experimental_method_override `staticmethod` ¶

_experimental_method_override(
    flag: Feature, enabled: T, freeze: bool = False
) -> T

Decorator to replace the decorated method with the given one if the specified feature is enabled.

Freezes the flag if the frozen parameter is set.

Example

class MyClass(_WithExperimentalSettings, ...):

    def my_method_experimental(self, ...): ...

    @MyClass._experimental_method_override(
        flag=Feature.OTEL_TRACING,
        enabled=my_method_experimental
    )
    def my_method(self, ...): ...

_experimental_method `staticmethod` ¶

_experimental_method(
    flag: Feature,
    enabled: Callable,
    disabled: Callable,
    freeze: bool = False,
) -> Callable

Select between two methods based on the status of a feature flag.

The selection happens after the method is called. Freezes the flag if the freeze parameter is set.

Example

python class MyClass(_WithExperimentalSettings, ...): ... def my_method_default(self, ...): ... def my_method_experimental(self, ...): ... ... my_method = MyClass._experimental_method( flag=Feature.OTEL_TRACING, enabled=my_method_experimental, disabled=my_method_default )

trulens.core.experimental¶