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

src_py_lib-0.1.3/.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.3}/.github/workflows/release.yml

@@ -23,6 +23,13 @@ defaults:
     shell: bash
 
 jobs:
+  validate:
+    name: Validate
+    uses: ./.github/workflows/validate.yml
+    with:
+      ref: ${{ github.event.inputs.tag || github.ref }}
+      build-package: false
+
   wheel:
     name: Build wheel
     runs-on: ubuntu-24.04
@@ -45,10 +52,16 @@ jobs:
           python-version: ${{ env.PYTHON_VERSION }}
           cache: pip
 
+      - name: Cache uv
+        uses: actions/cache@v5
+        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
-          python -m pip install "uv==${UV_VERSION}"
+        run: python -m pip install "uv==${UV_VERSION}"
 
       - name: Validate release inputs
         id: release
@@ -62,6 +75,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 +98,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,23 +120,29 @@ 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: |
           python -m venv build/release/install-venv
           . build/release/install-venv/bin/activate
-          python -m pip install --upgrade pip
           python -m pip install "${{ steps.build.outputs.wheel_path }}"
           python - <<'PY'
           import os
@@ -147,6 +158,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 +175,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 +197,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
@@ -190,22 +210,41 @@ jobs:
             ${{ steps.build.outputs.wheel_path }}
             ${{ steps.build.outputs.source_distribution_path }}
 
+  github-release:
+    name: Publish GitHub release assets
+    needs: [validate, wheel]
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Download release assets
+        uses: actions/download-artifact@v7
+        with:
+          name: src-py-lib-release
+          path: release-assets
+
       - name: Publish GitHub release assets
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          release_tag="${{ steps.release.outputs.tag }}"
-          wheel_path="${{ steps.build.outputs.wheel_path }}"
-          checksum_path="${{ steps.build.outputs.checksum_path }}"
-          notes_path="${{ steps.notes.outputs.path }}"
+          release_tag="${{ github.event.inputs.tag || github.ref_name }}"
+          notes_path="$(find release-assets -name release-notes.md -print -quit)"
+          mapfile -t release_assets < <(find release-assets -type f ! -name release-notes.md | sort)
+
+          if [[ -z "${notes_path}" ]]; then
+            echo "::error title=Missing release notes::release-notes.md was not found in release artifact."
+            exit 1
+          fi
+          if [[ "${#release_assets[@]}" -eq 0 ]]; then
+            echo "::error title=Missing release assets::No release assets were downloaded."
+            exit 1
+          fi
 
           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
@@ -213,7 +252,7 @@ jobs:
 
   pypi:
     name: Publish PyPI package
-    needs: wheel
+    needs: [validate, wheel]
     runs-on: ubuntu-24.04
     permissions:
       contents: read
@@ -233,3 +272,4 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: dist
+          skip-existing: true

src_py_lib-0.1.3/.github/workflows/validate.yml

@@ -0,0 +1,135 @@
+name: Validate
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to validate. Defaults to the caller's ref."
+        required: false
+        type: string
+      build-package:
+        description: "Build and smoke-test package artifacts. Release builds do this separately."
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  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"
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Cache actionlint
+        id: cache-actionlint
+        uses: actions/cache@v5
+        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"
+          asset="actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          checksums="actionlint_${ACTIONLINT_VERSION}_checksums.txt"
+          base_url="https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}"
+
+          curl -fsSLO "${base_url}/${asset}"
+          curl -fsSLO "${base_url}/${checksums}"
+          grep "  ${asset}$" "${checksums}" | sha256sum --check
+          tar -xzf "${asset}" -C "${HOME}/.local/bin" actionlint
+          chmod 0755 "${HOME}/.local/bin/actionlint"
+
+      - name: Lint GitHub Actions
+        run: |
+          "${HOME}/.local/bin/actionlint"
+
+      - name: Cache npm
+        uses: actions/cache@v5
+        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
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Cache uv
+        uses: actions/cache@v5
+        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 "uv==${UV_VERSION}"
+
+      - name: Validate lockfile
+        run: uv lock --check
+
+      - name: Lint Python
+        run: uv run --frozen ruff check .
+
+      - name: Check Python formatting
+        run: uv run --frozen ruff format --check .
+
+      - name: Type check
+        run: uv run --frozen pyright
+
+      - name: Run tests
+        run: uv run --frozen python -m unittest discover -s tests
+
+      - name: Smoke test source checkout import
+        run: |
+          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 wheel
+        if: inputs.build-package
+        run: uv build --wheel --out-dir dist --no-create-gitignore
+
+      - name: Smoke test installed wheel
+        if: inputs.build-package
+        run: |
+          python -m venv build/ci-venv
+          . build/ci-venv/bin/activate
+          python -m pip install dist/*.whl
+          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

{src_py_lib-0.1.1 → src_py_lib-0.1.3}/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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-py-lib
-Version: 0.1.1
+Version: 0.1.3
 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.3}/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.3}/pyproject.toml

@@ -10,7 +10,7 @@ dev = [
 
 [project]
 name = "src-py-lib"
-version = "0.1.1"
+version = "0.1.3"
 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.3}/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.3}/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."""