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

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

@@ -6,8 +6,8 @@ on:
       - "v*"
   workflow_dispatch:
     inputs:
-      tag:
-        description: "Existing release tag to publish, for example v0.1.0"
+      version:
+        description: "Package version to publish, for example 0.1.0 or v0.1.0"
         required: true
         type: string
 
@@ -16,7 +16,7 @@ permissions:
   pull-requests: read
 
 concurrency:
-  group: release-${{ github.event.inputs.tag || github.ref_name }}
+  group: release-${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
   cancel-in-progress: false
 
 defaults:
@@ -24,15 +24,41 @@ defaults:
     shell: bash
 
 jobs:
+  release_ref:
+    name: Resolve release tag
+    runs-on: ubuntu-24.04
+    outputs:
+      tag: ${{ steps.release.outputs.tag }}
+      version: ${{ steps.release.outputs.version }}
+
+    steps:
+      - name: Resolve release tag
+        id: release
+        env:
+          RELEASE_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
+        run: |
+          release_input="${RELEASE_INPUT}"
+          if [[ ! "${release_input}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error title=Invalid release version::Use MAJOR.MINOR.PATCH or vMAJOR.MINOR.PATCH, got '${release_input}'."
+            exit 1
+          fi
+
+          release_version="${release_input#v}"
+          release_tag="v${release_version}"
+          echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
+          echo "version=${release_version}" >> "${GITHUB_OUTPUT}"
+
   validate:
     name: Validate
+    needs: release_ref
     uses: ./.github/workflows/validate.yml
     with:
-      ref: ${{ github.event.inputs.tag || github.ref }}
+      ref: ${{ needs.release_ref.outputs.tag }}
       build-package: false
 
   wheel:
     name: Build wheel
+    needs: release_ref
     runs-on: ubuntu-24.04
     env:
       IMPORT_NAME: src_py_lib
@@ -45,7 +71,7 @@ jobs:
         with:
           fetch-depth: 0
           persist-credentials: false
-          ref: ${{ github.event.inputs.tag || github.ref }}
+          ref: ${{ needs.release_ref.outputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -66,7 +92,7 @@ jobs:
       - name: Validate release inputs
         id: release
         env:
-          RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+          RELEASE_TAG: ${{ needs.release_ref.outputs.tag }}
         run: |
           release_tag="${RELEASE_TAG}"
           if [[ ! "${release_tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
@@ -80,29 +106,19 @@ jobs:
           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
-
-          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}'."
+          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."
             exit 1
           fi
 
           echo "tag=${release_tag}" >> "${GITHUB_OUTPUT}"
+          echo "version=${release_tag#v}" >> "${GITHUB_OUTPUT}"
 
       - name: Build distributions
         id: build
         run: |
+          release_version="${{ steps.release.outputs.version }}"
           dist_dir="build/release/dist"
           rm -rf build/release
           mkdir -p "${dist_dir}"
@@ -123,6 +139,22 @@ jobs:
           wheel_name="$(basename "${wheel_path}")"
           source_distribution_path="${source_distributions[0]}"
           source_distribution_name="$(basename "${source_distribution_path}")"
+          case "${wheel_name}" in
+            src_py_lib-"${release_version}"-*.whl)
+              ;;
+            *)
+              echo "::error title=Wheel version mismatch::Expected wheel version ${release_version}, got '${wheel_name}'."
+              exit 1
+              ;;
+          esac
+          case "${source_distribution_name}" in
+            src_py_lib-"${release_version}".tar.gz)
+              ;;
+            *)
+              echo "::error title=Source distribution version mismatch::Expected source distribution version ${release_version}, got '${source_distribution_name}'."
+              exit 1
+              ;;
+          esac
           wheel_checksum_path="${wheel_path}.sha256"
           source_distribution_checksum_path="${source_distribution_path}.sha256"
 
@@ -214,7 +246,7 @@ jobs:
 
   github-release:
     name: Publish GitHub release assets
-    needs: [validate, wheel]
+    needs: [release_ref, validate, wheel]
     runs-on: ubuntu-24.04
     permissions:
       contents: write
@@ -230,7 +262,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
-          RELEASE_TAG: ${{ github.event.inputs.tag || github.ref_name }}
+          RELEASE_TAG: ${{ needs.release_ref.outputs.tag }}
         run: |
           release_tag="${RELEASE_TAG}"
           notes_path="$(find release-assets -name release-notes.md -print -quit)"

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

@@ -158,6 +158,7 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v6
         with:
+          fetch-depth: 0
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
 
@@ -217,6 +218,7 @@ jobs:
       - name: Check out code
         uses: actions/checkout@v6
         with:
+          fetch-depth: 0
           persist-credentials: false
           ref: ${{ inputs.ref || github.ref }}
 

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/.gitignore

@@ -10,6 +10,7 @@ __pycache__
 *.gql
 *.py[cod]
 *.py[oc]
+*.swp
 *.yaml
 build/
 dist/
@@ -17,4 +18,4 @@ wheels/
 
 # Allow
 !.env.example
-!.markdownlint-cli2.yaml
+!.markdownlint-cli2.yaml

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/AGENTS.md

@@ -51,111 +51,28 @@ uv run python -m unittest discover -s tests
 
 ## 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:
-- 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.
+- Package versions are derived from Git tags through `hatch-vcs`.
+- `pyproject.toml` must use `dynamic = ["version"]`; do not add a hard-coded
+  `project.version` for releases.
+- The release tag must be `vMAJOR.MINOR.PATCH` and point at a commit reachable
+  from `origin/main`.
+- The release workflow builds from the tag and checks that wheel and source
+  distribution filenames match the tag version before publishing.
+- Do not make the release workflow edit `pyproject.toml` or `uv.lock`.
+- Tag the remote head of `main` directly:
 
 ```sh
 set -euo pipefail
 
-VERSION=0.1.4
-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
-actionlint
-npx --yes markdownlint-cli2@0.22.1
-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.4
-BRANCH="release-v${VERSION}"
+VERSION_INPUT=<next-version>
+VERSION="${VERSION_INPUT#v}"
 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.4
-
+[[ "${VERSION_INPUT}" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]]
 git fetch origin --tags --prune
-git switch main
-git pull --ff-only
-git tag "v${VERSION}"
+MAIN_COMMIT="$(git rev-parse origin/main)"
+git tag -a "v${VERSION}" "${MAIN_COMMIT}" -m "Release 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.4
-GH_REPO="sourcegraph/src-py-lib"
 
 RUN_ID="$(
   gh run list \

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: src-py-lib
-Version: 0.1.5
+Version: 0.1.8
 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

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

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
 
 [dependency-groups]
@@ -10,7 +10,7 @@ dev = [
 
 [project]
 name = "src-py-lib"
-version = "0.1.5"
+dynamic = ["version"]
 description = "Reusable libraries for Sourcegraph projects"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -44,6 +44,9 @@ Issues = "https://github.com/sourcegraph/src-py-lib/issues"
 [tool.hatch.build.targets.wheel]
 packages = ["src/src_py_lib"]
 
+[tool.hatch.version]
+source = "vcs"
+
 [tool.pyright]
 include = ["src/src_py_lib", "tests"]
 typeCheckingMode = "strict"

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

@@ -10,5 +10,8 @@
       ],
       "allowedVersions": "<3.12"
     }
+  ],
+  "schedule": [
+    "at any time"
   ]
 }

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

@@ -52,6 +52,8 @@ from src_py_lib.utils.config import (
     Config,
     ConfigError,
     config_field,
+    config_field_names,
+    config_help_formatter,
     config_snapshot,
 )
 from src_py_lib.utils.config import (
@@ -150,6 +152,8 @@ __all__ = [
     "TraceContext",
     "aliased_batched_query",
     "config_field",
+    "config_field_names",
+    "config_help_formatter",
     "config_snapshot",
     "configure_logging",
     "critical",

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

@@ -25,7 +25,6 @@ from src_py_lib.utils.logging import (
     traceparent_header,
 )
 
-DEFAULT_SOURCEGRAPH_ENDPOINT = "https://sourcegraph.com"
 SOURCEGRAPH_EXTERNAL_SERVICE_NODE_TYPE: Final[str] = "ExternalService"
 SOURCEGRAPH_REPOSITORY_NODE_TYPE: Final[str] = "Repository"
 REQUEST_TRACE_HEADER: Final[str] = "X-Sourcegraph-Request-Trace"
@@ -158,11 +157,13 @@ class SourcegraphClientConfig(Config):
     """Config fields needed to build a Sourcegraph API client."""
 
     src_endpoint: str = config_field(
-        default=DEFAULT_SOURCEGRAPH_ENDPOINT,
+        default="",
         env_var="SRC_ENDPOINT",
         cli_flag="--src-endpoint",
         metavar="URL",
-        help=f"Sourcegraph instance URL (default: {DEFAULT_SOURCEGRAPH_ENDPOINT})",
+        help="Sourcegraph instance URL",
+        help_group="Sourcegraph",
+        required=True,
     )
     src_access_token: str = config_field(
         default="",
@@ -170,6 +171,7 @@ class SourcegraphClientConfig(Config):
         cli_flag="--src-access-token",
         metavar="TOKEN",
         help="Sourcegraph access token, or op:// secret reference",
+        help_group="Sourcegraph",
         secret=True,
         required=True,
     )
@@ -206,8 +208,29 @@ class SourcegraphClient:
             require_https=not self.allow_insecure_http,
         )
 
-    def graphql(self, query: str, variables: Mapping[str, JSONValue] | None = None) -> JSONDict:
-        return self._client().execute(query, variables)
+    def graphql(
+        self,
+        query: str,
+        variables: Mapping[str, JSONValue] | None = None,
+        *,
+        follow_pages: bool = True,
+        page_size: int | None = None,
+        first_variable: str = "first",
+        after_variable: str = "after",
+    ) -> JSONDict:
+        """Execute one Sourcegraph GraphQL operation.
+
+        Set `follow_pages=False` when the caller owns pagination, such as
+        aliased queries with one cursor per alias.
+        """
+        return self._client().execute(
+            query,
+            variables,
+            follow_pages=follow_pages,
+            page_size=page_size,
+            first_variable=first_variable,
+            after_variable=after_variable,
+        )
 
     def stream_connection_nodes(
         self,

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/src/src_py_lib/utils/config.py

@@ -16,7 +16,7 @@ from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass, replace
 from pathlib import Path
 from types import UnionType
-from typing import Any, Final, Literal, TypeVar, Union, cast, get_args, get_origin
+from typing import Any, Final, Literal, TypeAlias, TypeVar, Union, cast, get_args, get_origin
 
 from dotenv import dotenv_values
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
@@ -33,6 +33,7 @@ DEFAULT_CONFIG_ENV_FILE: Final[Path] = Path(".env")
 CONFIG_HELP_MIN_POSITION: Final[int] = 24
 CONFIG_HELP_MAX_POSITION_LIMIT: Final[int] = 48
 CONFIG_HELP_PADDING: Final[int] = 4
+DEFAULT_CONFIG_HELP_GROUP: Final[str] = "Config"
 _CONFIG_OPTION_KEY: Final[str] = "src_py_lib_config_option"
 _MISSING: Final[object] = object()
 
@@ -67,6 +68,7 @@ class ConfigOption:
     cli_const: object | None = None
     metavar: str | None = None
     help: str = ""
+    help_group: str = DEFAULT_CONFIG_HELP_GROUP
     secret: bool = False
     required: bool = False
 
@@ -78,6 +80,7 @@ class Config(BaseModel):
 
 
 ConfigType = TypeVar("ConfigType", bound=Config)
+ConfigFieldSource: TypeAlias = str | type[Config]
 
 
 def config_field(
@@ -91,6 +94,7 @@ def config_field(
     cli_const: object | None = None,
     metavar: str | None = None,
     help: str = "",
+    help_group: str = DEFAULT_CONFIG_HELP_GROUP,
     secret: bool = False,
     required: bool = False,
     gt: int | float | None = None,
@@ -110,6 +114,7 @@ def config_field(
         cli_const=cli_const,
         metavar=metavar,
         help=help,
+        help_group=help_group,
         secret=secret,
         required=required,
     )
@@ -140,6 +145,38 @@ def config_options(config_cls: type[Config]) -> tuple[ConfigOption, ...]:
     return tuple(options)
 
 
+def config_field_names(*sources: ConfigFieldSource) -> tuple[str, ...]:
+    """Return Config field names from Config classes and explicit field names.
+
+    Use this to define reusable CLI argument sets from Config mixins while
+    keeping the field metadata defined once on the Config classes.
+    """
+    names: list[str] = []
+    for source in sources:
+        if isinstance(source, str):
+            names.append(source)
+            continue
+        names.extend(option.field_name for option in config_options(source))
+    return tuple(dict.fromkeys(names))
+
+
+def config_help_formatter(
+    config_cls: type[Config],
+    *,
+    include_env_file: bool = True,
+    include_fields: Iterable[str] | None = None,
+    exclude_fields: Iterable[str] = (),
+) -> type[argparse.HelpFormatter]:
+    """Return a help formatter aligned for the selected Config fields."""
+    max_help_position = _config_help_max_position(
+        config_cls,
+        include_env_file=include_env_file,
+        include_fields=include_fields,
+        exclude_fields=exclude_fields,
+    )
+    return _config_help_formatter(max_help_position)
+
+
 def load_config_env_file(path: Path | None) -> dict[str, str]:
     """Load key/value pairs from a `.env` file.
 
@@ -192,22 +229,19 @@ def add_config_arguments(
     config_cls: type[Config],
     *,
     include_env_file: bool = True,
+    include_fields: Iterable[str] | None = None,
+    exclude_fields: Iterable[str] = (),
 ) -> None:
     """Add Config CLI flags to an argparse parser."""
-    group = parser.add_argument_group(
-        "Config",
-        "These options override matching environment variables and .env values",
-    )
-    if include_env_file:
-        group.add_argument(
-            "--env-file",
-            dest="env_file",
-            default=None,
-            metavar="PATH",
-            help="Read Config .env values from PATH (default: .env)",
-        )
+    groups: dict[str, Any] = {}
 
-    for option in config_options(config_cls):
+    def argument_group(title: str) -> Any:
+        if title not in groups:
+            groups[title] = parser.add_argument_group(title)
+        return groups[title]
+
+    for option in _selected_config_options(config_cls, include_fields, exclude_fields):
+        group = argument_group(option.help_group or DEFAULT_CONFIG_HELP_GROUP)
         field_info = config_cls.model_fields[option.field_name]
         argument_kwargs: dict[str, Any] = {
             "dest": option.field_name,
@@ -227,6 +261,15 @@ def add_config_arguments(
                 argument_kwargs["action"] = option.cli_action
         group.add_argument(option.cli_flag, *option.cli_aliases, **argument_kwargs)
 
+    if include_env_file:
+        argument_group(DEFAULT_CONFIG_HELP_GROUP).add_argument(
+            "--env-file",
+            dest="env_file",
+            default=None,
+            metavar="PATH",
+            help="Read Config .env values from PATH (default: .env)",
+        )
+
 
 def config_parse_args(
     config_cls: type[ConfigType],
@@ -235,6 +278,8 @@ def config_parse_args(
     argv: Sequence[str] | None = None,
     description: str | None = None,
     include_env_file: bool = True,
+    include_fields: Iterable[str] | None = None,
+    exclude_fields: Iterable[str] = (),
     env: Mapping[str, str] | None = None,
     base_dir: Path | None = None,
     resolve_op_refs: bool = True,
@@ -242,12 +287,23 @@ def config_parse_args(
     require: Iterable[str] = (),
 ) -> ConfigType:
     """Parse Config CLI flags and return a validated Config model."""
-    max_help_position = _config_help_max_position(config_cls, include_env_file=include_env_file)
+    formatter_class = config_help_formatter(
+        config_cls,
+        include_env_file=include_env_file,
+        include_fields=include_fields,
+        exclude_fields=exclude_fields,
+    )
     argument_parser = parser or argparse.ArgumentParser(
         description=description,
-        formatter_class=_config_help_formatter(max_help_position),
+        formatter_class=formatter_class,
+    )
+    add_config_arguments(
+        argument_parser,
+        config_cls,
+        include_env_file=include_env_file,
+        include_fields=include_fields,
+        exclude_fields=exclude_fields,
     )
-    add_config_arguments(argument_parser, config_cls, include_env_file=include_env_file)
     args = argument_parser.parse_args(argv)
     try:
         return load_config_from_args(
@@ -277,12 +333,14 @@ def _config_help_max_position(
     config_cls: type[Config],
     *,
     include_env_file: bool,
+    include_fields: Iterable[str] | None = None,
+    exclude_fields: Iterable[str] = (),
 ) -> int:
     """Return help-column width based on this Config's CLI arguments."""
     invocation_lengths = [len("--env-file PATH")] if include_env_file else []
     invocation_lengths.extend(
         _config_option_invocation_length(config_cls, option)
-        for option in config_options(config_cls)
+        for option in _selected_config_options(config_cls, include_fields, exclude_fields)
     )
     longest_invocation = max(invocation_lengths, default=0)
     return min(
@@ -291,6 +349,48 @@ def _config_help_max_position(
     )
 
 
+def _selected_config_options(
+    config_cls: type[Config],
+    include_fields: Iterable[str] | None,
+    exclude_fields: Iterable[str],
+) -> tuple[ConfigOption, ...]:
+    """Return options selected by field or env-var names.
+
+    When include_fields is set, its order controls the returned option order.
+    Without include_fields, Config model field order is preserved.
+    """
+    options = config_options(config_cls)
+    excluded = _selected_config_field_names(options, exclude_fields) or set()
+    if include_fields is None:
+        return tuple(option for option in options if not _option_is_selected(option, excluded))
+
+    options_by_field_name = {option.field_name: option for option in options}
+    return tuple(
+        options_by_field_name[field_name]
+        for field_name in _selected_config_field_names_in_order(options, include_fields)
+        if field_name not in excluded
+    )
+
+
+def _selected_config_field_names_in_order(
+    options: tuple[ConfigOption, ...],
+    selected: Iterable[str],
+) -> tuple[str, ...]:
+    """Return selected field names in caller order after validating names."""
+    names = (_option_by_name(options, name).field_name for name in selected)
+    return tuple(dict.fromkeys(names))
+
+
+def _selected_config_field_names(
+    options: tuple[ConfigOption, ...],
+    selected: Iterable[str] | None,
+) -> set[str] | None:
+    """Return selected field names after validating field or env-var names."""
+    if selected is None:
+        return None
+    return {_option_by_name(options, name).field_name for name in selected}
+
+
 def _config_option_invocation_length(config_cls: type[Config], option: ConfigOption) -> int:
     """Return argparse-style option invocation length for help alignment."""
     field_info = config_cls.model_fields[option.field_name]
@@ -452,6 +552,7 @@ def _config_option_payload(option: ConfigOption) -> dict[str, object]:
         "cli_const": option.cli_const,
         "metavar": option.metavar,
         "help": option.help,
+        "help_group": option.help_group,
         "secret": option.secret,
         "required": option.required,
     }
@@ -467,6 +568,7 @@ def _config_option_from_payload(payload: Mapping[str, object]) -> ConfigOption |
     cli_nargs = payload.get("cli_nargs")
     metavar = payload.get("metavar")
     help_text = payload.get("help")
+    help_group = payload.get("help_group")
     return ConfigOption(
         field_name="",
         env_var=env_var,
@@ -477,6 +579,7 @@ def _config_option_from_payload(payload: Mapping[str, object]) -> ConfigOption |
         cli_const=payload.get("cli_const"),
         metavar=metavar if isinstance(metavar, str) else None,
         help=help_text if isinstance(help_text, str) else "",
+        help_group=help_group if isinstance(help_group, str) else DEFAULT_CONFIG_HELP_GROUP,
         secret=payload.get("secret") is True,
         required=payload.get("required") is True,
     )

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/src/src_py_lib/utils/logging.py

@@ -100,6 +100,7 @@ class LoggingConfig(Config):
         cli_flag="--src-log-level",
         metavar="LEVEL",
         help="Log level (default: INFO)",
+        help_group="Logging",
     )
     verbose: bool = config_field(
         default=False,
@@ -108,6 +109,7 @@ class LoggingConfig(Config):
         cli_aliases=("-v",),
         cli_action="store_true",
         help="Alias for --src-log-level DEBUG",
+        help_group="Logging",
     )
     quiet: bool = config_field(
         default=False,
@@ -116,6 +118,7 @@ class LoggingConfig(Config):
         cli_aliases=("-q",),
         cli_action="store_true",
         help="Alias for --src-log-level WARNING",
+        help_group="Logging",
     )
     silent: bool = config_field(
         default=False,
@@ -124,6 +127,7 @@ class LoggingConfig(Config):
         cli_aliases=("-s",),
         cli_action="store_true",
         help="Alias for --src-log-level ERROR",
+        help_group="Logging",
     )
 
     @model_validator(mode="after")

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/tests/test_import.py

@@ -27,6 +27,8 @@ class PackageImportTest(unittest.TestCase):
         self.assertIsNotNone(src_py_lib.SourcegraphClient)
         self.assertIsNotNone(src_py_lib.SourcegraphClientConfig)
         self.assertIsNotNone(src_py_lib.config_field)
+        self.assertIsNotNone(src_py_lib.config_field_names)
+        self.assertIsNotNone(src_py_lib.config_help_formatter)
         self.assertIsNotNone(src_py_lib.gh_cli_token)
         self.assertIsNotNone(src_py_lib.gcloud_adc_access_token)
         self.assertIsNotNone(src_py_lib.info)

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/tests/test_logging_http_clients.py

@@ -50,6 +50,7 @@ from src_py_lib.utils.config import (
     add_config_arguments,
     config_env_file_from_args,
     config_field,
+    config_field_names,
     config_overrides_from_args,
     config_parse_args,
     config_snapshot,
@@ -198,6 +199,32 @@ class MultilineHelpConfig(Config):
     )
 
 
+class GroupedHelpConfig(Config):
+    """Config model with grouped help sections."""
+
+    alpha: str = config_field(
+        default="",
+        env_var="GROUPED_HELP_ALPHA",
+        cli_flag="--alpha",
+        help="Alpha option",
+        help_group="First group",
+    )
+    beta: str = config_field(
+        default="",
+        env_var="GROUPED_HELP_BETA",
+        cli_flag="--beta",
+        help="Beta option",
+        help_group="Second group",
+    )
+    gamma: str = config_field(
+        default="",
+        env_var="GROUPED_HELP_GAMMA",
+        cli_flag="--gamma",
+        help="Gamma option",
+        help_group="First group",
+    )
+
+
 class SnapshotOrderConfig(Config):
     """Config model whose field names and env-var names sort differently."""
 
@@ -340,6 +367,8 @@ class ConfigTest(unittest.TestCase):
         add_config_arguments(parser, SourcegraphExampleConfig)
         args = parser.parse_args(
             [
+                "--src-endpoint",
+                "https://sourcegraph.example.com",
                 "--src-access-token",
                 "test-token",
                 "--repo-query",
@@ -355,10 +384,10 @@ class ConfigTest(unittest.TestCase):
         )
         client = sourcegraph_client_from_config(config)
 
-        self.assertEqual(config.src_endpoint, "https://sourcegraph.com")
+        self.assertEqual(config.src_endpoint, "https://sourcegraph.example.com")
         self.assertEqual(config.src_access_token, "test-token")
         self.assertEqual(config.repo_query, "repo:example")
-        self.assertEqual(client.endpoint, "https://sourcegraph.com")
+        self.assertEqual(client.endpoint, "https://sourcegraph.example.com")
         self.assertEqual(client.token, "test-token")
 
     def test_load_config_uses_precedence_and_pydantic_types(self) -> None:
@@ -456,6 +485,82 @@ class ConfigTest(unittest.TestCase):
             },
         )
 
+    def test_config_field_names_combines_config_classes_and_fields(self) -> None:
+        self.assertEqual(
+            config_field_names(SourcegraphClientConfig, LoggingConfig, "page_size"),
+            (
+                "src_endpoint",
+                "src_access_token",
+                "src_log_level",
+                "verbose",
+                "quiet",
+                "silent",
+                "page_size",
+            ),
+        )
+
+    def test_add_config_arguments_can_select_reusable_field_sets(self) -> None:
+        parser = argparse.ArgumentParser()
+        add_config_arguments(
+            parser,
+            ExampleConfig,
+            include_fields=("token", "page_size", "EXAMPLE_LABELS"),
+            exclude_fields=("page_size",),
+        )
+
+        args = parser.parse_args(["--token", "raw-token", "--labels", "one,two"])
+
+        self.assertEqual(
+            config_overrides_from_args(ExampleConfig, args),
+            {
+                "token": "raw-token",
+                "labels": "one,two",
+            },
+        )
+        with redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+            parser.parse_args(["--page-size", "50"])
+
+    def test_config_parse_args_help_only_shows_selected_fields(self) -> None:
+        stdout = io.StringIO()
+
+        with redirect_stdout(stdout), self.assertRaises(SystemExit) as raised:
+            config_parse_args(
+                ExampleConfig,
+                argv=["--help"],
+                env={},
+                resolve_op_refs=False,
+                include_fields=("labels", "token"),
+            )
+
+        self.assertEqual(raised.exception.code, 0)
+        help_text = stdout.getvalue()
+        self.assertIn("--token TOKEN", help_text)
+        self.assertIn("--labels CSV", help_text)
+        self.assertLess(help_text.index("--labels CSV"), help_text.index("--token TOKEN"))
+        self.assertNotIn("--page-size", help_text)
+        self.assertNotIn("--include-archived", help_text)
+
+    def test_config_parse_args_groups_help_by_field_metadata(self) -> None:
+        stdout = io.StringIO()
+
+        with redirect_stdout(stdout), self.assertRaises(SystemExit) as raised:
+            config_parse_args(
+                GroupedHelpConfig,
+                argv=["--help"],
+                env={},
+                resolve_op_refs=False,
+                include_fields=("beta", "alpha", "gamma"),
+            )
+
+        self.assertEqual(raised.exception.code, 0)
+        help_text = stdout.getvalue()
+        self.assertLess(help_text.index("Second group:"), help_text.index("First group:"))
+        self.assertLess(help_text.index("First group:"), help_text.index("Config:"))
+        self.assertLess(help_text.index("--alpha"), help_text.index("--gamma"))
+        self.assertIn("Second group:\n  --beta", help_text)
+        self.assertIn("First group:\n  --alpha", help_text)
+        self.assertNotIn("override matching environment variables", help_text)
+
     def test_config_arguments_support_aliases_actions_and_optional_values(self) -> None:
         parser = argparse.ArgumentParser()
         add_config_arguments(parser, CommandStyleConfig)
@@ -1424,6 +1529,35 @@ class ClientTest(unittest.TestCase):
         self.assertEqual(http.calls[0]["url"], "https://sourcegraph.example.com/.api/graphql")
         self.assertEqual(http.calls[0]["headers"], {"Authorization": "token token"})
 
+    def test_sourcegraph_client_graphql_can_disable_auto_pagination(self) -> None:
+        http = RecordingHTTP(
+            [
+                {
+                    "data": {
+                        "users": {
+                            "nodes": [{"username": "alice"}],
+                            "pageInfo": {"hasNextPage": True, "endCursor": "cursor-1"},
+                        }
+                    }
+                }
+            ]
+        )
+        client = SourcegraphClient("https://sourcegraph.example.com", "token", http=http)
+        query = """
+query Users($first: Int!, $after: String) {
+  users(first: $first, after: $after) {
+    nodes { username }
+    pageInfo { hasNextPage endCursor }
+  }
+}
+"""
+
+        data = client.graphql(query, page_size=1, follow_pages=False)
+
+        self.assertEqual(json_dict(data.get("users"))["nodes"], [{"username": "alice"}])
+        self.assertEqual(len(http.calls), 1)
+        self.assertEqual(http.calls[0]["json_body"]["variables"], {"first": 1})
+
     def test_sourcegraph_client_rejects_http_endpoint_by_default(self) -> None:
         with self.assertRaisesRegex(ValueError, "https:// URL"):
             SourcegraphClient("http://sourcegraph.example.com", "token")
@@ -1536,7 +1670,7 @@ class ClientTest(unittest.TestCase):
 
         with src.trace_context(root_context):
             self.assertEqual(
-                client.graphql("query Viewer { currentUser { username } }"),
+                client.graphql("query Viewer { currentUser { username } }", follow_pages=False),
                 {"currentUser": {"username": "alice"}},
             )
         traces = client.drain_traces()

{src_py_lib-0.1.5 → src_py_lib-0.1.8}/uv.lock

@@ -254,7 +254,6 @@ wheels = [
 
 [[package]]
 name = "src-py-lib"
-version = "0.1.5"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },