src-py-lib 0.1.1__tar.gz → 0.1.2__tar.gz

src_py_lib-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate
+    uses: ./.github/workflows/validate.yml

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/.github/workflows/release.yml

@@ -23,8 +23,15 @@ defaults:
     shell: bash
 
 jobs:
+  validate:
+    name: Validate
+    uses: ./.github/workflows/validate.yml
+    with:
+      ref: ${{ github.event.inputs.tag || github.ref }}
+
   wheel:
     name: Build wheel
+    needs: validate
     runs-on: ubuntu-24.04
     env:
       IMPORT_NAME: src_py_lib
@@ -45,6 +52,14 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
           cache: pip
 
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-
+
       - name: Install build tools
         run: |
           python -m pip install --upgrade pip
@@ -62,6 +77,14 @@ jobs:
             echo "::error title=Missing tag::Tag '${release_tag}' was not fetched. Create and push it before running this workflow."
             exit 1
           fi
+          tag_revision="$(git rev-list -n 1 "${release_tag}")"
+          git fetch --no-tags origin main
+          main_revision="$(git rev-parse origin/main)"
+          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::Merge the release PR first, then tag the main commit."
+            exit 1
+          fi
 
           project_version=$(uv run --frozen python - <<'PY'
           import tomllib
@@ -77,22 +100,6 @@ jobs:
 
           echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
 
-      - name: Validate package
-        run: |
-          uv lock --check
-          uv run --frozen ruff check .
-          uv run --frozen ruff format --check .
-          uv run --frozen pyright
-          uv run --frozen python -m unittest discover -s tests
-          uv run --frozen python - <<'PY'
-          import os
-
-          import src_py_lib
-
-          if src_py_lib.__name__ != os.environ["IMPORT_NAME"]:
-              raise SystemExit(f"unexpected import name: {src_py_lib.__name__}")
-          PY
-
       - name: Build distributions
         id: build
         run: |
@@ -115,17 +122,24 @@ jobs:
           wheel_path="${project_wheels[0]}"
           wheel_name="$(basename "${wheel_path}")"
           source_distribution_path="${source_distributions[0]}"
-          checksum_path="${wheel_path}.sha256"
+          source_distribution_name="$(basename "${source_distribution_path}")"
+          wheel_checksum_path="${wheel_path}.sha256"
+          source_distribution_checksum_path="${source_distribution_path}.sha256"
 
           (
             cd "$(dirname "${wheel_path}")"
-            shasum -a 256 "${wheel_name}" > "$(basename "${checksum_path}")"
+            shasum -a 256 "${wheel_name}" > "$(basename "${wheel_checksum_path}")"
+            shasum -a 256 "${source_distribution_name}" > "$(basename "${source_distribution_checksum_path}")"
           )
 
-          echo "wheel_path=${wheel_path}" >> "${GITHUB_OUTPUT}"
-          echo "wheel_name=${wheel_name}" >> "${GITHUB_OUTPUT}"
-          echo "source_distribution_path=${source_distribution_path}" >> "${GITHUB_OUTPUT}"
-          echo "checksum_path=${checksum_path}" >> "${GITHUB_OUTPUT}"
+          {
+            echo "wheel_path=${wheel_path}"
+            echo "wheel_name=${wheel_name}"
+            echo "source_distribution_path=${source_distribution_path}"
+            echo "source_distribution_name=${source_distribution_name}"
+            echo "wheel_checksum_path=${wheel_checksum_path}"
+            echo "source_distribution_checksum_path=${source_distribution_checksum_path}"
+          } >> "${GITHUB_OUTPUT}"
 
       - name: Smoke test installed wheel
         run: |
@@ -147,6 +161,7 @@ jobs:
         run: |
           release_tag="${{ steps.release.outputs.tag }}"
           wheel_name="${{ steps.build.outputs.wheel_name }}"
+          source_distribution_name="${{ steps.build.outputs.source_distribution_name }}"
           notes_path="build/release/release-notes.md"
           cat > "${notes_path}" <<EOF
           ## Install
@@ -163,13 +178,19 @@ jobs:
           pip install "https://github.com/sourcegraph/src-py-lib/releases/download/${release_tag}/${wheel_name}"
           \`\`\`
 
+          Source distribution:
+
+          \`\`\`sh
+          curl -LO "https://github.com/sourcegraph/src-py-lib/releases/download/${release_tag}/${source_distribution_name}"
+          \`\`\`
+
           Or install this tag with uv:
 
           \`\`\`sh
           uv add "git+https://github.com/sourcegraph/src-py-lib.git@${release_tag}"
           \`\`\`
 
-          Verify downloaded wheel assets with the matching \`.sha256\` file.
+          Verify downloaded assets with the matching \`.sha256\` files.
           EOF
           echo "path=${notes_path}" >> "${GITHUB_OUTPUT}"
 
@@ -179,7 +200,9 @@ jobs:
           name: src-py-lib-release
           path: |
             ${{ steps.build.outputs.wheel_path }}
-            ${{ steps.build.outputs.checksum_path }}
+            ${{ steps.build.outputs.source_distribution_path }}
+            ${{ steps.build.outputs.wheel_checksum_path }}
+            ${{ steps.build.outputs.source_distribution_checksum_path }}
             ${{ steps.notes.outputs.path }}
 
       - name: Upload PyPI artifact
@@ -196,16 +219,23 @@ jobs:
         run: |
           release_tag="${{ steps.release.outputs.tag }}"
           wheel_path="${{ steps.build.outputs.wheel_path }}"
-          checksum_path="${{ steps.build.outputs.checksum_path }}"
+          source_distribution_path="${{ steps.build.outputs.source_distribution_path }}"
+          wheel_checksum_path="${{ steps.build.outputs.wheel_checksum_path }}"
+          source_distribution_checksum_path="${{ steps.build.outputs.source_distribution_checksum_path }}"
           notes_path="${{ steps.notes.outputs.path }}"
+          release_assets=(
+            "${wheel_path}"
+            "${source_distribution_path}"
+            "${wheel_checksum_path}"
+            "${source_distribution_checksum_path}"
+          )
 
           if gh release view "${release_tag}" >/dev/null 2>&1; then
             gh release edit "${release_tag}" --title "${release_tag}" --notes-file "${notes_path}"
-            gh release upload "${release_tag}" "${wheel_path}" "${checksum_path}" --clobber
+            gh release upload "${release_tag}" "${release_assets[@]}" --clobber
           else
             gh release create "${release_tag}" \
-              "${wheel_path}" \
-              "${checksum_path}" \
+              "${release_assets[@]}" \
               --title "${release_tag}" \
               --notes-file "${notes_path}" \
               --verify-tag
@@ -233,3 +263,4 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: dist
+          skip-existing: true

src_py_lib-0.1.1/.github/workflows/ci.yml → src_py_lib-0.1.2/.github/workflows/validate.yml

@@ -1,10 +1,12 @@
-name: CI
+name: Validate
 
 on:
-  pull_request:
-  push:
-    branches:
-      - main
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to validate. Defaults to the caller's ref."
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -14,11 +16,13 @@ defaults:
     shell: bash
 
 jobs:
-  test:
-    name: Build and test
+  package:
+    name: Validate package
     runs-on: ubuntu-24.04
     env:
+      ACTIONLINT_VERSION: "1.7.12"
       IMPORT_NAME: src_py_lib
+      MARKDOWNLINT_CLI2_VERSION: "0.22.1"
       PYTHON_VERSION: "3.11"
       UV_VERSION: "0.11.7"
 
@@ -27,6 +31,34 @@ jobs:
         uses: actions/checkout@v6
         with:
           persist-credentials: false
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Cache actionlint
+        id: cache-actionlint
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/bin/actionlint
+          key: actionlint-${{ runner.os }}-${{ runner.arch }}-${{ env.ACTIONLINT_VERSION }}
+
+      - name: Install actionlint
+        if: steps.cache-actionlint.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p "${HOME}/.local/bin"
+          go install "github.com/rhysd/actionlint/cmd/actionlint@v${ACTIONLINT_VERSION}"
+          install -m 0755 "${HOME}/go/bin/actionlint" "${HOME}/.local/bin/actionlint"
+
+      - name: Lint GitHub Actions
+        run: |
+          "${HOME}/.local/bin/actionlint"
+
+      - name: Cache npm
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-markdownlint-cli2-${{ env.MARKDOWNLINT_CLI2_VERSION }}
+
+      - name: Lint Markdown
+        run: npx --yes "markdownlint-cli2@${MARKDOWNLINT_CLI2_VERSION}"
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -34,6 +66,14 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
           cache: pip
 
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-py${{ env.PYTHON_VERSION }}-
+
       - name: Install uv
         run: |
           python -m pip install --upgrade pip
@@ -42,9 +82,6 @@ jobs:
       - name: Validate lockfile
         run: uv lock --check
 
-      - name: Lint Markdown
-        run: npx --yes markdownlint-cli2
-
       - name: Lint Python
         run: uv run --frozen ruff check .
 
@@ -85,9 +122,3 @@ jobs:
           if src_py_lib.__name__ != os.environ["IMPORT_NAME"]:
               raise SystemExit(f"unexpected import name: {src_py_lib.__name__}")
           PY
-
-      - name: Upload wheel artifact
-        uses: actions/upload-artifact@v7
-        with:
-          name: src-py-lib-wheel
-          path: dist/*.whl

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/AGENTS.md

@@ -14,7 +14,8 @@
 ## Standard commands
 
 ```sh
-npx --yes markdownlint-cli2
+actionlint
+npx --yes markdownlint-cli2@0.22.1
 uv sync
 uv run ruff format .
 uv run ruff check .
@@ -56,11 +57,14 @@ uv run python -m unittest discover -s tests
   verifies that it matches `project.version` before building GitHub release
   assets and publishing to PyPI.
 - Prepare releases on a branch from current `main`. Set `VERSION`, then run:
+- As part of every release bump, find old release-version literals in
+  `AGENTS.md`, `README.md`, and release snippets, and replace them with the
+  new version where they are meant to stay current.
 
 ```sh
 set -euo pipefail
 
-VERSION=0.1.1
+VERSION=0.1.2
 BRANCH="release-v${VERSION}"
 
 git fetch origin --tags --prune
@@ -96,7 +100,8 @@ uv lock
 set -euo pipefail
 
 uv lock --check
-npx --yes markdownlint-cli2
+actionlint
+npx --yes markdownlint-cli2@0.22.1
 uv run ruff check .
 uv run ruff format --check .
 uv run pyright
@@ -111,7 +116,7 @@ rm -rf /tmp/src-py-lib-release-check
 ```sh
 set -euo pipefail
 
-VERSION=0.1.1
+VERSION=0.1.2
 BRANCH="release-v${VERSION}"
 GH_REPO="sourcegraph/src-py-lib"
 
@@ -135,7 +140,7 @@ gh pr merge "${BRANCH}" --repo "${GH_REPO}" --squash --delete-branch
 ```sh
 set -euo pipefail
 
-VERSION=0.1.1
+VERSION=0.1.2
 
 git fetch origin --tags --prune
 git switch main
@@ -149,7 +154,7 @@ git push origin "v${VERSION}"
 ```sh
 set -euo pipefail
 
-VERSION=0.1.1
+VERSION=0.1.2
 GH_REPO="sourcegraph/src-py-lib"
 
 RUN_ID="$(

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-py-lib
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -31,6 +31,13 @@ This repo was created for Sourcegraph Implementation Engineering deployments,
 and is not intended, designed, built, or supported for use in any other scenario.
 Feel free to open issues or PRs, but responses are best effort.
 
+## Semantic Versioning
+
+- Release versions are `major.minor.patch`
+- Because this project is still major version 0:
+  - Minor version updates are breaking changes
+  - Patch version updates are not breaking changes
+
 ## Install
 
 From PyPI:

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/README.md

@@ -8,6 +8,13 @@ This repo was created for Sourcegraph Implementation Engineering deployments,
 and is not intended, designed, built, or supported for use in any other scenario.
 Feel free to open issues or PRs, but responses are best effort.
 
+## Semantic Versioning
+
+- Release versions are `major.minor.patch`
+- Because this project is still major version 0:
+  - Minor version updates are breaking changes
+  - Patch version updates are not breaking changes
+
 ## Install
 
 From PyPI:

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/pyproject.toml

@@ -10,7 +10,7 @@ dev = [
 
 [project]
 name = "src-py-lib"
-version = "0.1.1"
+version = "0.1.2"
 description = "Reusable libraries for Sourcegraph projects"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,7 +45,7 @@ Issues = "https://github.com/sourcegraph/src-py-lib/issues"
 packages = ["src/src_py_lib"]
 
 [tool.pyright]
-include = ["src/src_py_lib"]
+include = ["src/src_py_lib", "tests"]
 typeCheckingMode = "strict"
 extraPaths = ["src"]
 pythonVersion = "3.11"

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/src/src_py_lib/__init__.py

@@ -37,6 +37,14 @@ from src_py_lib.clients.slack import (
 from src_py_lib.clients.sourcegraph import (
     SourcegraphClient,
     SourcegraphClientConfig,
+    SourcegraphJaegerTraceError,
+    SourcegraphJaegerTraceSummary,
+    SourcegraphTrace,
+    decode_external_service_id,
+    decode_repository_id,
+    decode_sourcegraph_node_id,
+    encode_repository_id,
+    encode_sourcegraph_node_id,
     normalize_sourcegraph_endpoint,
     sourcegraph_client_from_config,
 )
@@ -49,7 +57,7 @@ from src_py_lib.utils.config import (
 from src_py_lib.utils.config import (
     config_parse_args as parse_args,
 )
-from src_py_lib.utils.http import HTTPClient, HTTPClientError
+from src_py_lib.utils.http import HTTPClient, HTTPClientError, HTTPResponse
 from src_py_lib.utils.json_cache import load_json_cache, load_json_subset, save_json_cache
 from src_py_lib.utils.json_types import (
     JSONDict,
@@ -63,8 +71,10 @@ 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,
@@ -73,10 +83,15 @@ from src_py_lib.utils.logging import (
     log_context,
     logging_context,
     logging_settings_from_config,
+    new_trace_context,
     resolve_log_level_name,
+    sampled_traceparent,
     stage,
     startup_event,
     submit_with_log_context,
+    trace_context,
+    trace_context_from_traceparent,
+    traceparent_header,
     warning,
 )
 from src_py_lib.utils.tsv import write_tsv
@@ -116,6 +131,7 @@ __all__ = [
     "GoogleSheetsError",
     "HTTPClient",
     "HTTPClientError",
+    "HTTPResponse",
     "JSONDict",
     "LinearClient",
     "LinearClientConfig",
@@ -128,12 +144,22 @@ __all__ = [
     "SlackPacer",
     "SourcegraphClient",
     "SourcegraphClientConfig",
+    "SourcegraphJaegerTraceError",
+    "SourcegraphJaegerTraceSummary",
+    "SourcegraphTrace",
+    "TraceContext",
     "aliased_batched_query",
     "config_field",
     "config_snapshot",
     "configure_logging",
     "critical",
+    "current_trace_context",
     "debug",
+    "decode_external_service_id",
+    "decode_repository_id",
+    "decode_sourcegraph_node_id",
+    "encode_repository_id",
+    "encode_sourcegraph_node_id",
     "error",
     "event",
     "gh_cli_token",
@@ -153,18 +179,23 @@ __all__ = [
     "logging_settings_from_config",
     "log",
     "log_context",
+    "new_trace_context",
     "normalize_sourcegraph_endpoint",
     "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",
     "warning",
     "write_tsv",
 ]

{src_py_lib-0.1.1 → src_py_lib-0.1.2}/src/src_py_lib/clients/graphql.py

@@ -9,11 +9,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import cast
 
-from src_py_lib.utils.http import HTTPClient, HTTPClientError
+from src_py_lib.utils.http import HTTPClient, HTTPClientError, HTTPResponse
 from src_py_lib.utils.json_types import JSONDict, JSONValue, json_dict, json_list, json_str
 from src_py_lib.utils.logging import event
 
 _OPERATION_NAME_RE = re.compile(r"\b(?:query|mutation|subscription)\s+(\w+)")
+HeaderProvider = Mapping[str, str] | Callable[[], Mapping[str, str]]
+GraphQLResponseHook = Callable[[HTTPResponse, Mapping[str, str]], None]
 
 GRAPHQL_INTROSPECTION_QUERY = """
 query IntrospectionQuery {
@@ -130,10 +132,11 @@ class GraphQLClient:
     """POST JSON GraphQL operations and return the `data` object."""
 
     url: str
-    headers: dict[str, str]
+    headers: HeaderProvider
     label: str
     http: HTTPClient = field(default_factory=HTTPClient)
     tolerate_partial_errors: bool = False
+    response_hook: GraphQLResponseHook | None = None
 
     def execute(
         self,
@@ -251,7 +254,16 @@ class GraphQLClient:
             query_bytes=len(query.encode("utf-8")),
         ) as fields:
             try:
-                payload = self.http.json("POST", self.url, headers=self.headers, json_body=body)
+                request_headers = self._headers()
+                if self.response_hook is None:
+                    payload = self.http.json(
+                        "POST", self.url, headers=request_headers, json_body=body
+                    )
+                else:
+                    payload, response = self.http.json_response(
+                        "POST", self.url, headers=request_headers, json_body=body
+                    )
+                    self.response_hook(response, request_headers)
             except HTTPClientError as exception:
                 raise GraphQLError(
                     f"{self.label} GraphQL request failed: {exception}",
@@ -269,6 +281,11 @@ class GraphQLClient:
                 )
             return data
 
+    def _headers(self) -> dict[str, str]:
+        if callable(self.headers):
+            return dict(self.headers())
+        return dict(self.headers)
+
 
 def operation_name(query: str) -> str:
     """Extract the operation name from a GraphQL document."""