src-py-lib 0.1.8__tar.gz → 0.2.0__tar.gz

src_py_lib-0.2.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @marcleblanc2

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/.github/workflows/release.yml

@@ -106,15 +106,34 @@ jobs:
           tag_revision="$(git rev-list -n 1 "${release_tag}")"
           git fetch --no-tags origin main
           main_revision="$(git rev-parse origin/main)"
-          if [[ "${tag_revision}" != "${main_revision}" ]]; then
-            echo "::error title=Tag is not origin/main::Tag '${release_tag}' points at ${tag_revision}, but origin/main is ${main_revision}."
-            echo "::error::Tag the remote head of main, then rerun the release."
+          if ! git merge-base --is-ancestor "${tag_revision}" "${main_revision}"; then
+            echo "::error title=Tag is not on main::Tag '${release_tag}' points at ${tag_revision}, which is not reachable from origin/main."
+            echo "::error::Tag a commit from main, then rerun the release."
             exit 1
           fi
 
           echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
           echo "version=${release_tag#v}" >> "${GITHUB_OUTPUT}"
 
+      - name: Validate runtime dependencies
+        run: |
+          runtime_requirements_file="build/release/runtime-requirements.txt"
+          mkdir -p "$(dirname "${runtime_requirements_file}")"
+          uv export \
+            --no-dev \
+            --no-emit-project \
+            --no-hashes \
+            --no-header \
+            --no-annotate \
+            --frozen \
+            --output-file "${runtime_requirements_file}"
+
+          if grep -Eq '(^-e[[:space:]]|^(\.\.?/)|(^|[[:space:]])file:| @ (\.\.?/|file:))' "${runtime_requirements_file}"; then
+            echo "::error title=Unexpected local dependency::Runtime requirements must resolve from PyPI."
+            cat "${runtime_requirements_file}"
+            exit 1
+          fi
+
       - name: Build distributions
         id: build
         run: |
@@ -174,11 +193,16 @@ jobs:
           } >> "${GITHUB_OUTPUT}"
 
       - name: Smoke test installed wheel
+        env:
+          WHEEL_PATH: ${{ steps.build.outputs.wheel_path }}
         run: |
-          python -m venv build/release/install-venv
-          . build/release/install-venv/bin/activate
-          python -m pip install "${{ steps.build.outputs.wheel_path }}"
-          python - <<'PY'
+          validation_dir="$(mktemp -d)"
+          python -m venv "${validation_dir}/venv"
+          . "${validation_dir}/venv/bin/activate"
+          python -m pip install "${GITHUB_WORKSPACE}/${WHEEL_PATH}"
+          (
+            cd "${validation_dir}"
+            python - <<'PY'
           import os
 
           import src_py_lib
@@ -186,6 +210,7 @@ jobs:
           if src_py_lib.__name__ != os.environ["IMPORT_NAME"]:
               raise SystemExit(f"unexpected import name: {src_py_lib.__name__}")
           PY
+          )
 
       - name: Write release notes
         id: notes
@@ -253,7 +278,7 @@ jobs:
 
     steps:
       - name: Download release assets
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: src-py-lib-release
           path: release-assets
@@ -301,7 +326,7 @@ jobs:
 
     steps:
       - name: Download built distribution
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: pypi-distributions
           path: dist

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/.github/workflows/validate.yml

@@ -238,8 +238,8 @@ jobs:
       - name: Install uv
         run: python -m pip install "uv==${UV_VERSION}"
 
-      - name: Build wheel
-        run: uv build --wheel --out-dir dist --no-create-gitignore
+      - name: Build distributions
+        run: uv build --wheel --sdist --out-dir dist --no-create-gitignore
 
       - name: Smoke test installed wheel
         run: |

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-py-lib
-Version: 0.1.8
+Version: 0.2.0
 Summary: Reusable libraries for Sourcegraph projects
 Project-URL: Homepage, https://github.com/sourcegraph/src-py-lib
 Project-URL: Issues, https://github.com/sourcegraph/src-py-lib/issues
@@ -16,9 +16,13 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: httpx<1,>=0.28
-Requires-Dist: pydantic<3,>=2
-Requires-Dist: python-dotenv<2,>=1.2
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: opentelemetry-api<2,>=1.38.0
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: python-dotenv<2,>=1.2.2
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.38.0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk<2,>=1.38.0; extra == 'otel'
 Description-Content-Type: text/markdown
 
 # src-py-lib

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/pyproject.toml

@@ -4,8 +4,10 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
-    "pyright>=1.1.409",
-    "ruff>=0.7.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.38.0,<2",
+    "opentelemetry-sdk>=1.38.0,<2",
+    "pyright>=1.1.410",
+    "ruff>=0.15.16",
 ]
 
 [project]
@@ -29,9 +31,10 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "httpx>=0.28,<1",
-    "pydantic>=2,<3",
-    "python-dotenv>=1.2,<2",
+    "httpx>=0.28.1,<1",
+    "opentelemetry-api>=1.38.0,<2",
+    "pydantic>=2.13.4,<3",
+    "python-dotenv>=1.2.2,<2",
 ]
 keywords = [
     "Sourcegraph"
@@ -41,6 +44,12 @@ keywords = [
 Homepage = "https://github.com/sourcegraph/src-py-lib"
 Issues = "https://github.com/sourcegraph/src-py-lib/issues"
 
+[project.optional-dependencies]
+otel = [
+    "opentelemetry-exporter-otlp-proto-http>=1.38.0,<2",
+    "opentelemetry-sdk>=1.38.0,<2",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/src_py_lib"]
 

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/renovate.json

@@ -9,6 +9,15 @@
         "python"
       ],
       "allowedVersions": "<3.12"
+    },
+    {
+      "matchPackageNames": [
+        "python"
+      ],
+      "matchUpdateTypes": [
+        "patch"
+      ],
+      "enabled": false
     }
   ],
   "schedule": [

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/src/src_py_lib/__init__.py

@@ -73,29 +73,32 @@ from src_py_lib.utils.json_types import (
 from src_py_lib.utils.logging import (
     LoggingConfig,
     LoggingSettings,
-    TraceContext,
     configure_logging,
     critical,
-    current_trace_context,
     debug,
     error,
-    event,
     info,
-    log,
     log_context,
+    log_event,
     logging_context,
     logging_settings_from_config,
-    new_trace_context,
     resolve_log_level_name,
-    sampled_traceparent,
+    span,
     stage,
     startup_event,
     submit_with_log_context,
-    trace_context,
-    trace_context_from_traceparent,
-    traceparent_header,
     warning,
 )
+from src_py_lib.utils.telemetry import (
+    OpenTelemetryConfig,
+    OpenTelemetryRuntime,
+    OpenTelemetrySettings,
+    OpenTelemetrySetupError,
+    configure_open_telemetry,
+    current_traceparent_header,
+    open_telemetry_settings_from_config,
+    traceparent_fields,
+)
 from src_py_lib.utils.tsv import write_tsv
 
 
@@ -105,15 +108,33 @@ def logging(
     command: str | None = None,
     git_cwd: Path | str | None = None,
     logging_config: LoggingSettings | None = None,
+    open_telemetry: OpenTelemetrySettings | None = None,
     run_fields: Mapping[str, Any] | None = None,
     run_summary: Callable[[], Mapping[str, Any]] | None = None,
 ) -> AbstractContextManager[Path | None]:
     """Configure standard CLI logging and emit startup metadata."""
+    resolved_logging_config = logging_config
+    if open_telemetry is not None:
+        resolved_logging_config = logging_config or logging_settings_from_config(config)
+        resolved_logging_config = LoggingSettings(
+            logger_name=resolved_logging_config.logger_name,
+            terminal_level=resolved_logging_config.terminal_level,
+            log_file_level=resolved_logging_config.log_file_level,
+            log_file=resolved_logging_config.log_file,
+            logs_dir=resolved_logging_config.logs_dir,
+            run=resolved_logging_config.run,
+            retain_log_files=resolved_logging_config.retain_log_files,
+            suppress_http_dependency_logs=resolved_logging_config.suppress_http_dependency_logs,
+            resource_sample_interval_seconds=(
+                resolved_logging_config.resource_sample_interval_seconds
+            ),
+            open_telemetry=open_telemetry,
+        )
     return logging_context(
         command or _script_name(),
         config,
         git_cwd=git_cwd,
-        logging_config=logging_config,
+        logging_config=resolved_logging_config,
         run_fields=run_fields,
         run_summary=run_summary,
     )
@@ -139,6 +160,10 @@ __all__ = [
     "LinearClientConfig",
     "LoggingConfig",
     "LoggingSettings",
+    "OpenTelemetryConfig",
+    "OpenTelemetryRuntime",
+    "OpenTelemetrySettings",
+    "OpenTelemetrySetupError",
     "PullRequest",
     "SlackClient",
     "SlackClientConfig",
@@ -149,15 +174,15 @@ __all__ = [
     "SourcegraphJaegerTraceError",
     "SourcegraphJaegerTraceSummary",
     "SourcegraphTrace",
-    "TraceContext",
     "aliased_batched_query",
     "config_field",
     "config_field_names",
     "config_help_formatter",
     "config_snapshot",
+    "configure_open_telemetry",
     "configure_logging",
     "critical",
-    "current_trace_context",
+    "current_traceparent_header",
     "debug",
     "decode_external_service_id",
     "decode_repository_id",
@@ -165,7 +190,7 @@ __all__ = [
     "encode_repository_id",
     "encode_sourcegraph_node_id",
     "error",
-    "event",
+    "span",
     "gh_cli_token",
     "gcloud_adc_access_token",
     "info",
@@ -182,25 +207,22 @@ __all__ = [
     "logging",
     "logging_context",
     "logging_settings_from_config",
-    "log",
+    "log_event",
     "log_context",
-    "new_trace_context",
     "normalize_sourcegraph_endpoint",
+    "open_telemetry_settings_from_config",
     "parse_args",
     "pr_ref_from_url",
     "quota_project_from_adc",
     "resolve_log_level_name",
     "save_json_cache",
-    "sampled_traceparent",
     "slack_client_from_config",
     "sourcegraph_client_from_config",
     "stage",
     "startup_event",
     "stream_connection_nodes",
     "submit_with_log_context",
-    "trace_context",
-    "trace_context_from_traceparent",
-    "traceparent_header",
+    "traceparent_fields",
     "warning",
     "write_tsv",
 ]

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/src/src_py_lib/clients/graphql.py

@@ -11,7 +11,7 @@ from typing import cast
 
 from src_py_lib.utils.http import HTTPClient, HTTPClientError, HTTPResponse, log_safe_url
 from src_py_lib.utils.json_types import JSONDict, JSONValue, json_dict, json_list, json_str
-from src_py_lib.utils.logging import event
+from src_py_lib.utils.logging import span
 
 _OPERATION_NAME_RE = re.compile(r"\b(?:query|mutation|subscription)\s+(\w+)")
 HeaderProvider = Mapping[str, str] | Callable[[], Mapping[str, str]]
@@ -241,7 +241,7 @@ class GraphQLClient:
         after_variable: str = "after",
     ) -> JSONDict:
         body = {"query": query, "variables": variables or {}}
-        with event(
+        with span(
             "graphql_query",
             level="debug",
             graphql_client=self.label,

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/src/src_py_lib/clients/sourcegraph.py

@@ -10,19 +10,18 @@ import time
 from collections.abc import Iterable, Iterator, Mapping, Sequence
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
-from typing import Final, cast
+from typing import Final
 from urllib.parse import urlsplit
 
 from src_py_lib.clients.graphql import GraphQLClient, stream_connection_nodes
 from src_py_lib.utils.config import Config, config_field
 from src_py_lib.utils.http import HTTPClient, HTTPClientError, HTTPResponse
 from src_py_lib.utils.json_types import JSONDict, JSONValue, json_dict, json_list
-from src_py_lib.utils.logging import (
-    current_trace_context,
-    new_trace_context,
-    submit_with_log_context,
-    trace_context_from_traceparent,
-    traceparent_header,
+from src_py_lib.utils.logging import submit_with_log_context
+from src_py_lib.utils.telemetry import (
+    current_traceparent_header,
+    set_current_span_attributes,
+    traceparent_fields,
 )
 
 SOURCEGRAPH_EXTERNAL_SERVICE_NODE_TYPE: Final[str] = "ExternalService"
@@ -187,16 +186,16 @@ class SourcegraphClient:
     Plain HTTP endpoints are rejected unless `allow_insecure_http=True` is set
     for local development.
 
-    Set `trace=True` to ask Sourcegraph to retain traces for each GraphQL
-    request. Traced requests are available through `drain_traces()` and can be
-    fetched from the instance's Jaeger/debug endpoint with
+    Set `fetch_sg_traces=True` to ask Sourcegraph to retain traces for each
+    GraphQL request. Traced requests are available through `drain_traces()` and
+    can be fetched from the instance's Jaeger/debug endpoint with
     `stream_jaeger_trace_summaries()`.
     """
 
     endpoint: str
     token: str
     http: HTTPClient = field(default_factory=HTTPClient)
-    trace: bool = False
+    fetch_sg_traces: bool = False
     allow_insecure_http: bool = False
     _traces: queue.Queue[SourcegraphTrace] = field(
         default_factory=lambda: queue.Queue[SourcegraphTrace](), init=False, repr=False
@@ -355,7 +354,7 @@ class SourcegraphClient:
             headers=self._graphql_headers,
             label="Sourcegraph",
             http=self.http,
-            response_hook=self._record_trace_response if self.trace else None,
+            response_hook=self._record_trace_response if self.fetch_sg_traces else None,
         )
 
     def _authorization_headers(self) -> dict[str, str]:
@@ -363,11 +362,11 @@ class SourcegraphClient:
 
     def _graphql_headers(self) -> dict[str, str]:
         headers = self._authorization_headers()
-        if self.trace:
+        if self.fetch_sg_traces:
             headers[REQUEST_TRACE_HEADER] = "true"
-            headers[TRACEPARENT_HEADER] = traceparent_header(
-                current_trace_context() or new_trace_context()
-            )
+            traceparent = current_traceparent_header()
+            if traceparent is not None:
+                headers[TRACEPARENT_HEADER] = traceparent
         return headers
 
     def _record_trace_response(
@@ -375,6 +374,13 @@ class SourcegraphClient:
     ) -> None:
         trace = sourcegraph_trace_from_headers(response.headers, request_headers)
         if trace is not None:
+            set_current_span_attributes(
+                {
+                    "sourcegraph.trace_id": trace.trace_id,
+                    "sourcegraph.trace_url": trace.trace_url,
+                    "sourcegraph.span_id": trace.span_id,
+                }
+            )
             self._traces.put(trace)
 
 
@@ -382,22 +388,17 @@ def sourcegraph_client_from_config(
     config: SourcegraphClientConfig,
     *,
     http: HTTPClient | None = None,
-    trace: bool = False,
+    fetch_sg_traces: bool = False,
 ) -> SourcegraphClient:
     """Return a Sourcegraph API client from shared Sourcegraph Config fields."""
     return SourcegraphClient(
         endpoint=config.src_endpoint,
         token=config.src_access_token,
         http=http or HTTPClient(),
-        trace=trace,
+        fetch_sg_traces=fetch_sg_traces,
     )
 
 
-def sampled_traceparent() -> str:
-    """Compatibility wrapper for sampled W3C traceparent generation."""
-    return traceparent_header(sampled=True)
-
-
 def sourcegraph_trace_from_headers(
     response_headers: Mapping[str, str], request_headers: Mapping[str, str]
 ) -> SourcegraphTrace | None:
@@ -407,13 +408,13 @@ def sourcegraph_trace_from_headers(
         return None
     span_id = header_value(response_headers, TRACE_SPAN_RESPONSE_HEADER)
     trace_url = header_value(response_headers, TRACE_URL_RESPONSE_HEADER)
-    parent = trace_context_from_traceparent(header_value(request_headers, TRACEPARENT_HEADER))
+    parent = traceparent_fields(header_value(request_headers, TRACEPARENT_HEADER))
     return SourcegraphTrace(
         trace_id=trace_id.lower(),
         span_id=span_id.lower() if span_id and is_hex_identifier(span_id, 16) else span_id,
         trace_url=trace_url,
-        parent_trace_id=parent.trace_id if parent is not None else None,
-        parent_span_id=parent.span_id if parent is not None else None,
+        parent_trace_id=parent.get("trace_id"),
+        parent_span_id=parent.get("span_id"),
     )
 
 
@@ -472,7 +473,7 @@ def summarize_jaeger_trace(
                 }
             )
 
-    hot_operations = [
+    hot_operations: list[JSONDict] = [
         {
             "operation": operation,
             "count": len(durations),
@@ -481,12 +482,12 @@ def summarize_jaeger_trace(
         }
         for operation, durations in durations_by_operation.items()
     ]
-    hot_operations.sort(key=lambda operation: float(operation["sum_ms"]), reverse=True)
+    hot_operations.sort(key=jaeger_summary_operation_sum_ms, reverse=True)
     return SourcegraphJaegerTraceSummary(
         trace=trace_metadata,
         jaeger_found=True,
         span_count=len(spans),
-        hot_operations=tuple(cast(JSONDict, operation) for operation in hot_operations[:10]),
+        hot_operations=tuple(hot_operations[:10]),
         graphql_operations=tuple(
             {"operation": operation, "count": count}
             for operation, count in graphql_operations.most_common(10)
@@ -495,6 +496,11 @@ def summarize_jaeger_trace(
     )
 
 
+def jaeger_summary_operation_sum_ms(operation: JSONDict) -> float:
+    """Return the total duration for sorting compact Jaeger operation summaries."""
+    return float_value(operation.get("sum_ms"))
+
+
 def jaeger_span_tags(span: JSONDict) -> dict[str, object]:
     """Return Jaeger span tags keyed by tag name."""
     tags: dict[str, object] = {}

{src_py_lib-0.1.8 → src_py_lib-0.2.0}/src/src_py_lib/utils/http.py

@@ -14,7 +14,13 @@ from typing import Final, cast
 import httpx
 
 from src_py_lib.utils.json_types import JSONDict, json_dict
-from src_py_lib.utils.logging import event, record_http_attempt, record_http_retry
+from src_py_lib.utils.logging import record_http_attempt, record_http_retry, span
+from src_py_lib.utils.telemetry import (
+    inject_current_trace_context,
+    mark_current_span_error,
+    record_http_client_metrics,
+    record_http_client_retry,
+)
 
 DEFAULT_TIMEOUT_SECONDS: Final[float] = 30.0
 DEFAULT_MAX_CONNECTIONS: Final[int] = 20
@@ -158,8 +164,9 @@ class HTTPClient:
             body = json.dumps(json_body).encode("utf-8")
             request_headers.setdefault("Content-Type", "application/json")
         for attempt in range(1, self.max_attempts + 1):
+            attempt_started = time.perf_counter()
             try:
-                with event(
+                with span(
                     "http_request",
                     level="debug",
                     method=method,
@@ -168,6 +175,7 @@ class HTTPClient:
                     request_headers=_headers_for_log(request_headers),
                     request_bytes=len(body or b""),
                 ) as fields:
+                    inject_current_trace_context(request_headers)
                     response = self._client.request(
                         method,
                         request_url,
@@ -182,12 +190,22 @@ class HTTPClient:
                     http_version = _response_http_version(response)
                     if http_version is not None:
                         fields["http_version"] = http_version
+                    duration_seconds = time.perf_counter() - attempt_started
                     record_http_attempt(
                         request_bytes=len(body or b""),
                         response_bytes=len(payload),
                         status_code=response.status_code,
                     )
+                    record_http_client_metrics(
+                        method=method,
+                        url=request_url,
+                        duration_seconds=duration_seconds,
+                        request_bytes=len(body or b""),
+                        response_bytes=len(payload),
+                        status_code=response.status_code,
+                    )
                     if response.status_code >= 400:
+                        mark_current_span_error(f"HTTP {response.status_code}")
                         body_text = _body_preview(payload)
                         if not self._should_retry(response.status_code, attempt):
                             raise HTTPClientError(
@@ -198,6 +216,11 @@ class HTTPClient:
                                 headers=dict(response.headers),
                             )
                         record_http_retry()
+                        record_http_client_retry(
+                            method=method,
+                            url=request_url,
+                            status_code=response.status_code,
+                        )
                         self._sleep_before_retry(attempt, response.headers.get("Retry-After"))
                     else:
                         return HTTPResponse(
@@ -210,7 +233,15 @@ class HTTPClient:
             except HTTPClientError:
                 raise
             except httpx.TransportError as exception:
+                duration_seconds = time.perf_counter() - attempt_started
                 record_http_attempt(request_bytes=len(body or b""), transport_error=True)
+                record_http_client_metrics(
+                    method=method,
+                    url=request_url,
+                    duration_seconds=duration_seconds,
+                    request_bytes=len(body or b""),
+                    transport_error=True,
+                )
                 if not self._should_retry(None, attempt):
                     failure = (
                         "timed out" if isinstance(exception, httpx.TimeoutException) else "failed"
@@ -220,6 +251,7 @@ class HTTPClient:
                         f"{_exception_message(exception)}"
                     ) from exception
                 record_http_retry()
+                record_http_client_retry(method=method, url=request_url)
                 self._sleep_before_retry(attempt, None)
         raise AssertionError("HTTP retry loop exited without returning or raising")