spanlight 0.2.1__tar.gz → 0.3.0__tar.gz

{spanlight-0.2.1 → spanlight-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spanlight
-Version: 0.2.1
+Version: 0.3.0
 Summary: Python SDK for Spanlight, open-source observability for LLM applications.
 Author: Dheeraj
 License-Expression: MIT
@@ -167,9 +167,11 @@ event, `client_disconnected` when your code closed it early, and
   annotations, which are not a count of searches. No count is recorded and the
   span gets `usage.fee_unknown = "openai_chat_web_search"`, so the search fee
   shows as unknown rather than zero.
-- Requests that set `inference_geo` (other than `global`) or `speed: "fast"`
-  are priced at the standard rate and tagged with
-  `usage.pricing_modifier_unknown`, because those modifiers are not modelled.
+- Anthropic data residency and fast mode are priced from the answer's
+  `usage.inference_geo` and `usage.speed` (1.1 times and 2 times the standard
+  rate). When the answer lacks them, the requested option is tagged
+  `usage.pricing_modifier_unknown` and priced at the standard rate, as is an
+  OpenAI call through a regional host (`regional_endpoint`).
 
 ### Batch output
 
@@ -447,6 +449,13 @@ options. Use `tracer.observe`, `tracer.span` and
 | `shutdown_timeout` |                         | `5.0`                   | Time budget for the flush at interpreter exit                            |
 | `prompt_cache_ttl` |                         | `60.0`                  | Seconds a fetched prompt is served before it is revalidated              |
 
+`host` must use `https://`. Plain `http://` works only for local and private-network hosts:
+`localhost` and names ending in `.localhost`, `.local` or `.internal`, single-label names such
+as a Compose service (`http://api:8000`), and loopback, private and link-local IP addresses.
+With any other plain-http host the SDK logs a warning and stays disabled rather than send the
+key in clear text. A service name with an underscore (`my_api`) is not a valid host name and is
+refused too: rename it with a hyphen or use `https://`.
+
 ### `@observe(name=None, kind="chain", capture_input=True, capture_output=True)`
 
 Traces each call of a function. It supports plain functions, `async def`,
@@ -505,8 +514,63 @@ Trace ids are 32 lowercase hex characters and span ids are 16, both
 W3C Trace Context compatible. `spanlight.get_current_trace_id()` returns the
 current trace id so you can put it in your logs.
 
+### `inject(carrier=None) -> dict` and `continue_trace(carrier)`
+
+These carry a trace from one process to another as a W3C `traceparent`, so an MCP server, an
+agent you call over HTTP or a queue worker records its spans as children of the caller's span.
+
+`inject` returns a copy of `carrier` with `traceparent` set to the current span. A
+`traceparent` already in the carrier is kept, and outside a span the copy is returned
+unchanged. `continue_trace` is a `with` and `async with` block: spans opened inside it become
+children of the span the `traceparent` names. A missing or invalid `traceparent` is ignored and
+the next span starts a new trace. The W3C sampled flag is not honoured (every span is recorded),
+and `tracestate` and `baggage` are not used.
+
+MCP carries trace context in `params._meta` under the key `traceparent`
+([SEP-414](https://modelcontextprotocol.io/seps/414-request-meta)):
+
+```python
+# Client: before sending a request
+params["_meta"] = spanlight.inject(params.get("_meta"))
+
+# Server: while handling it
+with spanlight.continue_trace(request.params.meta):
+    result = run_tool(request.params.arguments)
+```
+
+HTTP headers work the same way:
+
+```python
+# Client
+with spanlight.span("ask-billing-agent"):
+    response = httpx.post(url, json=body, headers=spanlight.inject())
+
+# Server (any headers object with .get, such as Starlette's or Flask's)
+with spanlight.continue_trace(request.headers), spanlight.span("answer"):
+    ...
+```
+
+Spans the server records carry no trace name, environment or release, so they never overwrite the
+caller's. The remote parent is a placeholder that is never sent: inside the block
+`get_current_span()` returns it, and setters called on it are lost, so open a span of your own
+first.
+
+Only continue traces from callers you trust. The caller chooses the trace id, so it can attach
+your spans to another trace of the same project. Your spans still land in the project of your
+own API key.
+
 ## Delivery guarantees
 
+Delivery is confirmed only by a JSON acknowledgment whose nonnegative integer `accepted`
+count plus its `rejected` entries equals the batch size. Rejection indexes must be unique
+integers within the batch. Empty, malformed or inconsistent success responses are ambiguous:
+the SDK retries the same IDs within its configured retry budget, then counts unconfirmed
+entries as failed. A write may already have committed; server idempotence prevents duplicate
+stored records when those IDs are retried. A valid `Retry-After` is a minimum delay, even above
+the client exponential backoff cap. Integer delays beyond exact numeric representation remain
+pending until shutdown rather than retrying early. Shutdown interrupts pending retry waits.
+
+
 Spans are sent by a background daemon thread. A batch goes out when it reaches
 `batch_size` spans or after `flush_interval` seconds. Failed requests are
 retried with jittered exponential backoff on network errors, `429` and `5xx`,

{spanlight-0.2.1 → spanlight-0.3.0}/README.md

@@ -140,9 +140,11 @@ event, `client_disconnected` when your code closed it early, and
   annotations, which are not a count of searches. No count is recorded and the
   span gets `usage.fee_unknown = "openai_chat_web_search"`, so the search fee
   shows as unknown rather than zero.
-- Requests that set `inference_geo` (other than `global`) or `speed: "fast"`
-  are priced at the standard rate and tagged with
-  `usage.pricing_modifier_unknown`, because those modifiers are not modelled.
+- Anthropic data residency and fast mode are priced from the answer's
+  `usage.inference_geo` and `usage.speed` (1.1 times and 2 times the standard
+  rate). When the answer lacks them, the requested option is tagged
+  `usage.pricing_modifier_unknown` and priced at the standard rate, as is an
+  OpenAI call through a regional host (`regional_endpoint`).
 
 ### Batch output
 
@@ -420,6 +422,13 @@ options. Use `tracer.observe`, `tracer.span` and
 | `shutdown_timeout` |                         | `5.0`                   | Time budget for the flush at interpreter exit                            |
 | `prompt_cache_ttl` |                         | `60.0`                  | Seconds a fetched prompt is served before it is revalidated              |
 
+`host` must use `https://`. Plain `http://` works only for local and private-network hosts:
+`localhost` and names ending in `.localhost`, `.local` or `.internal`, single-label names such
+as a Compose service (`http://api:8000`), and loopback, private and link-local IP addresses.
+With any other plain-http host the SDK logs a warning and stays disabled rather than send the
+key in clear text. A service name with an underscore (`my_api`) is not a valid host name and is
+refused too: rename it with a hyphen or use `https://`.
+
 ### `@observe(name=None, kind="chain", capture_input=True, capture_output=True)`
 
 Traces each call of a function. It supports plain functions, `async def`,
@@ -478,8 +487,63 @@ Trace ids are 32 lowercase hex characters and span ids are 16, both
 W3C Trace Context compatible. `spanlight.get_current_trace_id()` returns the
 current trace id so you can put it in your logs.
 
+### `inject(carrier=None) -> dict` and `continue_trace(carrier)`
+
+These carry a trace from one process to another as a W3C `traceparent`, so an MCP server, an
+agent you call over HTTP or a queue worker records its spans as children of the caller's span.
+
+`inject` returns a copy of `carrier` with `traceparent` set to the current span. A
+`traceparent` already in the carrier is kept, and outside a span the copy is returned
+unchanged. `continue_trace` is a `with` and `async with` block: spans opened inside it become
+children of the span the `traceparent` names. A missing or invalid `traceparent` is ignored and
+the next span starts a new trace. The W3C sampled flag is not honoured (every span is recorded),
+and `tracestate` and `baggage` are not used.
+
+MCP carries trace context in `params._meta` under the key `traceparent`
+([SEP-414](https://modelcontextprotocol.io/seps/414-request-meta)):
+
+```python
+# Client: before sending a request
+params["_meta"] = spanlight.inject(params.get("_meta"))
+
+# Server: while handling it
+with spanlight.continue_trace(request.params.meta):
+    result = run_tool(request.params.arguments)
+```
+
+HTTP headers work the same way:
+
+```python
+# Client
+with spanlight.span("ask-billing-agent"):
+    response = httpx.post(url, json=body, headers=spanlight.inject())
+
+# Server (any headers object with .get, such as Starlette's or Flask's)
+with spanlight.continue_trace(request.headers), spanlight.span("answer"):
+    ...
+```
+
+Spans the server records carry no trace name, environment or release, so they never overwrite the
+caller's. The remote parent is a placeholder that is never sent: inside the block
+`get_current_span()` returns it, and setters called on it are lost, so open a span of your own
+first.
+
+Only continue traces from callers you trust. The caller chooses the trace id, so it can attach
+your spans to another trace of the same project. Your spans still land in the project of your
+own API key.
+
 ## Delivery guarantees
 
+Delivery is confirmed only by a JSON acknowledgment whose nonnegative integer `accepted`
+count plus its `rejected` entries equals the batch size. Rejection indexes must be unique
+integers within the batch. Empty, malformed or inconsistent success responses are ambiguous:
+the SDK retries the same IDs within its configured retry budget, then counts unconfirmed
+entries as failed. A write may already have committed; server idempotence prevents duplicate
+stored records when those IDs are retried. A valid `Retry-After` is a minimum delay, even above
+the client exponential backoff cap. Integer delays beyond exact numeric representation remain
+pending until shutdown rather than retrying early. Shutdown interrupts pending retry waits.
+
+
 Spans are sent by a background daemon thread. A batch goes out when it reaches
 `batch_size` spans or after `flush_interval` seconds. Failed requests are
 retried with jittered exponential backoff on network errors, `429` and `5xx`,

{spanlight-0.2.1 → spanlight-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spanlight"
-version = "0.2.1"
+version = "0.3.0"
 description = "Python SDK for Spanlight, open-source observability for LLM applications."
 readme = "README.md"
 license = "MIT"

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/__init__.py

@@ -22,6 +22,7 @@ from ._context import get_current_span, get_current_trace_id
 from ._globals import flush, get_client, init, observe, prompts, score, shutdown, span
 from ._prompt_client import PromptClient
 from ._prompts import CompiledPrompt, Prompt, PromptUnavailableError, no_prompt
+from ._propagation import continue_trace, inject
 from ._span import Span, SpanKind, SpanStatus
 from ._templates import InvalidTemplateError, MissingVariablesError, TemplateTooLargeError
 from ._version import __version__
@@ -43,11 +44,13 @@ __all__ = [
     "Spanlight",
     "TemplateTooLargeError",
     "__version__",
+    "continue_trace",
     "flush",
     "get_client",
     "get_current_span",
     "get_current_trace_id",
     "init",
+    "inject",
     "no_prompt",
     "observe",
     "prompts",

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_client.py

@@ -19,6 +19,7 @@ from ._context import (
     set_current_span,
 )
 from ._exporter import BatchExporter
+from ._hosts import is_safe_host
 from ._prompt_client import PromptClient
 from ._scores import ScoreValue, build_score
 from ._span import Span, SpanKind, normalize_kind
@@ -104,9 +105,11 @@ class Spanlight:
             prompt_cache_ttl=prompt_cache_ttl,
         )
         self._exporter: BatchExporter | None = None
+        # The key is a bearer credential: never send it in clear text to another machine.
+        safe_host = is_safe_host(self.config.host)
         self.prompts: PromptClient = PromptClient(
             base_url=self.config.prompts_url,
-            api_key=self.config.api_key,
+            api_key=self.config.api_key if safe_host else None,
             timeout=self.config.timeout,
             cache_ttl=self.config.prompt_cache_ttl,
             transport=transport,
@@ -118,6 +121,12 @@ class Spanlight:
                 "Spanlight: no API key configured (set SPANLIGHT_API_KEY or pass "
                 "api_key=...); tracing is disabled."
             )
+        elif self.config.enabled and not safe_host:
+            logger.warning(
+                "Spanlight: the host must be an https:// URL (plain http:// is allowed only for "
+                "local and private-network hosts); the API key is not sent, so tracing and "
+                "prompt fetching are disabled."
+            )
         elif self.config.enabled and self.config.api_key:
             self._exporter = BatchExporter(
                 url=self.config.ingest_url,

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_config.py

@@ -8,7 +8,7 @@ a ``SPANLIGHT_*`` environment variable and then to a default.
 from __future__ import annotations
 
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 DEFAULT_HOST = "http://localhost:8000"
 INGEST_PATH = "/v1/traces"
@@ -39,7 +39,7 @@ class SpanlightConfig:
         prompt_cache_ttl: Seconds a fetched prompt is served before it is revalidated.
     """
 
-    api_key: str | None
+    api_key: str | None = field(repr=False)
     host: str
     environment: str | None
     release: str | None

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_experiments_api.py

@@ -10,18 +10,18 @@ from __future__ import annotations
 from collections.abc import Iterator
 from dataclasses import dataclass
 from typing import Any
-from urllib.parse import quote, urlsplit
+from urllib.parse import quote
 
 import httpx
 
 from ._experiments_parse import PromptRef
+from ._hosts import is_safe_host
 from ._version import __version__
 
 _PAGE_SIZE = 200
 # A guard against a server that keeps returning cursors: 50 pages of 200 is 10 000 rows.
 _MAX_PAGES = 50
 _ESCAPE = "~"
-_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
 
 
 class ExperimentError(Exception):
@@ -39,15 +39,12 @@ class ResolvedPrompt:
 
 def _require_safe_host(host: str) -> None:
     """Refuse to send the access token over plain http, except to the local machine."""
-    parts = urlsplit(host)
-    if parts.scheme == "https" and parts.hostname:
-        return
-    if parts.scheme == "http" and parts.hostname in _LOCAL_HOSTS:
-        return
-    raise ExperimentError(
-        "the host must be an https:// URL (http:// is allowed only for localhost); "
-        "the access token is never sent in clear text"
-    )
+    if not is_safe_host(host):
+        raise ExperimentError(
+            "the host must be an https:// URL (http:// is allowed only for local and "
+            "private-network hosts); "
+            "the access token is never sent in clear text"
+        )
 
 
 def wire_name(name: str) -> str:

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_exporter.py

@@ -63,7 +63,8 @@ class BatchExporter:
         jitter: Function returning a float in ``[0, 1)`` used to randomize
             backoff delays.
         base_backoff: Backoff before the first retry, in seconds.
-        max_backoff: Upper bound for any single wait, in seconds.
+        max_backoff: Upper bound for client exponential backoff, in seconds.
+            A valid server ``Retry-After`` minimum may exceed this bound.
     """
 
     def __init__(

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_exporter_delivery.py

@@ -146,25 +146,30 @@ class Delivery:
             body = gzip.compress(body)
 
         for attempt in range(self._max_retries + 1):
+            if self._abort_retries.is_set():
+                self.failed += len(batch)
+                return
             retry_after: float | None = None
             try:
                 response = self._http_client().post(target.url, content=body, headers=self._headers)
             except httpx.HTTPError as exc:
-                failure = f"{type(exc).__name__}: {exc}"
+                failure = type(exc).__name__
             else:
                 status = response.status_code
                 if 200 <= status < 300:
-                    self._handle_success(target, response, batch)
-                    return
-                if status == 413 and len(batch) > 1:
+                    if self._handle_success(target, response, batch):
+                        return
+                    failure = "ambiguous acknowledgment"
+                elif status == 413 and len(batch) > 1:
                     self._split_and_send(target, batch, client)
                     return
-                if not _is_retryable(status):
+                elif not _is_retryable(status):
                     self.failed += len(batch)
                     self._log_rejected_batch(target, response, len(batch))
                     return
-                failure = f"HTTP {status}"
-                retry_after = parse_retry_after(response.headers.get("Retry-After"))
+                else:
+                    failure = f"HTTP {status}"
+                    retry_after = parse_retry_after(response.headers.get("Retry-After"))
 
             if attempt >= self._max_retries or self._abort_retries.is_set():
                 self.failed += len(batch)
@@ -228,20 +233,35 @@ class Delivery:
 
     def _handle_success(
         self, target: _Target, response: httpx.Response, batch: list[SpanPayload]
-    ) -> None:
+    ) -> bool:
         batch_size = len(batch)
         try:
             result: Any = response.json()
         except ValueError:
-            self.sent += batch_size
-            return
-        rejected = result.get("rejected") if isinstance(result, dict) else None
-        if not isinstance(rejected, list) or not rejected:
-            self.sent += batch_size
-            return
-
-        self.sent += batch_size - len(rejected)
+            return False
+        if not isinstance(result, dict):
+            return False
+        accepted, rejected = result.get("accepted"), result.get("rejected")
+        if (
+            type(accepted) is not int
+            or accepted < 0
+            or not isinstance(rejected, list)
+            or accepted + len(rejected) != batch_size
+        ):
+            return False
+        indexes: set[int] = set()
+        for item in rejected:
+            if not isinstance(item, dict):
+                return False
+            index = item.get("index")
+            if type(index) is not int or not 0 <= index < batch_size or index in indexes:
+                return False
+            indexes.add(index)
+
+        self.sent += accepted
         self.failed += len(rejected)
+        if not rejected:
+            return True
         logger.warning(
             "Spanlight rejected %d of %d %s",
             len(rejected),
@@ -260,21 +280,26 @@ class Delivery:
                     item.get("reason"),
                 )
 
+        return True
+
     def retry_delay(self, attempt: int, retry_after: float | None) -> float:
         """Return seconds to wait before retry number ``attempt + 1``.
 
-        ``Retry-After`` wins when present. Otherwise use "equal jitter"
+        ``Retry-After`` sets a minimum when present. Use "equal jitter"
         exponential backoff: half of the exponential step is fixed and the
         other half random, which spreads retries out without ever retrying
         immediately.
         """
-        if retry_after is not None:
-            return min(max(retry_after, 0.0), self._max_backoff)
-        step = min(self._max_backoff, self._base_backoff * (2.0**attempt))
-        return step / 2 + self._jitter() * step / 2
+        step = min(self._max_backoff, self._base_backoff * (2.0 ** min(attempt, 1023)))
+        return max(retry_after or 0.0, step / 2 + self._jitter() * step / 2)
 
     def _interruptible_sleep(self, seconds: float) -> None:
-        self._abort_retries.wait(seconds)
+        # Event.wait overflows on very large valid server delays; wait in bounded chunks.
+        while seconds > 0 and not self._abort_retries.is_set():
+            started = time.monotonic()
+            if self._abort_retries.wait(min(seconds, threading.TIMEOUT_MAX)):
+                return
+            seconds -= time.monotonic() - started
 
 
 def _is_retryable(status: int) -> bool:
@@ -286,6 +311,10 @@ def parse_retry_after(value: str | None) -> float | None:
     if value is None:
         return None
     value = value.strip()
+    if value.isascii() and value.isdecimal():
+        seconds = float(value)
+        # Beyond exact integer representation, keep the minimum indefinite until shutdown.
+        return seconds if seconds <= 2**53 else math.inf
     try:
         seconds = float(value)
     except ValueError:
@@ -297,7 +326,11 @@ def parse_retry_after(value: str | None) -> float | None:
         moment = email.utils.parsedate_to_datetime(value)
     except (TypeError, ValueError):
         return None
-    return max(moment.timestamp() - time.time(), 0.0)
+    try:
+        seconds = moment.timestamp() - time.time()
+    except (OverflowError, OSError, ValueError):
+        return None
+    return max(seconds, 0.0) if math.isfinite(seconds) else None
 
 
 def _short_body(response: httpx.Response) -> str:

spanlight-0.3.0/src/spanlight/_hosts.py

@@ -0,0 +1,61 @@
+"""Which hosts the SDK may send a credential to.
+
+Any https:// host is fine. Plain http:// is allowed only for a host that cannot be on the public
+internet: loopback, private and link-local addresses, and local-only names. The TypeScript SDK
+applies the same rule (``sdks/typescript/src/client.ts``).
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from urllib.parse import urlsplit
+
+# Explicit lists rather than ``is_private``, which is broader and would make the SDKs disagree.
+_LOCAL_NETWORKS = tuple(
+    ipaddress.ip_network(network)
+    for network in (
+        "127.0.0.0/8",
+        "10.0.0.0/8",
+        "172.16.0.0/12",
+        "192.168.0.0/16",
+        "169.254.0.0/16",
+        "::1/128",
+        "fc00::/7",
+        "fe80::/10",
+    )
+)
+_LOCAL_SUFFIXES = (".localhost", ".local", ".internal")
+_SINGLE_LABEL = re.compile(r"[a-z0-9-]+")
+
+
+def is_safe_host(host: str) -> bool:
+    """True for an https:// URL, or plain http:// to a local or private-network host."""
+    try:
+        parts = urlsplit(host)
+        hostname = parts.hostname
+    except ValueError:  # e.g. an unclosed "[::1"; fail closed instead of raising into the app
+        return False
+    if not hostname:
+        return False
+    if parts.scheme == "https":
+        return True
+    return parts.scheme == "http" and _is_local(hostname)
+
+
+def _is_local(hostname: str) -> bool:
+    name = hostname.removesuffix(".")
+    if name == "localhost" or name.endswith(_LOCAL_SUFFIXES):
+        return True
+    try:
+        address: ipaddress.IPv4Address | ipaddress.IPv6Address = ipaddress.ip_address(name)
+    except ValueError:
+        if "." in name or not _SINGLE_LABEL.fullmatch(name):
+            return False
+        try:
+            # The resolver reads a dotless number ("134744072", "0x8080808") as an IPv4 address.
+            address = ipaddress.IPv4Address(socket.inet_aton(name))
+        except OSError:
+            return True  # a single-label name such as a Compose service ("api")
+    return any(address in network for network in _LOCAL_NETWORKS)

spanlight-0.3.0/src/spanlight/_propagation.py

@@ -0,0 +1,122 @@
+"""W3C Trace Context propagation across processes: MCP ``_meta``, HTTP headers, queues.
+
+:func:`inject` writes the current span as a ``traceparent`` into a carrier dict, and
+:func:`continue_trace` makes the span a ``traceparent`` names the parent of the spans opened
+inside its block. ``tracestate`` and ``baggage`` are left as they are. The W3C sampled flag
+is not honoured: the SDK records every span.
+
+Only continue traces from callers you trust: a caller chooses the trace id, so it can attach
+your spans to another trace of the same project.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Mapping
+from contextvars import Token
+from types import TracebackType
+from typing import Any
+
+from ._context import get_current_span, restore_current_span, set_current_span
+from ._span import Span
+from ._trace_state import TraceState
+
+logger = logging.getLogger("spanlight")
+
+_TRACEPARENT = re.compile(r"([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}")
+
+
+def inject(carrier: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Return a copy of ``carrier`` with the current span as its ``traceparent``.
+
+    A ``traceparent`` already in the carrier is kept. Outside a recording span the copy is
+    returned unchanged.
+
+    Example:
+        >>> params["_meta"] = spanlight.inject(params.get("_meta"))  # doctest: +SKIP
+    """
+    result = dict(carrier or {})
+    span = get_current_span()
+    if span is not None and span.recording and "traceparent" not in result:
+        result["traceparent"] = f"00-{span.trace_id}-{span.span_id}-01"
+    return result
+
+
+def _parse(value: object) -> tuple[str, str] | None:
+    """``(trace_id, parent_span_id)`` of a valid W3C ``traceparent``, else ``None``."""
+    if not isinstance(value, str):
+        return None
+    match = _TRACEPARENT.match(value)
+    if match is None:
+        return None
+    version, trace_id, span_id = match.groups()
+    # Version 00 is exactly 55 characters; a later version may add fields after a dash.
+    exact = len(value) == 55
+    if version == "ff" or not (exact or (version != "00" and value[55] == "-")):
+        return None
+    if not trace_id.strip("0") or not span_id.strip("0"):
+        return None
+    return trace_id, span_id
+
+
+class continue_trace:  # lowercase: used like a function, as `contextlib` helpers are
+    """Continue the trace named by ``carrier["traceparent"]`` inside a ``with`` block.
+
+    Spans opened inside the block become children of the remote span. A missing or invalid
+    ``traceparent`` is ignored, so the next span starts a new trace. Works with ``with`` and
+    ``async with``. The carrier is anything with ``.get`` (a dict, request headers) or an object
+    with a ``traceparent`` attribute (the MCP Python SDK's ``request.params.meta``).
+
+    The remote parent is a placeholder that is never sent; :func:`get_current_span` returns it
+    inside the block, and setters called on it are lost.
+    """
+
+    def __init__(self, carrier: Mapping[str, Any] | object | None) -> None:
+        try:
+            # `.get` covers dicts and framework header objects that are not a `Mapping`.
+            get = getattr(carrier, "get", None)
+            value = get("traceparent") if callable(get) else getattr(carrier, "traceparent", None)
+            self._ids = _parse(value)
+        except Exception:
+            logger.debug("continue_trace() could not read the carrier", exc_info=True)
+            self._ids = None
+        self._token: Token[Span | None] | None = None
+        self._previous: Span | None = None
+
+    def __enter__(self) -> None:
+        if self._ids is None:
+            return
+        trace_id, span_id = self._ids
+        # No name, environment or release: the caller's trace fields must win on the server.
+        placeholder = Span(
+            name="remote parent",
+            kind="other",
+            trace=TraceState(trace_id=trace_id),
+            parent_span_id=None,
+            on_end=None,
+            span_id=span_id,
+        )
+        self._previous = get_current_span()
+        self._token = set_current_span(placeholder)
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._token is not None:
+            restore_current_span(self._token, self._previous)
+            self._token = None
+
+    async def __aenter__(self) -> None:
+        self.__enter__()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.__exit__(exc_type, exc, traceback)

{spanlight-0.2.1 → spanlight-0.3.0}/src/spanlight/_version.py

@@ -1,3 +1,3 @@
 """Package version, kept in one place."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"