src-py-lib 0.1.0__py3-none-any.whl

src_py_lib/utils/tsv.py

@@ -0,0 +1,95 @@
+"""Aligned TSV file writing."""
+
+from __future__ import annotations
+
+import unicodedata
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Final
+
+DEFAULT_MAX_COLUMN_WIDTH: Final[int] = 100
+_ZERO_WIDTH_CATEGORIES: Final[frozenset[str]] = frozenset({"Cf", "Me", "Mn"})
+
+
+def write_tsv(
+    path: Path,
+    rows: Iterable[Mapping[str, object]],
+    *,
+    max_column_width: int = DEFAULT_MAX_COLUMN_WIDTH,
+) -> None:
+    """Write rows as a padded TSV table, inferring the header from row keys."""
+    data_rows = list(rows)
+    fieldnames = list(data_rows[0]) if data_rows else []
+    table: list[Mapping[str, object]] = []
+    if fieldnames:
+        table.append(dict(zip(fieldnames, fieldnames, strict=True)))
+    table.extend(data_rows)
+
+    widths = {
+        field: max(
+            display_width(
+                format_tsv_value(
+                    row.get(field, ""),
+                    field,
+                    max_column_width=max_column_width,
+                )
+            )
+            for row in table
+        )
+        for field in fieldnames
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as file:
+        for row in table:
+            values = [
+                pad_display(
+                    format_tsv_value(
+                        row.get(field, ""),
+                        field,
+                        max_column_width=max_column_width,
+                    ),
+                    widths[field],
+                )
+                for field in fieldnames
+            ]
+            file.write("\t".join(values) + "\n")
+
+
+def format_tsv_value(
+    value: object,
+    field: str,
+    *,
+    max_column_width: int = DEFAULT_MAX_COLUMN_WIDTH,
+) -> str:
+    """Return a single-line TSV cell value, truncating non-URL fields."""
+    text = str(value).replace("\r", " ").replace("\n", " ").replace("\t", " ")
+    if field == "url" or field.endswith("_url"):
+        return text
+    return text[:max_column_width]
+
+
+def display_width(value: str) -> int:
+    """Return terminal display width for padding aligned text columns."""
+    width = 0
+    for character in value:
+        if unicodedata.combining(character):
+            continue
+        if unicodedata.category(character) in _ZERO_WIDTH_CATEGORIES:
+            continue
+        width += 2 if unicodedata.east_asian_width(character) in {"F", "W"} else 1
+    return width
+
+
+def pad_display(value: str, width: int) -> str:
+    """Pad text to a target display width."""
+    return value + " " * max(width - display_width(value), 0)
+
+
+__all__ = [
+    "DEFAULT_MAX_COLUMN_WIDTH",
+    "display_width",
+    "format_tsv_value",
+    "pad_display",
+    "write_tsv",
+]

src_py_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: src-py-lib
+Version: 0.1.0
+Summary: Reusable Python helpers 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-adjacent Python projects
+
+This repo is the shared implementation layer for patterns which get
+rebuilt in separate scripts: API clients, HTTP retries/timeouts, structured logging,
+etc.
+
+## 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 another project
+
+```sh
+uv add git+https://github.com/sourcegraph/src-py-lib.git
+```
+
+## What is included
+
+- `src_py_lib.utils.logging` — centralized human stderr logs plus optional structured
+  JSONL events, run IDs, git commit metadata, context fields, event timing,
+  retention, startup metadata, and sanitized config snapshots.
+- `src_py_lib.utils.config` — Pydantic-backed `Config` models loaded from code
+  defaults, `python-dotenv` `.env` parsing, shell environment, and CLI
+  overrides, with typed values, required checks, safe snapshots, and `op://...`
+  reference resolution.
+- `src_py_lib.utils.http` — pooled `httpx` JSON HTTP client with a shared
+  30-second timeout, retry policy, `Retry-After` support, and contextual errors.
+- `src_py_lib.utils.tsv` — padded TSV writer for human-readable tabular exports,
+  with newline/tab cleanup, URL preservation, and Unicode-aware column widths.
+- `src_py_lib.clients.graphql` — shared GraphQL execution with automatic cursor
+  pagination, batched alias lookups, and schema introspection export.
+- `src_py_lib.clients.sourcegraph` — Sourcegraph GraphQL client with token
+  validation, endpoint normalization, connection streaming, and shared config
+  fields for `SRC_ENDPOINT` (default: `https://sourcegraph.com`) and
+  `SRC_ACCESS_TOKEN`.
+- `src_py_lib.clients.linear` — Linear GraphQL client with automatic cursor
+  handling, token validation, shared config fields, and injectable HTTP policy.
+- `src_py_lib.clients.slack` — Slack Web API client with token validation,
+  cursor pagination, and method pacing. Consider `slack_sdk` if usage grows
+  beyond simple GET, pagination, and rate-limit handling.
+- `src_py_lib.clients.github` — GitHub GraphQL client, PR URL parsing, and
+  batched PR lookups, with token validation. Defaults to `https://github.com`;
+  pass `github_url` for GitHub Enterprise Server. Keep lightweight for GraphQL;
+  GitHub SDKs help more for REST.
+- `src_py_lib.clients.one_password` — tiny 1Password CLI wrapper for signing in,
+  validating authenticated `op` access, and resolving `op://...` references after config loading.
+- `src_py_lib.clients.google_sheets` — Google Sheets API primitives with
+  spreadsheet access validation using gcloud Application Default Credentials or
+  a provided access token. Prefer Google's official libraries if Sheets usage
+  grows beyond small primitives, because auth, quota project, token refresh,
+  batching, and error shapes are subtle.
+
+Prefer this library for shared logging, HTTP policy, and thin API wrappers.
+Prefer vendor SDKs when they replace tricky auth, token refresh, retries,
+pagination, quota behavior, or complex request models.
+
+## Example
+
+Define one project-specific `Config` model, then load it once at CLI startup.
+For common CLI and client usage, import the curated root API:
+
+```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.")
+client = src.linear_client_from_config(config)
+print(f"Writing files under {config.output_dir}")
+```
+
+Config precedence is: code defaults, `.env`, shell environment, then CLI
+overrides. API client modules can provide shared Config base classes such as
+`LinearClientConfig`, and `parse_args` resolves `op://...` references by
+default. `config_field(default=...)` supports aliases, store-true /
+store-false command flags, optional values, numeric bounds, and string patterns
+for simple CLIs. Pass a custom `argparse.ArgumentParser` to `parse_args` only when you
+need parsing beyond Config fields. Help text preserves description and
+argument-help newlines, and reserves enough option-column width for long config
+flags. Mark sensitive fields with `secret=True` so snapshots do not expose
+resolved values.
+
+## Logging example
+
+Configure logging once at process startup. Prefer configuring the root logger
+(`logger_name=""`, the default) so project modules and shared `src_py_lib` modules
+such as `src_py_lib.utils.http` are captured by the same terminal and JSONL handlers.
+Use `logging()` in CLIs to configure logging, add the command field to all
+structured events, and emit standard run/startup/run-end metadata.
+Use `debug()`, `info()`, `warning()`, `error()`, and `critical()` for one-off
+structured events. Use `event()` blocks around timed work; they emit `trace`,
+`span`, and nested `parent_span` fields. Use `start_level="debug"` to hide
+noisy start events while keeping end timing visible, and
+`omit_success_status=True` for very high-volume success events. Use `stage()`
+for workflow context such as `stage="apply"`.
+When the root logger is configured, noisy `httpx`/`httpcore` records are suppressed;
+`HTTPClient` emits structured `http_request` events instead.
+Run-end events include HTTP attempt/byte/status/retry counters. Set
+`LoggingSettings.resource_sample_interval_seconds` to emit DEBUG
+`resource_sample` events and include process resource totals on run end. Set
+`SRC_LOG_LEVEL=INFO` for a run to omit DEBUG events from the log file.
+`LoggingConfig` includes `--verbose/-v`, `--quiet/-q`, and `--silent/-s`
+shortcuts (also available as `SRC_LOG_VERBOSE`, `SRC_LOG_QUIET`, and
+`SRC_LOG_SILENT`). Use `logging_settings_from_config()` to build
+`LoggingSettings` from those conventions.
+
+```python
+import src_py_lib as src
+
+with src.logging({"src_token": "provided"}):
+    src.info("sync_started", repository_count=3)
+
+    client = src.SourcegraphClient("https://sourcegraph.example.com", "token")
+    data = client.graphql("query Viewer { currentUser { username } }")
+```
+
+## 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
+```

src_py_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+src_py_lib/__init__.py,sha256=RRUHFF4TtGAkwN_m_IGXDiDEqE9THi9z9sHLiYMnT6s,3958
+src_py_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src_py_lib/clients/__init__.py,sha256=Ux21Bu2_NNFklyF4M7iYzMUM4kTRcNiVIrjpz3hxpbM,103
+src_py_lib/clients/github.py,sha256=F3ZLVs69_8_1_RvQXCBZeklKsYtA4P7qD_v3TFPM4WA,5202
+src_py_lib/clients/google_sheets.py,sha256=jBEjODZsQDiZ-z2aM_Vld7kFy8TNvxcIe_qr89e9nvY,4481
+src_py_lib/clients/graphql.py,sha256=z9ekJXmVwocVAUkDSBZXJEOsIBzVGjynhqpXXXmvp04,14940
+src_py_lib/clients/linear.py,sha256=z5eAdDGfaiGaBD8WhF06vmuvUmnWqpVfqT6aLY-YV5U,2780
+src_py_lib/clients/one_password.py,sha256=EvAcpMpUVpF4Bk1Y-uFLQPx8AlFbFPheWoOr9q4asG0,3666
+src_py_lib/clients/slack.py,sha256=lemaTSFQpDzAKhS7e7U1JNU3pnw2kZlrX_WOYYcTMog,5271
+src_py_lib/clients/sourcegraph.py,sha256=osn93J0i42FEhqPoDUyqjtUfOZ5Bnh96wF_SMRTqgzU,4304
+src_py_lib/utils/__init__.py,sha256=TcJJo8jlZgN09c4z90QBHoEPO8US9RYkFLsR46igZ7c,107
+src_py_lib/utils/config.py,sha256=hHB-pDFmYzPJRXVpQnxPyTQR8fO4rFGJb4cnusDqQ-8,21406
+src_py_lib/utils/http.py,sha256=0Q7ZmbHch6dnuMoUOnAoqQ-qLHzV7QpWlhBVvbHmcKk,10606
+src_py_lib/utils/json_cache.py,sha256=LfbOIKGdY1Ug5Hj81jG6cvdh4cY6R4FNbgsQloG6kq4,1327
+src_py_lib/utils/json_types.py,sha256=0V8Ukd3fB9X6VVcatHAxjTdXjuTqxAlzUWgAQQVG6lQ,1993
+src_py_lib/utils/logging.py,sha256=a-4hdfYKf8qmvXcOlZZTeHuicqcN6N7fnRfldmVVs6A,32667
+src_py_lib/utils/tsv.py,sha256=hXz2xwZL-8v-iiD66P8WrPWPno3_5Ns-n2ysi3-Ce4Y,2723
+src_py_lib-0.1.0.dist-info/METADATA,sha256=QMZ57HM9i3tE8uAPWsvCgRXNAPvlK3losUKXLyCr0bw,7334
+src_py_lib-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+src_py_lib-0.1.0.dist-info/licenses/LICENSE,sha256=FCl6gJG7mu3Vdm030o3A0oG-_L60JJSlkc9f2T0rSGI,1068
+src_py_lib-0.1.0.dist-info/RECORD,,

src_py_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

src_py_lib-0.1.0.dist-info/licenses/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.