Add docstrings

Author: dmontagu

logfire/variables/config.py

@@ -14,53 +14,68 @@
 
 @dataclass(kw_only=True)
 class ValueEquals:
+    """Condition that matches when an attribute equals a specific value."""
+
     attribute: str
     value: Any
     kind: Literal['value-equals'] = 'value-equals'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute equals the expected value."""
         return attributes.get(self.attribute, object()) == self.value
 
 
 @dataclass(kw_only=True)
 class ValueDoesNotEqual:
+    """Condition that matches when an attribute does not equal a specific value."""
+
     attribute: str
     value: Any
     kind: Literal['value-does-not-equal'] = 'value-does-not-equal'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute does not equal the specified value."""
         return attributes.get(self.attribute, object()) != self.value
 
 
 @dataclass(kw_only=True)
 class ValueIsIn:
+    """Condition that matches when an attribute value is in a set of values."""
+
     attribute: str
     values: Sequence[Any]
     kind: Literal['value-is-in'] = 'value-is-in'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute value is in the allowed set."""
         value = attributes.get(self.attribute, object())
         return value in self.values
 
 
 @dataclass(kw_only=True)
 class ValueIsNotIn:
+    """Condition that matches when an attribute value is not in a set of values."""
+
     attribute: str
     values: Sequence[Any]
     kind: Literal['value-is-not-in'] = 'value-is-not-in'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute value is not in the excluded set."""
         value = attributes.get(self.attribute, object())
         return value not in self.values
 
 
 @dataclass(kw_only=True)
 class ValueMatchesRegex:
+    """Condition that matches when an attribute value matches a regex pattern."""
+
     attribute: str
     pattern: str | re.Pattern[str]
     kind: Literal['value-matches-regex'] = 'value-matches-regex'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute value matches the regex pattern."""
         value = attributes.get(self.attribute)
         if not isinstance(value, str):
             return False
@@ -69,11 +84,14 @@ def matches(self, attributes: Mapping[str, Any]) -> bool:
 
 @dataclass(kw_only=True)
 class ValueDoesNotMatchRegex:
+    """Condition that matches when an attribute value does not match a regex pattern."""
+
     attribute: str
     pattern: str | re.Pattern[str]
     kind: Literal['value-does-not-match-regex'] = 'value-does-not-match-regex'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute value does not match the regex pattern."""
         value = attributes.get(self.attribute)
         if not isinstance(value, str):
             return False
@@ -82,19 +100,25 @@ def matches(self, attributes: Mapping[str, Any]) -> bool:
 
 @dataclass(kw_only=True)
 class KeyIsPresent:
+    """Condition that matches when an attribute key is present."""
+
     attribute: str
     kind: Literal['key-is-present'] = 'key-is-present'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute key exists in the attributes."""
         return self.attribute in attributes
 
 
 @dataclass(kw_only=True)
 class KeyIsNotPresent:
+    """Condition that matches when an attribute key is not present."""
+
     attribute: str
     kind: Literal['key-is-not-present'] = 'key-is-not-present'
 
     def matches(self, attributes: Mapping[str, Any]) -> bool:
+        """Check if the attribute key does not exist in the attributes."""
         return self.attribute not in attributes
 
 
@@ -123,6 +147,8 @@ def matches(self, attributes: Mapping[str, Any]) -> bool:
 
 @dataclass(kw_only=True)
 class Rollout:
+    """Configuration for variant selection with weighted probabilities."""
+
     variants: dict[VariantKey, float]
 
     @field_validator('variants')
@@ -135,6 +161,7 @@ def _validate_variant_proportions(cls, v: dict[VariantKey, float]):
         return v
 
     def select_variant(self, seed: str | None) -> VariantKey | None:
+        """Select a variant based on configured weights using optional seeded randomness."""
         rand = random.Random(seed)
 
         population: list[VariantKey | None] = []
@@ -153,6 +180,8 @@ def select_variant(self, seed: str | None) -> VariantKey | None:
 
 @dataclass(kw_only=True)
 class Variant:
+    """A specific variant of a managed variable with its serialized value."""
+
     key: VariantKey
     serialized_value: str
     # format: Literal['json', 'yaml']  # TODO: Consider supporting yaml, and not just JSON; allows comments and better formatting
@@ -162,12 +191,16 @@ class Variant:
 
 @dataclass(kw_only=True)
 class RolloutOverride:
+    """An override of the default rollout when specific conditions are met."""
+
     conditions: list[Condition]
     rollout: Rollout
 
 
 @dataclass(kw_only=True)
 class VariableConfig:
+    """Configuration for a single managed variable including variants and rollout rules."""
+
     name: VariableName
     variants: dict[VariantKey, Variant]
     rollout: Rollout
@@ -228,6 +261,8 @@ def resolve_variant(
 
 @dataclass(kw_only=True)
 class VariablesConfig:
+    """Container for all managed variable configurations."""
+
     variables: dict[VariableName, VariableConfig]
 
     @model_validator(mode='after')
@@ -239,6 +274,7 @@ def _validate_variables(self):
         return self
 
     def get_validation_errors(self, variables: list[Variable[Any]]) -> dict[str, dict[str | None, Exception]]:
+        """Validate that all variable variants can be deserialized to their expected types."""
         errors: dict[str, dict[str | None, Exception]] = {}
         for variable in variables:
             try:
@@ -256,6 +292,7 @@ def get_validation_errors(self, variables: list[Variable[Any]]) -> dict[str, dic
 
     @staticmethod
     def validate_python(data: Any) -> VariablesConfig:
+        """Parse and validate a VariablesConfig from a Python object."""
         return _VariablesConfigAdapter.validate_python(data)
 
 

logfire/variables/providers/abstract.py

@@ -11,24 +11,31 @@
 
 
 class VariableProvider(ABC):
+    """Abstract base class for variable value providers."""
+
     @abstractmethod
     def get_serialized_value(
         self,
         variable_name: str,
         targeting_key: str | None = None,
         attributes: Mapping[str, Any] | None = None,
     ) -> VariableResolutionDetails[str | None]:
+        """Retrieve the serialized value for a variable."""
         raise NotImplementedError
 
     def shutdown(self):
+        """Clean up any resources used by the provider."""
         pass
 
 
 class NoOpVariableProvider(VariableProvider):
+    """A variable provider that always returns None, used when no provider is configured."""
+
     def get_serialized_value(
         self,
         variable_name: str,
         targeting_key: str | None = None,
         attributes: Mapping[str, Any] | None = None,
     ) -> VariableResolutionDetails[str | None]:
+        """Return None for all variable lookups."""
         return VariableResolutionDetails(value=None, _reason='resolved')

logfire/variables/providers/local.py

@@ -11,6 +11,8 @@
 
 
 class LogfireLocalProvider(VariableProvider):
+    """Variable provider that resolves values from a local in-memory configuration."""
+
     def __init__(
         self,
         config: VariablesConfig | Callable[[], VariablesConfig],
@@ -31,6 +33,7 @@ def get_serialized_value(
         targeting_key: str | None = None,
         attributes: Mapping[str, Any] | None = None,
     ) -> VariableResolutionDetails[str | None]:
+        """Resolve a variable's serialized value from the local configuration."""
         variables_config = self.get_config()
 
         variable_config = variables_config.variables.get(variable_name)

logfire/variables/providers/remote.py

@@ -25,8 +25,11 @@
 # TODO: Do we need to provide a mechanism for whether the LogfireRemoteProvider should block to retrieve the config
 #   during startup or do synchronize in the background?
 class LogfireRemoteProvider(VariableProvider):
-    # The threading implementation draws heavily from opentelemetry.sdk._shared_internal.BatchProcessor
-    # You might look there to better understand where some of this logic came from if it seems wrong.
+    """Variable provider that fetches configuration from a remote Logfire API.
+
+    The threading implementation draws heavily from opentelemetry.sdk._shared_internal.BatchProcessor.
+    """
+
     def __init__(
         self,
         base_url: str,
@@ -103,6 +106,7 @@ def _get(self, endpoint: str, *, params: dict[str, Any] | None = None, error_mes
             warnings.warn(error_message, category=RuntimeWarning)
 
     def refresh(self, force: bool = False):
+        """Fetch the latest variable configuration from the remote API."""
         # TODO: Probably makes sense to replace this with something that just polls for a version number or hash
         #   or similar, rather than the whole config, and only grabs the whole config if that version or hash changes.
         with self._refresh_lock:  # Make at most one request at a time
@@ -134,6 +138,7 @@ def get_serialized_value(
         targeting_key: str | None = None,
         attributes: Mapping[str, Any] | None = None,
     ) -> VariableResolutionDetails[str | None]:
+        """Resolve a variable's serialized value from the remote configuration."""
         if self._pid != os.getpid():
             self._reset_once.do_once(self._at_fork_reinit)
 
@@ -159,6 +164,7 @@ def get_serialized_value(
             return VariableResolutionDetails(value=variant.serialized_value, variant=variant.key, _reason='resolved')
 
     def shutdown(self):
+        """Stop the background polling thread and clean up resources."""
         if self._shutdown:
             return
         self._shutdown = True

logfire/variables/variable.py

@@ -26,6 +26,8 @@
 
 @dataclass(kw_only=True)
 class VariableResolutionDetails(Generic[T_co]):
+    """Details about a variable resolution including value, variant, and any errors."""
+
     value: T_co
     variant: str | None = None
     exception: Exception | None = None
@@ -34,15 +36,20 @@ class VariableResolutionDetails(Generic[T_co]):
     ]
 
     def with_value(self, v: T) -> VariableResolutionDetails[T]:
+        """Return a copy of this result with a different value."""
         return replace(self, value=v)  # pyright: ignore[reportReturnType]
 
 
 class ResolveFunction(Protocol[T_co]):
+    """Protocol for functions that resolve variable values based on context."""
+
     def __call__(self, targeting_key: str | None, attributes: Mapping[str, Any] | None) -> T_co:
+        """Resolve the variable value given a targeting key and attributes."""
         raise NotImplementedError
 
 
 def is_resolve_function(f: Any) -> TypeIs[ResolveFunction[Any]]:
+    """Check if a callable matches the ResolveFunction signature."""
     if not callable(f):
         return False
     signature = inspect.signature(f)
@@ -53,12 +60,13 @@ def is_resolve_function(f: Any) -> TypeIs[ResolveFunction[Any]]:
 
 
 class Variable(Generic[T]):
-    """TODO: Need to add otel instrumentation in some way
-      Should the default be that logfire dumps a span with the details into the project for you?
-      And there's no in-process otel? But you can enable that?
-    TODO: Add get_sync method or similar
-    TODO: Need to decide how this is going to work. Options:
-    """
+    """A managed variable that can be resolved dynamically based on configuration."""
+
+    # TODO: Need to add otel instrumentation in some way
+    #  Should the default be that logfire dumps a span with the details into the project for you?
+    #  And there's no in-process otel? But you can enable that?
+    # TODO: Add get_sync method or similar
+    # TODO: Need to decide how this is going to work. Options:
 
     name: str
     default: T | ResolveFunction[T]
@@ -82,6 +90,7 @@ def __init__(
 
     @contextmanager
     def override(self, value: T | ResolveFunction[T]) -> Iterator[None]:
+        """Context manager to temporarily override this variable's value."""
         current = _VARIABLE_OVERRIDES.get() or {}
         token = _VARIABLE_OVERRIDES.set({**current, self.name: value})
         try:
@@ -90,11 +99,13 @@ def override(self, value: T | ResolveFunction[T]) -> Iterator[None]:
             _VARIABLE_OVERRIDES.reset(token)
 
     async def get(self, targeting_key: str | None = None, attributes: Mapping[str, Any] | None = None) -> T:
+        """Resolve and return the variable's value."""
         return (await self.get_details(targeting_key, attributes)).value
 
     async def get_details(
         self, targeting_key: str | None = None, attributes: Mapping[str, Any] | None = None
     ) -> VariableResolutionDetails[T]:
+        """Resolve the variable and return full details including variant and any errors."""
         merged_attributes = self._get_merged_attributes(attributes)
 
         # TODO: How much of the following code should be in the try: except:?