src-py-lib 0.1.1__tar.gz

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

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    name: Build and test
+    runs-on: ubuntu-24.04
+    env:
+      IMPORT_NAME: src_py_lib
+      PYTHON_VERSION: "3.11"
+      UV_VERSION: "0.11.7"
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "uv==${UV_VERSION}"
+
+      - name: Validate lockfile
+        run: uv lock --check
+
+      - name: Lint Markdown
+        run: npx --yes markdownlint-cli2
+
+      - 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
+        run: uv build --wheel --out-dir dist --no-create-gitignore
+
+      - name: Smoke test installed wheel
+        run: |
+          python -m venv build/ci-venv
+          . build/ci-venv/bin/activate
+          python -m pip install --upgrade pip
+          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
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: src-py-lib-wheel
+          path: dist/*.whl

src_py_lib-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,235 @@
+name: Build release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag to publish, for example v0.1.0"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.event.inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  wheel:
+    name: Build wheel
+    runs-on: ubuntu-24.04
+    env:
+      IMPORT_NAME: src_py_lib
+      PYTHON_VERSION: "3.11"
+      UV_VERSION: "0.11.7"
+
+    steps:
+      - name: Check out release ref
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "uv==${UV_VERSION}"
+
+      - name: Validate release inputs
+        id: release
+        run: |
+          release_tag="${{ github.event.inputs.tag || github.ref_name }}"
+          if [[ ! "${release_tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error title=Invalid release tag::Use a vMAJOR.MINOR.PATCH tag, got '${release_tag}'."
+            exit 1
+          fi
+          if ! git rev-parse --verify --quiet "refs/tags/${release_tag}" >/dev/null; then
+            echo "::error title=Missing tag::Tag '${release_tag}' was not fetched. Create and push it before running this workflow."
+            exit 1
+          fi
+
+          project_version=$(uv run --frozen python - <<'PY'
+          import tomllib
+
+          with open("pyproject.toml", "rb") as pyproject_file:
+              print(tomllib.load(pyproject_file)["project"]["version"])
+          PY
+          )
+          if [[ "v${project_version}" != "${release_tag}" ]]; then
+            echo "::error title=Version mismatch::pyproject.toml version '${project_version}' does not match tag '${release_tag}'."
+            exit 1
+          fi
+
+          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: |
+          dist_dir="build/release/dist"
+          rm -rf build/release
+          mkdir -p "${dist_dir}"
+          shopt -s nullglob
+
+          uv build --wheel --sdist --out-dir "${dist_dir}" --no-create-gitignore
+          project_wheels=("${dist_dir}"/*.whl)
+          if [[ "${#project_wheels[@]}" -ne 1 ]]; then
+            echo "::error title=Unexpected wheel count::Expected one project wheel, found ${#project_wheels[@]}."
+            exit 1
+          fi
+          source_distributions=("${dist_dir}"/*.tar.gz)
+          if [[ "${#source_distributions[@]}" -ne 1 ]]; then
+            echo "::error title=Unexpected source distribution count::Expected one source distribution, found ${#source_distributions[@]}."
+            exit 1
+          fi
+          wheel_path="${project_wheels[0]}"
+          wheel_name="$(basename "${wheel_path}")"
+          source_distribution_path="${source_distributions[0]}"
+          checksum_path="${wheel_path}.sha256"
+
+          (
+            cd "$(dirname "${wheel_path}")"
+            shasum -a 256 "${wheel_name}" > "$(basename "${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}"
+
+      - 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
+
+          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: Write release notes
+        id: notes
+        run: |
+          release_tag="${{ steps.release.outputs.tag }}"
+          wheel_name="${{ steps.build.outputs.wheel_name }}"
+          notes_path="build/release/release-notes.md"
+          cat > "${notes_path}" <<EOF
+          ## Install
+
+          Install from PyPI:
+
+          \`\`\`sh
+          pip install src-py-lib
+          \`\`\`
+
+          Install from the release wheel:
+
+          \`\`\`sh
+          pip install "https://github.com/sourcegraph/src-py-lib/releases/download/${release_tag}/${wheel_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.
+          EOF
+          echo "path=${notes_path}" >> "${GITHUB_OUTPUT}"
+
+      - name: Upload workflow artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: src-py-lib-release
+          path: |
+            ${{ steps.build.outputs.wheel_path }}
+            ${{ steps.build.outputs.checksum_path }}
+            ${{ steps.notes.outputs.path }}
+
+      - name: Upload PyPI artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: pypi-distributions
+          path: |
+            ${{ steps.build.outputs.wheel_path }}
+            ${{ steps.build.outputs.source_distribution_path }}
+
+      - 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 }}"
+
+          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
+          else
+            gh release create "${release_tag}" \
+              "${wheel_path}" \
+              "${checksum_path}" \
+              --title "${release_tag}" \
+              --notes-file "${notes_path}" \
+              --verify-tag
+          fi
+
+  pypi:
+    name: Publish PyPI package
+    needs: wheel
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/src-py-lib/
+
+    steps:
+      - name: Download built distribution
+        uses: actions/download-artifact@v7
+        with:
+          name: pypi-distributions
+          path: dist
+
+      - name: Publish PyPI package
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

src_py_lib-0.1.1/.gitignore

@@ -0,0 +1,20 @@
+# Ignore
+__pycache__
+.DS_Store
+.pypirc
+.pyright
+.pytest_cache
+.ruff_cache
+.venv
+*.env*
+*.gql
+*.py[cod]
+*.py[oc]
+*.yaml
+build/
+dist/
+wheels/
+
+# Allow
+!.env.example
+!.markdownlint-cli2.yaml

src_py_lib-0.1.1/.markdownlint-cli2.yaml

@@ -0,0 +1,9 @@
+globs:
+  - "**/*.md"
+ignores:
+  - ".venv/**"
+  - "build/**"
+  - "dist/**"
+config:
+  MD013:
+    line_length: 100

src_py_lib-0.1.1/.python-version

@@ -0,0 +1 @@
+3.11

src_py_lib-0.1.1/AGENTS.md

@@ -0,0 +1,179 @@
+# Agents
+
+<!-- HUMAN-MAINTAINED - START -->
+
+## Project principles
+
+- This repo is public, never write non-public information in this repo
+- Keep code and docs brief, for humans to read / understand / audit quickly
+- Reuse and improve existing solutions / approaches / designs / helpers / tools / patterns,
+  before adding new / similar ones
+- Keep runtime dependencies minimal; justify new dependencies in code review
+- Preserve unrelated user or agent edits in the worktree
+
+## Standard commands
+
+```sh
+npx --yes markdownlint-cli2
+uv sync
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run python -m unittest discover -s tests
+```
+
+<!-- HUMAN-MAINTAINED - END -->
+
+<!-- AGENT-MAINTAINED - START -->
+
+## Toolchain
+
+- Use `uv` for dependency management, virtualenv creation, and command running
+- Use pyright in strict mode; fix linting / typing issues instead of suppressing them
+- Use ruff for formatting, import sorting, and linting
+
+## Runtime standards
+
+- Configure the root logger by default (`logger_name=""`) so project modules
+  and shared `src_py_lib` modules are captured by the same handlers
+- Startup logs should include command, sanitized runtime config, commit when
+  available, and log file path when applicable
+- Use shared HTTP/client helpers for timeout policy, API error wrapping, and
+  rate-limit handling
+
+## Code organization
+
+- Put importable package code under `src/`
+- Put tests under `tests/`
+- Keep module-level constants near the top of each module, after imports
+- Prefer specific package/module names over broad `helpers` or `utils` modules
+
+## Release process
+
+- The tagged source commit must already contain the package version it
+  releases. Do not make the release workflow edit `pyproject.toml`.
+- The tag must be `vMAJOR.MINOR.PATCH`, and `.github/workflows/release.yml`
+  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:
+
+```sh
+set -euo pipefail
+
+VERSION=0.1.1
+BRANCH="release-v${VERSION}"
+
+git fetch origin --tags --prune
+git switch main
+git pull --ff-only
+git switch -c "${BRANCH}"
+
+uv run python - "${VERSION}" <<'PY'
+from pathlib import Path
+import re
+import sys
+
+version = sys.argv[1]
+path = Path("pyproject.toml")
+text = path.read_text()
+new_text = re.sub(
+    r'(?m)^version = "[^"]+"$',
+    f'version = "{version}"',
+    text,
+    count=1,
+)
+if new_text == text:
+    raise SystemExit("pyproject.toml version was not updated")
+path.write_text(new_text)
+PY
+
+uv lock
+```
+
+- Validate before opening the PR:
+
+```sh
+set -euo pipefail
+
+uv lock --check
+npx --yes markdownlint-cli2
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run python -m unittest discover -s tests
+uv build --wheel --sdist --out-dir /tmp/src-py-lib-release-check --no-create-gitignore
+rm -rf /tmp/src-py-lib-release-check
+```
+
+- Commit, push, open the PR, wait for checks, then merge it. If review is
+  required, stop after `gh pr checks` and ask for review before merging.
+
+```sh
+set -euo pipefail
+
+VERSION=0.1.1
+BRANCH="release-v${VERSION}"
+GH_REPO="sourcegraph/src-py-lib"
+
+git add pyproject.toml uv.lock
+git commit -m "Release v${VERSION}"
+git push -u origin "${BRANCH}"
+
+gh pr create \
+  --repo "${GH_REPO}" \
+  --base main \
+  --head "${BRANCH}" \
+  --title "Release v${VERSION}" \
+  --body "Bump src-py-lib package metadata to ${VERSION}."
+
+gh pr checks "${BRANCH}" --repo "${GH_REPO}" --watch --fail-fast
+gh pr merge "${BRANCH}" --repo "${GH_REPO}" --squash --delete-branch
+```
+
+- Tag the merged `main` commit. Do not tag a branch commit.
+
+```sh
+set -euo pipefail
+
+VERSION=0.1.1
+
+git fetch origin --tags --prune
+git switch main
+git pull --ff-only
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
+```
+
+- Watch the release workflow and confirm the GitHub release and PyPI project.
+
+```sh
+set -euo pipefail
+
+VERSION=0.1.1
+GH_REPO="sourcegraph/src-py-lib"
+
+RUN_ID="$(
+  gh run list \
+    --repo "${GH_REPO}" \
+    --workflow release.yml \
+    --branch "v${VERSION}" \
+    --limit 1 \
+    --json databaseId \
+    --jq '.[0].databaseId // empty'
+)"
+test -n "${RUN_ID}"
+gh run watch "${RUN_ID}" --repo "${GH_REPO}" --exit-status
+gh release view "v${VERSION}" --repo "${GH_REPO}"
+uvx --from pip pip index versions src-py-lib
+```
+
+- If a pushed tag points at the wrong commit, move it only after explicit
+  human approval.
+
+## Before finishing changes
+
+- Re-read edited files for organization and stale comments
+- Update `README.md` when setup or user-facing behavior changes
+- Update this `AGENTS.md` only with durable project-specific discoveries
+
+<!-- AGENT-MAINTAINED - END -->

src_py_lib-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sourcegraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src_py_lib-0.1.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: src-py-lib
+Version: 0.1.1
+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
+Author: Sourcegraph
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Sourcegraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Description-Content-Type: text/markdown
+
+# src-py-lib
+
+Reusable libraries for Sourcegraph projects
+
+## Experimental - This is not a supported Sourcegraph product
+
+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.
+
+## Install
+
+From PyPI:
+
+```sh
+uv add src-py-lib
+```
+
+From this repository:
+
+```sh
+uv add git+https://github.com/sourcegraph/src-py-lib.git
+```
+
+## Use it for
+
+- Typed config models loaded from defaults, `.env`, environment variables, and CLI flags
+- Root logger setup with terminal output, optional JSONL events, timing, and run metadata
+- A shared `httpx` JSON client with timeouts, retries, `Retry-After`, and contextual errors
+- Small helpers for TSV output, JSON caches, GraphQL pagination, and batched GraphQL queries
+- Thin clients for Sourcegraph, Linear, Slack, GitHub, Google Sheets, and 1Password
+
+Prefer vendor SDKs when they handle complex auth, token refresh, quota behavior,
+pagination, retries, or request models better than a thin wrapper
+
+## Quick example
+
+Define a project config, parse it once, and configure logging at startup:
+
+```python
+from pathlib import Path
+
+import src_py_lib as src
+
+
+class LinearExportConfig(src.LinearClientConfig):
+    output_dir: Path = src.config_field(
+        default=Path("."),
+        env_var="LINEAR_EXPORT_OUTPUT_DIR",
+        cli_flag="--output-dir",
+        metavar="PATH",
+        help="Directory for generated files.",
+    )
+
+config = src.parse_args(LinearExportConfig, description="Export Linear data")
+
+with src.logging(config):
+    client = src.linear_client_from_config(config)
+    client.validate()
+    src.info("Starting export", output_dir=str(config.output_dir))
+```
+
+- Config precedence is code defaults, `.env`, shell environment, then CLI overrides
+- `parse_args` resolves `op://...` references by default
+- Mark sensitive fields with `secret=True` so config snapshots redact resolved values
+- `src.logging()` configures the root logger by default so project code and `src_py_lib` internals
+  share the same handlers
+- Use `event()` for timed work, `stage()` for workflow context, and
+  `info()` / `warning()` / `error()` for structured one-off events
+
+## Development
+
+```sh
+uv sync
+uv run ruff format .
+uv run ruff check .
+uv run pyright
+uv run python -m unittest discover -s tests
+npx --yes markdownlint-cli2
+```