logfire-api 4.34.0__tar.gz → 4.36.0__tar.gz

{logfire_api-4.34.0 → logfire_api-4.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logfire-api
-Version: 4.34.0
+Version: 4.36.0
 Summary: Shim for the Logfire SDK which does nothing unless Logfire is installed
 Author-email: Pydantic Team <engineering@pydantic.dev>, Samuel Colvin <samuel@pydantic.dev>, Hasan Ramezani <hasan@pydantic.dev>, Adrian Garcia Badaracco <adrian@pydantic.dev>, David Montague <david@pydantic.dev>, Marcelo Trylesinski <marcelo@pydantic.dev>, David Hewitt <david.hewitt@pydantic.dev>, Alex Hall <alex@pydantic.dev>
 License-Expression: MIT

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/__init__.pyi

@@ -16,7 +16,7 @@ from logfire.propagate import attach_context as attach_context, get_context as g
 from logfire.sampling import SamplingOptions as SamplingOptions
 from typing import Any
 
-__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval', 'forward_export_request', 'forward_export_request_starlette']
+__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'template_var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval', 'forward_export_request', 'forward_export_request_starlette']
 
 DEFAULT_LOGFIRE_INSTANCE = Logfire()
 span = DEFAULT_LOGFIRE_INSTANCE.span
@@ -74,6 +74,7 @@ error = DEFAULT_LOGFIRE_INSTANCE.error
 fatal = DEFAULT_LOGFIRE_INSTANCE.fatal
 exception = DEFAULT_LOGFIRE_INSTANCE.exception
 var = DEFAULT_LOGFIRE_INSTANCE.var
+template_var = DEFAULT_LOGFIRE_INSTANCE.template_var
 variables_clear = DEFAULT_LOGFIRE_INSTANCE.variables_clear
 variables_get = DEFAULT_LOGFIRE_INSTANCE.variables_get
 variables_push = DEFAULT_LOGFIRE_INSTANCE.variables_push

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/config.pyi

@@ -81,8 +81,8 @@ class PydanticPlugin:
     This class is deprecated for external use. Use `logfire.instrument_pydantic()` instead.
     """
     record: PydanticPluginRecordValues = ...
-    include: set[str] = field(default_factory=set)
-    exclude: set[str] = field(default_factory=set)
+    include: set[str] = field(default_factory=set[str])
+    exclude: set[str] = field(default_factory=set[str])
 
 @dataclass
 class MetricsOptions:
@@ -99,6 +99,8 @@ class CodeSource:
     revision: str
     root_path: str = ...
 
+TemplateMismatchPolicy: Incomplete
+
 @dataclass
 class VariablesOptions:
     """Configuration for managed variables using the Logfire remote API.
@@ -112,6 +114,7 @@ class VariablesOptions:
     include_resource_attributes_in_context: bool = ...
     include_baggage_in_context: bool = ...
     instrument: bool = ...
+    template_mismatch_policy: TemplateMismatchPolicy = ...
     def __post_init__(self) -> None: ...
 
 @dataclass
@@ -125,6 +128,7 @@ class LocalVariablesOptions:
     include_resource_attributes_in_context: bool = ...
     include_baggage_in_context: bool = ...
     instrument: bool = ...
+    template_mismatch_policy: TemplateMismatchPolicy = ...
 
 class DeprecatedKwargs(TypedDict): ...
 
@@ -286,8 +290,8 @@ class LogfireConfig(_LogfireConfigData):
         This is used internally and should not be called by users of the SDK.
 
         If no provider has been explicitly configured (i.e. `variables=` was not passed to
-        `configure()`), but a `LOGFIRE_API_KEY` is available, a `LogfireRemoteVariableProvider`
-        will be lazily created on the first call.
+        `configure()`), but `configure()` has been called and a `LOGFIRE_API_KEY` is available,
+        a `LogfireRemoteVariableProvider` will be lazily created on the first call.
 
         Returns:
             The variable provider.

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/integrations/system_metrics.pyi

@@ -4,7 +4,7 @@ from logfire import Logfire as Logfire
 from typing import Literal
 from typing_extensions import LiteralString
 
-MetricName: type[Literal['system.cpu.simple_utilization', 'system.cpu.time', 'system.cpu.utilization', 'system.memory.usage', 'system.memory.utilization', 'system.swap.usage', 'system.swap.utilization', 'system.disk.io', 'system.disk.operations', 'system.disk.time', 'system.network.dropped.packets', 'system.network.packets', 'system.network.errors', 'system.network.io', 'system.network.connections', 'system.thread_count', 'process.open_file_descriptor.count', 'process.context_switches', 'process.cpu.time', 'process.cpu.utilization', 'process.cpu.core_utilization', 'process.memory.usage', 'process.memory.virtual', 'process.thread.count', 'process.runtime.gc_count', 'cpython.gc.collected_objects', 'cpython.gc.collections', 'cpython.gc.uncollectable_objects']]
+MetricName: type[Literal['system.cpu.simple_utilization', 'system.cpu.time', 'system.cpu.utilization', 'system.memory.usage', 'system.memory.utilization', 'system.swap.usage', 'system.swap.utilization', 'system.disk.io', 'system.disk.operations', 'system.disk.time', 'system.network.dropped.packets', 'system.network.packets', 'system.network.errors', 'system.network.io', 'system.network.connections', 'system.thread_count', 'process.open_file_descriptor.count', 'process.context_switches', 'process.cpu.time', 'process.cpu.utilization', 'process.cpu.core_utilization', 'process.disk.io', 'process.memory.usage', 'process.memory.virtual', 'process.thread.count', 'process.runtime.gc_count', 'cpython.gc.collected_objects', 'cpython.gc.collections', 'cpython.gc.uncollectable_objects']]
 Config = dict[MetricName, Iterable[str] | None]
 CPU_FIELDS: list[LiteralString]
 MEMORY_FIELDS: list[LiteralString]

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/logs.pyi

@@ -11,9 +11,9 @@ from weakref import WeakSet
 class ProxyLoggerProvider(LoggerProvider):
     """A logger provider that wraps another internal logger provider allowing it to be re-assigned."""
     provider: LoggerProvider
-    loggers: WeakSet[ProxyLogger] = dataclasses.field(default_factory=WeakSet)
+    loggers: WeakSet[ProxyLogger] = dataclasses.field(default_factory=WeakSet['ProxyLogger'])
     lock: Lock = dataclasses.field(default_factory=Lock)
-    suppressed_scopes: set[str] = dataclasses.field(default_factory=set)
+    suppressed_scopes: set[str] = dataclasses.field(default_factory=set[str])
     min_level: int = ...
     def get_logger(self, name: str, version: str | None = None, schema_url: str | None = None, attributes: _ExtendedAttributes | None = None) -> Logger: ...
     def set_min_level(self, min_level: int) -> None: ...

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/main.pyi

@@ -14,10 +14,10 @@ from ..integrations.psycopg import CommenterOptions as PsycopgCommenterOptions
 from ..integrations.redis import RequestHook as RedisRequestHook, ResponseHook as RedisResponseHook
 from ..integrations.sqlalchemy import CommenterOptions as SQLAlchemyCommenterOptions
 from ..integrations.wsgi import RequestHook as WSGIRequestHook, ResponseHook as WSGIResponseHook
-from ..variables import ResolveFunction as ResolveFunction, ValidationReport as ValidationReport, Variable as Variable, VariablesConfig as VariablesConfig
+from ..variables import ResolveFunction as ResolveFunction, TemplateVariable as TemplateVariable, ValidationReport as ValidationReport, Variable as Variable, VariablesConfig as VariablesConfig
 from ..version import VERSION as VERSION
 from .auto_trace import AutoTraceModule as AutoTraceModule, install_auto_tracing as install_auto_tracing
-from .config import GLOBAL_CONFIG as GLOBAL_CONFIG, LogfireConfig as LogfireConfig
+from .config import GLOBAL_CONFIG as GLOBAL_CONFIG, LogfireConfig as LogfireConfig, TemplateMismatchPolicy as TemplateMismatchPolicy
 from .config_params import PydanticPluginRecordValues as PydanticPluginRecordValues
 from .constants import ATTRIBUTES_JSON_SCHEMA_KEY as ATTRIBUTES_JSON_SCHEMA_KEY, ATTRIBUTES_LOG_LEVEL_NUM_KEY as ATTRIBUTES_LOG_LEVEL_NUM_KEY, ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_MESSAGE_TEMPLATE_KEY as ATTRIBUTES_MESSAGE_TEMPLATE_KEY, ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, ATTRIBUTES_TAGS_KEY as ATTRIBUTES_TAGS_KEY, DISABLE_CONSOLE_KEY as DISABLE_CONSOLE_KEY, LEVEL_NUMBERS as LEVEL_NUMBERS, LevelName as LevelName, OTLP_MAX_INT_SIZE as OTLP_MAX_INT_SIZE, log_level_attributes as log_level_attributes
 from .formatter import logfire_format as logfire_format, logfire_format_with_magic as logfire_format_with_magic
@@ -64,6 +64,7 @@ from wsgiref.types import WSGIApplication
 
 ExcInfo = SysExcInfo | BaseException | bool | None
 T = TypeVar('T')
+InputsT = TypeVar('InputsT')
 
 class Logfire:
     """The main logfire class."""
@@ -1214,16 +1215,21 @@ class Logfire:
     def var(self, name: str, *, default: T, description: str | None = None) -> Variable[T]: ...
     @overload
     def var(self, name: str, *, type: type[T], default: T | ResolveFunction[T], description: str | None = None) -> Variable[T]: ...
+    @overload
+    def template_var(self, name: str, *, default: T, inputs_type: type[InputsT], description: str | None = None, template_mismatch_policy: TemplateMismatchPolicy | None = None) -> TemplateVariable[T, InputsT]: ...
+    @overload
+    def template_var(self, name: str, *, type: type[T], default: T | ResolveFunction[T], inputs_type: type[InputsT], description: str | None = None, template_mismatch_policy: TemplateMismatchPolicy | None = None) -> TemplateVariable[T, InputsT]: ...
     def variables_clear(self) -> None:
         """Clear all registered variables from this Logfire instance.
 
-        This removes all variables previously registered via [`var()`][logfire.Logfire.var],
+        This removes all variables previously registered via [`var()`][logfire.Logfire.var]
+        or [`template_var()`][logfire.Logfire.template_var],
         allowing them to be re-registered. This is primarily intended for use in tests
         to ensure a clean state between test cases.
         """
-    def variables_get(self) -> list[Variable[Any]]:
+    def variables_get(self) -> list[Variable[Any] | TemplateVariable[Any, Any]]:
         """Get all variables registered with this Logfire instance."""
-    def variables_push(self, variables: list[Variable[Any]] | None = None, *, dry_run: bool = False, yes: bool = False, strict: bool = False) -> bool:
+    def variables_push(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None, *, dry_run: bool = False, yes: bool = False, strict: bool = False) -> bool:
         """Push variable definitions (metadata only) to the configured variable provider.
 
         This method syncs local variable definitions with the provider:
@@ -1239,7 +1245,8 @@ class Logfire:
                 registered with this Logfire instance will be pushed.
             dry_run: If True, only show what would change without applying.
             yes: If True, skip confirmation prompt.
-            strict: If True, fail if any existing label values are incompatible with new schemas.
+            strict: If True, fail if any existing label values are incompatible with new schemas
+                or any reference errors are found.
 
         Returns:
             True if changes were applied (or would be applied in dry_run mode), False otherwise.
@@ -1316,7 +1323,7 @@ class Logfire:
                 )
             ```
         """
-    def variables_validate(self, variables: list[Variable[Any]] | None = None) -> ValidationReport:
+    def variables_validate(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None) -> ValidationReport:
         """Validate that provider-side variable label values match local type definitions.
 
         This method fetches the current variable configuration from the provider and
@@ -1350,8 +1357,10 @@ class Logfire:
     def variables_push_config(self, config: VariablesConfig, *, mode: Literal['merge', 'replace'] = 'merge', dry_run: bool = False, yes: bool = False) -> bool:
         '''Push a VariablesConfig to the configured provider.
 
-        This method pushes a complete VariablesConfig (including labels and rollouts)
-        to the provider. It\'s useful for:
+        This method pushes a VariablesConfig (including labels and rollouts) to the
+        provider. For remote providers, version records are created from label
+        entries with inline serialized values; `latest_version` is pull/read state
+        derived by the server and is not pushed directly. It\'s useful for:
         - Pushing configs generated or modified locally
         - Pushing configs read from files
         - Partial updates (merge mode) or full replacement (replace mode)
@@ -1396,7 +1405,7 @@ class Logfire:
             print(config.model_dump_json(indent=2))
             ```
         '''
-    def variables_build_config(self, variables: list[Variable[Any]] | None = None) -> VariablesConfig:
+    def variables_build_config(self, variables: list[Variable[Any] | TemplateVariable[Any, Any]] | None = None) -> VariablesConfig:
         '''Build a VariablesConfig from registered Variable instances.
 
         This creates a minimal config with just the name, schema, and example for each variable.

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/metrics.pyi

@@ -11,9 +11,9 @@ from weakref import WeakSet
 @dataclasses.dataclass
 class ProxyMeterProvider(MeterProvider):
     provider: MeterProvider
-    meters: WeakSet[_ProxyMeter] = dataclasses.field(default_factory=WeakSet)
+    meters: WeakSet[_ProxyMeter] = dataclasses.field(default_factory=WeakSet['_ProxyMeter'])
     lock: Lock = dataclasses.field(default_factory=Lock)
-    suppressed_scopes: set[str] = dataclasses.field(default_factory=set)
+    suppressed_scopes: set[str] = dataclasses.field(default_factory=set[str])
     def get_meter(self, name: str, version: str | None = None, schema_url: str | None = None, attributes: Attributes | None = None) -> Meter: ...
     def suppress_scopes(self, *scopes: str) -> None: ...
     def set_meter_provider(self, meter_provider: MeterProvider) -> None: ...

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/_internal/tracer.pyi

@@ -25,9 +25,9 @@ class ProxyTracerProvider(TracerProvider):
     """A tracer provider that wraps another internal tracer provider allowing it to be re-assigned."""
     provider: TracerProvider
     config: LogfireConfig
-    tracers: WeakKeyDictionary[_ProxyTracer, Callable[[], Tracer]] = field(default_factory=WeakKeyDictionary)
+    tracers: WeakKeyDictionary[_ProxyTracer, Callable[[], Tracer]] = field(default_factory=WeakKeyDictionary['_ProxyTracer', Callable[[], Tracer]])
     lock: Lock = field(default_factory=Lock)
-    suppressed_scopes: set[str] = field(default_factory=set)
+    suppressed_scopes: set[str] = field(default_factory=set[str])
     def set_provider(self, provider: SDKTracerProvider) -> None: ...
     def suppress_scopes(self, *scopes: str) -> None: ...
     def get_tracer(self, instrumenting_module_name: str, *args: Any, is_span_tracer: bool = True, **kwargs: Any) -> _ProxyTracer: ...

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/db_api.pyi

@@ -2,7 +2,7 @@ from _typeshed import Incomplete
 from collections.abc import Sequence
 from datetime import datetime, timedelta
 from logfire.experimental.query_client import ColumnDetails as ColumnDetails, LogfireQueryClient as LogfireQueryClient
-from typing import Any
+from typing import Any, overload
 
 apilevel: str
 threadsafety: int
@@ -49,11 +49,15 @@ class Cursor:
     """PEP 249 Cursor that executes queries via `LogfireQueryClient.query_json_rows()`."""
     rowcount: int
     arraysize: int
-    min_timestamp: datetime | None
     max_timestamp: datetime | None
     limit: int
     def __init__(self, connection: Connection) -> None: ...
     @property
+    def min_timestamp(self) -> datetime | None:
+        """Per-cursor override for the lower `start_timestamp` bound."""
+    @min_timestamp.setter
+    def min_timestamp(self, value: datetime | None) -> None: ...
+    @property
     def description(self) -> list[tuple[Any, ...]] | None:
         """Column description as a list of 7-tuples per PEP 249.
 
@@ -88,23 +92,7 @@ class Cursor:
     def __enter__(self) -> Cursor: ...
     def __exit__(self, *args: Any) -> None: ...
 
-def connect(read_token: str, base_url: str | None = None, timeout: float = 30.0, *, min_timestamp: datetime | timedelta | None = ..., max_timestamp: datetime | None = None, limit: int = ..., **kwargs: Any) -> Connection:
-    """Create a PEP 249 connection to the Logfire query API.
-
-    Args:
-        read_token: A Logfire read token for authentication.
-        base_url: Override the default API base URL (inferred from token region).
-        timeout: HTTP request timeout in seconds.
-        min_timestamp: Default lower bound for `start_timestamp` filtering.
-            Accepts a `datetime` for an exact bound, a `timedelta` for a
-            relative window (computed as `now - timedelta`), or `None` to
-            disable the filter.  Defaults to 1 day ago.
-        max_timestamp: Default upper bound for `start_timestamp` filtering.
-        limit: Default row limit per query (max 10,000). When the number of
-            returned rows equals the limit a warning is emitted.
-        **kwargs: Additional keyword arguments forwarded to the underlying
-            `httpx.Client`.
-
-    Returns:
-        A PEP 249 `Connection` object.
-    """
+@overload
+def connect(read_token: str, base_url: str | None = None, timeout: float = 30.0, *, min_timestamp: None, max_timestamp: datetime | None = None, limit: int = ..., **kwargs: Any) -> Connection: ...
+@overload
+def connect(read_token: str, base_url: str | None = None, timeout: float = 30.0, *, min_timestamp: datetime | timedelta = ..., max_timestamp: datetime | None = None, limit: int = ..., **kwargs: Any) -> Connection: ...

logfire_api-4.36.0/logfire_api/experimental/query_client.pyi

@@ -0,0 +1,123 @@
+from _typeshed import Incomplete
+from datetime import datetime
+from httpx import AsyncClient, Client, Response, Timeout
+from httpx._client import BaseClient
+from logfire import VERSION as VERSION
+from logfire._internal.config import get_base_url_from_token as get_base_url_from_token
+from logfire._internal.stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
+from pyarrow import Table
+from types import TracebackType
+from typing import Any, Generic, TypeVar, TypedDict, overload
+from typing_extensions import Self
+
+DEFAULT_TIMEOUT: Incomplete
+
+class QueryExecutionError(RuntimeError):
+    """Raised when the query execution fails on the server."""
+class QueryRequestError(RuntimeError):
+    """Raised when the query request is invalid."""
+class InfoRequestError(RuntimeError):
+    """Raised when the request for read token info fails because of unavailable information."""
+
+class ReadTokenInfo(TypedDict, total=False):
+    """Information about the read token."""
+    organization_name: str
+    project_name: str
+
+class ColumnDetails(TypedDict):
+    """The details of a column in the row-oriented JSON-format query results."""
+    name: str
+    datatype: Any
+    nullable: bool
+
+class ColumnData(ColumnDetails):
+    """The data of a column in the column-oriented JSON-format query results."""
+    values: list[Any]
+
+class QueryResults(TypedDict):
+    """The (column-oriented) results of a JSON-format query."""
+    columns: list[ColumnData]
+
+class RowQueryResults(TypedDict):
+    """The row-oriented results of a JSON-format query."""
+    columns: list[ColumnDetails]
+    rows: list[dict[str, Any]]
+T = TypeVar('T', bound=BaseClient)
+
+class _BaseLogfireQueryClient(Generic[T]):
+    base_url: Incomplete
+    read_token: Incomplete
+    timeout: Incomplete
+    client: T
+    def __init__(self, base_url: str, read_token: str, timeout: Timeout, client: type[T], **client_kwargs: Any) -> None: ...
+    def handle_response_errors(self, response: Response) -> None: ...
+
+class LogfireQueryClient(_BaseLogfireQueryClient[Client]):
+    """A synchronous client for querying Logfire data."""
+    def __init__(self, read_token: str, base_url: str | None = None, timeout: Timeout = ..., **client_kwargs: Any) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(self, exc_type: type[BaseException] | None = None, exc_value: BaseException | None = None, traceback: TracebackType | None = None) -> None: ...
+    def info(self) -> ReadTokenInfo:
+        """Get information about the read token."""
+    def query_json(self, sql: str, min_timestamp: datetime | None = None, max_timestamp: datetime | None = None, limit: int | None = None) -> QueryResults:
+        """Query Logfire data and return the results as a column-oriented dictionary."""
+    @overload
+    def query_json_rows(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> RowQueryResults: ...
+    @overload
+    def query_json_rows(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> RowQueryResults: ...
+    @overload
+    def query_arrow(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> Table: ...
+    @overload
+    def query_arrow(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> Table: ...
+    @overload
+    def query_csv(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> str: ...
+    @overload
+    def query_csv(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> str: ...
+
+class AsyncLogfireQueryClient(_BaseLogfireQueryClient[AsyncClient]):
+    """An asynchronous client for querying Logfire data."""
+    def __init__(self, read_token: str, base_url: str | None = None, timeout: Timeout = ..., **async_client_kwargs: Any) -> None: ...
+    async def __aenter__(self) -> Self: ...
+    async def __aexit__(self, exc_type: type[BaseException] | None = None, exc_value: BaseException | None = None, traceback: TracebackType | None = None) -> None: ...
+    async def info(self) -> ReadTokenInfo:
+        """Get information about the read token."""
+    @overload
+    async def query_json_rows(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> RowQueryResults: ...
+    @overload
+    async def query_json_rows(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> RowQueryResults: ...
+    async def query_json(self, sql: str, min_timestamp: datetime | None = None, max_timestamp: datetime | None = None, limit: int | None = None) -> QueryResults:
+        """Query Logfire data and return the results as a column-oriented dictionary."""
+    async def query_json_rows(self, sql: str, min_timestamp: datetime | None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> RowQueryResults:
+        """Query Logfire data and return the results as a row-oriented dictionary.
+
+        Args:
+            sql: The SQL `SELECT` query to execute.
+            min_timestamp: The minimum timestamp to use when querying data. If the provided
+                [`datetime`][datetime.datetime] doesn't have a timezone set, it is assumed to
+                be UTC.
+
+                /// version-deprecated | v4.35.0
+                Not providing a `min_timestamp` is deprecated.
+                ///
+            max_timestamp: The maximum timestamp to use when querying data. If the provided
+                [`datetime`][datetime.datetime] doesn't have a timezone set, it is assumed to
+                be UTC.
+            limit: The maximum number of rows to query. This value takes priority over the
+                `LIMIT` clause in the `sql` query.
+            timezone: The timezone to use for the query execution context.
+            environment: Restrict rows to the provided environment(s). To only query rows where no environment is set,
+                use the empty string (`''`).
+
+        Returns:
+            A dictionary with two entries:
+              * `columns`: A list of column details including the name, datatype and whether the column is nullable.
+              * `rows`: The list of rows matching the query.
+        """
+    @overload
+    async def query_arrow(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> Table: ...
+    @overload
+    async def query_arrow(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> Table: ...
+    @overload
+    async def query_csv(self, sql: str, min_timestamp: None = None, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> str: ...
+    @overload
+    async def query_csv(self, sql: str, min_timestamp: datetime, max_timestamp: datetime | None = None, limit: int | None = None, *, timezone: str | None = None, environment: str | list[str] | None = None) -> str: ...

logfire_api-4.36.0/logfire_api/query_client.pyi

@@ -0,0 +1,3 @@
+from .experimental.query_client import AsyncLogfireQueryClient as AsyncLogfireQueryClient, ColumnData as ColumnData, ColumnDetails as ColumnDetails, InfoRequestError as InfoRequestError, LogfireQueryClient as LogfireQueryClient, QueryExecutionError as QueryExecutionError, QueryRequestError as QueryRequestError, QueryResults as QueryResults, ReadTokenInfo as ReadTokenInfo, RowQueryResults as RowQueryResults
+
+__all__ = ['QueryExecutionError', 'QueryRequestError', 'InfoRequestError', 'ReadTokenInfo', 'ColumnDetails', 'ColumnData', 'QueryResults', 'RowQueryResults', 'LogfireQueryClient', 'AsyncLogfireQueryClient']

logfire_api-4.36.0/logfire_api/variables/__init__.pyi

@@ -0,0 +1,6 @@
+from logfire.variables.abstract import ResolutionReason as ResolutionReason, ResolvedVariable as ResolvedVariable, SyncMode as SyncMode, ValidationReport as ValidationReport, VariableAlreadyExistsError as VariableAlreadyExistsError, VariableNotFoundError as VariableNotFoundError, VariableWriteError as VariableWriteError
+from logfire.variables.composition import ComposedReference as ComposedReference, VariableCompositionCycleError as VariableCompositionCycleError, VariableCompositionError as VariableCompositionError
+from logfire.variables.config import KeyIsNotPresent as KeyIsNotPresent, KeyIsPresent as KeyIsPresent, LabelRef as LabelRef, LabeledValue as LabeledValue, LatestVersion as LatestVersion, LocalVariablesOptions as LocalVariablesOptions, Rollout as Rollout, RolloutOverride as RolloutOverride, TemplateMismatchPolicy as TemplateMismatchPolicy, ValueDoesNotEqual as ValueDoesNotEqual, ValueDoesNotMatchRegex as ValueDoesNotMatchRegex, ValueEquals as ValueEquals, ValueIsIn as ValueIsIn, ValueIsNotIn as ValueIsNotIn, ValueMatchesRegex as ValueMatchesRegex, VariableConfig as VariableConfig, VariableTypeConfig as VariableTypeConfig, VariablesConfig as VariablesConfig
+from logfire.variables.variable import ResolveFunction as ResolveFunction, TemplateInputsMismatchError as TemplateInputsMismatchError, TemplateVariable as TemplateVariable, Variable as Variable, targeting_context as targeting_context
+
+__all__ = ['Variable', 'TemplateVariable', 'ResolvedVariable', 'ResolveFunction', 'VariablesConfig', 'VariableConfig', 'VariableTypeConfig', 'LocalVariablesOptions', 'LabeledValue', 'LabelRef', 'LatestVersion', 'Rollout', 'RolloutOverride', 'KeyIsPresent', 'KeyIsNotPresent', 'ValueEquals', 'ValueDoesNotEqual', 'ValueIsIn', 'ValueIsNotIn', 'ValueMatchesRegex', 'ValueDoesNotMatchRegex', 'targeting_context', 'ComposedReference', 'ResolutionReason', 'SyncMode', 'TemplateMismatchPolicy', 'ValidationReport', 'TemplateInputsMismatchError', 'VariableAlreadyExistsError', 'VariableCompositionCycleError', 'VariableCompositionError', 'VariableNotFoundError', 'VariableWriteError']

logfire_api-4.36.0/logfire_api/variables/_handlebars.pyi

@@ -0,0 +1,52 @@
+from functools import cache
+from pydantic_handlebars import CompiledTemplate, HandlebarsEnvironment
+
+COMPOSITION_OPEN_DELIM: str
+COMPOSITION_CLOSE_DELIM: str
+
+@cache
+def get_environment(strict: bool = False) -> HandlebarsEnvironment:
+    """Return a cached `HandlebarsEnvironment` configured for `@{...}@` composition.
+
+    Uses non-default delimiters so the composition pass leaves any
+    `{{...}}` runtime placeholders in the template as plain content; a
+    subsequent render pass with the default delimiters consumes those.
+
+    When *strict* is `True`, the environment raises `HandlebarsRuntimeError`
+    for any `@{ref}@` (or dotted `@{ref.field}@`) that doesn't resolve, rather
+    than rendering it as an empty string. Composition uses the strict
+    environment for provider/override values (so a missing reference triggers a
+    fall back to the code default) and the non-strict one for the code default
+    itself (the lenient last resort, where a missing reference renders empty).
+    """
+@cache
+def get_runtime_environment() -> HandlebarsEnvironment:
+    """Return a cached default-delimiter `HandlebarsEnvironment` for `{{...}}` rendering.
+
+    Used by `TemplateVariable.get(inputs)` to render the post-composition
+    serialized value against the provided inputs.
+    """
+def compile_composition_template(source: str, strict: bool = False) -> CompiledTemplate:
+    """Return a cached `CompiledTemplate` for *source* under composition delimiters.
+
+    Managed-variable values are typically stable across many resolutions, so
+    caching the parsed program lets `Variable._resolve` skip the parse on
+    every `get()` call. 1024 is large enough for any realistic number of
+    distinct templates in a single process while staying bounded for
+    long-running workers. Same rationale for `compile_runtime_template`.
+
+    *strict* selects the strict vs non-strict composition environment (see
+    `get_environment`); the two are cached separately.
+    """
+def compile_runtime_template(source: str) -> CompiledTemplate:
+    """Return a cached `CompiledTemplate` for *source* under default `{{...}}` delimiters."""
+def extract_composition_dependencies(template: str) -> frozenset[str]:
+    """Return the top-level `@{name}@` references in *template*.
+
+    Cached because cycle / reference validation runs over the same template
+    strings multiple times per push or sync. The underlying delegation goes
+    to `pydantic_handlebars.extract_dependencies` configured for the
+    composition delimiters, so block helpers, dotted paths, and helper
+    sub-expressions are handled AST-correctly. A `frozenset` is returned so the
+    cached value can't be mutated by a caller and poison later lookups.
+    """

{logfire_api-4.34.0 → logfire_api-4.36.0}/logfire_api/variables/abstract.pyi

@@ -2,12 +2,14 @@ import logfire
 from _typeshed import Incomplete
 from abc import ABC, abstractmethod
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from logfire.variables.composition import ComposedReference
 from logfire.variables.config import VariableConfig, VariableTypeConfig, VariablesConfig
+from logfire.variables.template_validation import TemplateFieldIssue
 from logfire.variables.variable import Variable
 from typing import Any, Generic, TypeVar
 
-__all__ = ['ResolvedVariable', 'ResolutionReason', 'SyncMode', 'ValidationReport', 'VariableProvider', 'NoOpVariableProvider', 'VariableWriteError', 'VariableNotFoundError', 'VariableAlreadyExistsError']
+__all__ = ['ResolvedVariable', 'ResolutionReason', 'SyncMode', 'ValidationReport', 'VariableProvider', 'NoOpVariableProvider', 'VariableWriteError', 'VariableNotFoundError', 'VariableAlreadyExistsError', 'render_serialized_string']
 
 SyncMode: Incomplete
 T = TypeVar('T')
@@ -46,11 +48,27 @@ class ResolvedVariable(Generic[T_co]):
     label: str | None = ...
     version: int | None = ...
     exception: Exception | None = ...
+    composed_from: list[ComposedReference] = field(default_factory=list['ComposedReference'])
     reason: ResolutionReason
     def __post_init__(self) -> None: ...
     def __enter__(self): ...
     def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None: ...
 
+def render_serialized_string(serialized_json: str, inputs: Any) -> str:
+    """Render Handlebars templates in a serialized JSON string.
+
+    Decodes the JSON, renders all string values containing `{{placeholders}}`
+    using the provided inputs, then re-encodes to JSON.
+
+    Args:
+        serialized_json: A JSON-encoded string potentially containing Handlebars templates.
+        inputs: Template context values. Can be a Pydantic `BaseModel`, `dict`,
+            `Mapping`, or `None`.
+
+    Returns:
+        The rendered JSON string.
+    """
+
 @dataclass
 class LabelCompatibility:
     """Result of checking a label value's compatibility with a schema."""
@@ -72,12 +90,18 @@ class VariableChange:
     local_description: str | None = ...
     server_description: str | None = ...
     description_differs: bool = ...
+    template_inputs_schema: dict[str, Any] | None = ...
+    value_schema_changed: bool = ...
+    inputs_schema_changed: bool = ...
 
 @dataclass
 class VariableDiff:
     """Represents the diff between local and server variables."""
     changes: list[VariableChange]
     orphaned_server_variables: list[str]
+    reference_errors: list[str] = field(default_factory=list[str])
+    reference_cycles: list[str] = field(default_factory=list[str])
+    template_field_issues: list[TemplateFieldIssue] = field(default_factory=list)
     @property
     def has_changes(self) -> bool:
         """Return True if there are any changes to apply."""
@@ -116,12 +140,15 @@ class ValidationReport:
     variables_checked: int
     variables_not_on_server: list[str]
     description_differences: list[DescriptionDifference]
+    reference_errors: list[str] = field(default_factory=list[str])
+    reference_cycles: list[str] = field(default_factory=list[str])
+    template_field_issues: list[TemplateFieldIssue] = field(default_factory=list)
     @property
     def has_errors(self) -> bool:
         """Return True if there are any validation errors."""
     @property
     def is_valid(self) -> bool:
-        """Return False if there are any validation errors or any variables not defined in the (possibly remote) config."""
+        """Return False if there are validation errors, missing variables, or reference errors."""
     def format(self, *, colors: bool = True) -> str:
         """Format the validation report for human-readable output.
 
@@ -276,8 +303,10 @@ class VariableProvider(ABC):
     def push_config(self, config: VariablesConfig, *, mode: SyncMode = 'merge', dry_run: bool = False, yes: bool = False) -> bool:
         """Push a VariablesConfig to this provider.
 
-        This method pushes a complete VariablesConfig (including labels and rollouts)
-        to the provider. It's useful for:
+        This method pushes a VariablesConfig (including labels and rollouts) to the
+        provider. For remote providers, version records are created from label
+        entries with inline serialized values; `latest_version` is pull/read state
+        derived by the server and is not pushed directly. It's useful for:
         - Pushing configs generated or modified locally
         - Pushing configs read from files
         - Partial updates (merge mode) or full replacement (replace mode)
@@ -313,7 +342,8 @@ class VariableProvider(ABC):
             variables: Variable instances to push.
             dry_run: If True, only show what would change without applying.
             yes: If True, skip confirmation prompt.
-            strict: If True, fail if any existing label values are incompatible with new schemas.
+            strict: If True, fail if any existing label values are incompatible with new schemas
+                or any reference errors are found.
 
         Returns:
             True if changes were applied (or would be applied in dry_run mode), False otherwise.