From 735e47acfdedb64f8c88dc6ce535080bd690a8c5 Mon Sep 17 00:00:00 2001 From: Pablo Pardo Garcia Date: Wed, 29 Jul 2026 17:41:42 +0200 Subject: [PATCH] docs: remove em dashes from docstrings Reword every docstring em-dash (semicolon, colon, or comma as each sentence needs). The generated API reference in the docs site derives from these docstrings, and the docs style bans em-dashes; this was the only remaining source of them. Code comments are untouched (they never reach the reference). --- src/glassflow/__init__.py | 2 +- src/glassflow/client.py | 2 +- src/glassflow/config.py | 8 ++++---- src/glassflow/generation.py | 2 +- src/glassflow/heartbeat.py | 12 ++++++------ src/glassflow/instrumentation_mcp.py | 2 +- src/glassflow/masking.py | 8 ++++---- src/glassflow/spans.py | 6 +++--- 8 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/glassflow/__init__.py b/src/glassflow/__init__.py index eacd984..4926a33 100644 --- a/src/glassflow/__init__.py +++ b/src/glassflow/__init__.py @@ -1,4 +1,4 @@ -"""GlassFlow SDK — OpenTelemetry-native tracing for AI agents and LLM apps.""" +"""GlassFlow SDK: OpenTelemetry-native tracing for AI agents and LLM apps.""" __version__ = "0.6.0" # x-release-please-version diff --git a/src/glassflow/client.py b/src/glassflow/client.py index 9cfa15a..545d8af 100644 --- a/src/glassflow/client.py +++ b/src/glassflow/client.py @@ -134,7 +134,7 @@ def init( ``/v1/heartbeat`` from init until process exit so the platform can tell a live-but-idle agent from a vanished one. heartbeat_interval: Seconds between pings (default 15, clamped to - ``[5, 300]`` — the backend derives staleness from this). + ``[5, 300]``; the backend derives staleness from this). agent_name: Identity heartbeats group under; defaults to ``service_name``. heartbeat_transport: Override the heartbeat HTTP transport diff --git a/src/glassflow/config.py b/src/glassflow/config.py index b62fc28..5e0849d 100644 --- a/src/glassflow/config.py +++ b/src/glassflow/config.py @@ -77,12 +77,12 @@ def traces_endpoint(self) -> str: @property def heartbeat_endpoint(self) -> str: - """Heartbeat URL (``/v1/heartbeat``) — same host as traces.""" + """Heartbeat URL (``/v1/heartbeat``), same host as traces.""" return self.endpoint.rstrip("/") + "/v1/heartbeat" def _clamp_sample_rate(value: float) -> float: - """Clamp to [0.0, 1.0] — an out-of-range value must degrade, not crash init().""" + """Clamp to [0.0, 1.0]; an out-of-range value must degrade, not crash init().""" if 0.0 <= value <= 1.0: return value clamped = min(max(value, 0.0), 1.0) @@ -91,7 +91,7 @@ def _clamp_sample_rate(value: float) -> float: def _clamp_heartbeat_interval(value: float) -> float: - """Clamp to the contract bounds — out-of-range degrades, never crashes init().""" + """Clamp to the contract bounds; out-of-range degrades, never crashes init().""" if HEARTBEAT_INTERVAL_MIN <= value <= HEARTBEAT_INTERVAL_MAX: return value clamped = min(max(value, HEARTBEAT_INTERVAL_MIN), HEARTBEAT_INTERVAL_MAX) @@ -142,7 +142,7 @@ def resolve_config( heartbeat: Enable the agent-lifetime heartbeat thread (``GLASSFLOW_HEARTBEAT``). Off by default this release. heartbeat_interval: Seconds between pings - (``GLASSFLOW_HEARTBEAT_INTERVAL``), clamped to ``[5, 300]`` — + (``GLASSFLOW_HEARTBEAT_INTERVAL``), clamped to ``[5, 300]``; the backend derives staleness from this, so the bounds are part of the wire contract. agent_name: Identity heartbeats group under (``GLASSFLOW_AGENT_NAME``); diff --git a/src/glassflow/generation.py b/src/glassflow/generation.py index 3f4e9f8..3202c18 100644 --- a/src/glassflow/generation.py +++ b/src/glassflow/generation.py @@ -171,7 +171,7 @@ def record_first_token(self) -> None: Call from a streaming loop when the first content chunk arrives; the backend derives time-to-first-token as the event time minus the span - start. Idempotent — only the first call records; safe to call + start. Idempotent: only the first call records; safe to call unconditionally per chunk. A no-op after ``end()``. """ if self._first_token_recorded or not self._span.is_recording(): diff --git a/src/glassflow/heartbeat.py b/src/glassflow/heartbeat.py index 9f3ca5a..a5dccc6 100644 --- a/src/glassflow/heartbeat.py +++ b/src/glassflow/heartbeat.py @@ -11,13 +11,13 @@ - First ping immediately at start (the agent appears without waiting an interval), then every ``interval`` seconds. - Graceful shutdown (``client.shutdown()`` / ``atexit``) sends a final - ``stopped: true`` ping. No signal handlers are installed — a library - must not own process signals; an unhandled SIGTERM/SIGKILL means no - stopped ping, and the backend's stale→gone path covers exactly that. + ``stopped: true`` ping. No signal handlers are installed, because a + library must not own process signals; an unhandled SIGTERM/SIGKILL means + no stopped ping, and the backend's stale→gone path covers exactly that. - Never raises into user code. Pings have a short timeout, are never - retried or queued (liveness is only true fresh — a late heartbeat is + retried or queued (liveness is only true fresh; a late heartbeat is misinformation), and delivery problems warn once per process. -- ``fork()``: the child re-arms with a NEW ``instance_id`` — one identity +- ``fork()``: the child re-arms with a NEW ``instance_id``, so one identity never speaks for two processes. """ @@ -129,7 +129,7 @@ def _http_transport(url: str, headers: dict[str, str]) -> Callable[[dict[str, An """Default transport: a plain POST with a per-call timeout, no retries. TLS certificate verification is urllib's default and is deliberately not - configurable here — a liveness signal must not become a reason to accept + configurable here: a liveness signal must not become a reason to accept unverified endpoints. """ diff --git a/src/glassflow/instrumentation_mcp.py b/src/glassflow/instrumentation_mcp.py index 517b458..530400c 100644 --- a/src/glassflow/instrumentation_mcp.py +++ b/src/glassflow/instrumentation_mcp.py @@ -4,7 +4,7 @@ over MCP becomes a TOOL-kind span: tool name, arguments, result, latency, and error status. Generic instrumentation SDKs cover MCP unevenly (the OpenInference MCP package only propagates context; it creates no spans), so we instrument it -ourselves. Registered in :mod:`glassflow.instrumentation` under ``"mcp"`` — the +ourselves. Registered in :mod:`glassflow.instrumentation` under ``"mcp"``; the top-level import of ``mcp`` below makes an environment without the package look "not installed" to the registry, exactly like a missing third-party instrumentor. diff --git a/src/glassflow/masking.py b/src/glassflow/masking.py index a41ca36..14d2a29 100644 --- a/src/glassflow/masking.py +++ b/src/glassflow/masking.py @@ -2,15 +2,15 @@ A ``SpanExporter`` wrapper that, before spans leave the process, either strips content attributes (``capture_content=False``) or applies a caller-supplied -``mask``. It runs on every span it sees — including third-party instrumentation — -so it's a single client-side choke point for sensitive data. +``mask``. It runs on every span it sees, including third-party +instrumentation, so it's a single client-side choke point for sensitive data. Sanitization works on **copies**: a ``ReadableSpan`` shares its attribute dict by reference with every processor on the provider, so mutating it in place would rewrite what other exporters see (and race with their iteration). Fail-closed guarantees: a mask that raises, returns ``None``, or returns a -value OTel can't encode never leaks the original — the attribute is dropped +value OTel can't encode never leaks the original; the attribute is dropped (or the return value serialized), and the rest of the batch is delivered. """ @@ -123,7 +123,7 @@ def _safe_value(value: Any) -> Any: """Coerce a mask's return into something OTel can encode, or None to drop. BoundedAttributes-style cleaning silently refuses invalid values, which - would leave the ORIGINAL in place — so we validate ourselves. + would leave the ORIGINAL in place, so we validate ourselves. """ if value is None or isinstance(value, _PRIMITIVES): return value diff --git a/src/glassflow/spans.py b/src/glassflow/spans.py index e04a182..9f24d98 100644 --- a/src/glassflow/spans.py +++ b/src/glassflow/spans.py @@ -2,9 +2,9 @@ Two surfaces, following the OpenTelemetry / Langfuse / Laminar convention: -- ``start_as_current_span`` — context manager: activates the span in the OTel - context (so children nest under it) and auto-ends it. -- ``start_span`` — manual: returns an ``Observation`` you must ``.end()``. The span +- ``start_as_current_span`` is the context manager: it activates the span in + the OTel context (so children nest under it) and auto-ends it. +- ``start_span`` is manual: it returns an ``Observation`` you must ``.end()``. The span is parented to the current span at creation but is NOT set as current and does NOT auto-record exceptions. For lifetimes a ``with`` block can't express (streaming, callbacks, passing a span across boundaries).