qsv-client 0.1.0__tar.gz

qsv_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - name: Download the latest qsv release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then target=x86_64-unknown-linux-musl; else target=aarch64-apple-darwin; fi
+          mkdir -p "$RUNNER_TEMP/qsv"
+          gh release download --repo dathere/qsv --pattern "qsv-*-${target}.zip" --dir "$RUNNER_TEMP/qsv"
+          unzip -o -q "$RUNNER_TEMP"/qsv/*.zip -d "$RUNNER_TEMP/qsv"
+          chmod +x "$RUNNER_TEMP"/qsv/qsv*
+          ls "$RUNNER_TEMP/qsv"
+      - name: Unit tests and integration tests (qsv)
+        run: QSV_BIN="$RUNNER_TEMP/qsv/qsv" uv run pytest -v
+      - name: Integration tests (qsvlite)
+        run: QSV_BIN="$RUNNER_TEMP/qsv/qsvlite" uv run pytest -q tests/test_integration.py
+      - name: Integration tests (qsvdp)
+        if: runner.os == 'Linux'
+        run: QSV_BIN="$RUNNER_TEMP/qsv/qsvdp" uv run pytest -q tests/test_integration.py

qsv_client-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # PyPI Trusted Publishing: configure a publisher for this repo, workflow `publish.yml`
+    # and environment `pypi` at https://pypi.org/manage/account/publishing/
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

qsv_client-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+qsv_r*.log
+# roborev snapshots
+/.roborev/

qsv_client-0.1.0/.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

qsv_client-0.1.0/.serena/memories/conventions.md

@@ -0,0 +1,10 @@
+# Conventions
+
+- `Qsv` and `AsyncQsv` are hand-mirrored: same method set (`run`, `_run_unchecked`, `capabilities`, `version`, `_probe`, `_check_version_once`, conveniences). Any change to one must be applied to the other. In async, `capabilities`/`version` are coroutines, not properties.
+- Shared non-I/O logic lives in `_Base`; keep I/O in subclasses and `_process.py`.
+- `_process.py` is the only place that spawns/kills processes; it returns `RawResult` and leaves error classification to `_Base._finish` → `errors.error_from_run`.
+- Convenience methods take `(path, *args, **kw)` and forward `**kw` to `run`; `Arg` = str | int | float | PathLike.
+- New qsv error kind: add subclass in `errors.py`, map in `_KIND_TO_CLASS` (and `_EXIT_CODE_TO_CLASS` if it has a distinct exit code), export from `__init__.py`, update README errors table.
+- Full type hints everywhere (mypy strict, tests included). Google-style docstrings (`Args:`/`Raises:`) on public API; private helpers mostly undocumented.
+- Comments only for non-obvious WHY (lowercase, terse).
+- Tests: unit tests use the `fake_qsv(body)` fixture (conftest) — writes an executable Python script standing in for qsv; integration tests use `qsv`/`qsv_bin`/`csv_files` fixtures and skip without a real binary. Integration tests must pass on qsv, qsvlite and qsvdp.

qsv_client-0.1.0/.serena/memories/core.md

@@ -0,0 +1,22 @@
+# qsv-client — core
+
+Python library that runs the qsv CSV toolkit binary as a subprocess (qsv not bundled). Zero runtime deps. Sync `Qsv` + asyncio `AsyncQsv` with identical API.
+
+Related: stack/versions `mem:tech_stack`; dev/test/run commands `mem:suggested_commands`; code style & sync/async mirroring rules `mem:conventions`; done-checklist (ruff/mypy/pytest as CI runs them) `mem:task_completion`.
+
+## Source map (`src/qsv_client/`)
+- `client.py` — `_Base` (init, env building, argv, min-version check, `_finish` → result/exception), `Qsv`, `AsyncQsv`, `QsvResult`, `find_qsv` (`$QSV_BIN`, else first of qsv/qsvmcp/qsvdp/qsvlite on PATH).
+- `_process.py` — private spawn/kill layer: `run_sync`/`run_async` return `RawResult`; never raises qsv errors.
+- `errors.py` — `QsvError` hierarchy, exit-code constants, `parse_json_error`, `error_from_run` (kind→class via `_KIND_TO_CLASS`, fallback exit code→class via `_EXIT_CODE_TO_CLASS`).
+- `capabilities.py` — `Capabilities` dataclass; parsers `from_capabilities_json` (`qsv --capabilities`) and `from_version_output` (`--version` + `--list` fallback).
+- `__init__.py` — public re-exports; `py.typed` shipped.
+
+## Invariants
+- Every run gets `QSV_ERROR_FORMAT=json` forced in `_Base._build_env` (overrides user env). Older qsv ignores it → classify by exit code.
+- Success = exit code 0 or 255 (`SUCCESS_EXIT_CODES`; 255 = qsv "warning", e.g. broken pipe).
+- Timeout/cancel/KeyboardInterrupt: kill whole process group (POSIX `start_new_session`): SIGTERM, then SIGKILL after `kill_grace`. Timeout → `QsvTimeout` with exit code 124 (`EXIT_TIMEOUT`), raised even when `check=False`.
+- stdin is DEVNULL unless `stdin=` given.
+- LLM secrets go via env (`QSV_LLM_APIKEY`/`_BASE_URL`/`_MODEL`), never argv.
+- `min_version` is enforced inside `_probe` (so it holds however the capabilities cache is filled); `run()` calls `_check_version_once()` first; internal probes use `_run_unchecked` to avoid recursion.
+- Empty `command` string → argv is just `[binary, *args]` (used for `--version`/`--list`/`--capabilities`).
+- Windows: new process group, only qsv itself killed (children not reaped). Officially POSIX/macOS.

qsv_client-0.1.0/.serena/memories/memory_maintenance.md

@@ -0,0 +1,33 @@
+# Memory Maintenance
+
+## Discovery Model
+
+- Core principle: progressive discovery through references, building a graph of memories.
+- Initially, agents are provided with the list of all memories (names only).
+- Agents should read `mem:core` as the top-level entry point (graph root).
+  This memory should contain references to other memories covering major project domains.
+  The referenced memories shall, in turn, shall contain references to even more specific memories, and so on.
+  The depth of the graph shall depend on the project complexity.
+- Use topics/folders to group related memories in order to make the content structure explicit.
+  Folders can mirror project structure (e.g. modules like frontend/backend) or topics like debugging, architecture, etc.
+- Memory references must use a mem: prefix inside backticks, e.g. `mem:frontend/core`.
+  The surrounding text should clearly indicate when to read the memory/which content to expect.
+  The text should provide more precise guidance than the memory name alone, 
+  i.e. avoid a reference like "frontend debugging: `mem:frontend/debugging` and instead make clear which aspects of frontend debugging are covered.
+- Memories themselves should not contain information about when to read them; this is the responsibility of the referring memory.
+
+## Style
+
+Dense agent notes, not prose docs. Prefer invariants, terse bullets. 
+Avoid obvious context, rationale, and examples unless they prevent likely mistakes. 
+Keep guidance durable and generalizable, not task-local.
+
+## Add/update threshold
+
+Add or update memories only with stable, non-obvious project conventions that avoid complex rediscovery in the future.
+Do not add: quick-read facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon.
+
+## Maintenance Actions
+
+- Renaming memories: References are updated automatically if handled via Serena's memory rename tool.
+- Checking for stale memories (e.g. after deletion): Call `serena memories check` for a report.

qsv_client-0.1.0/.serena/memories/suggested_commands.md

@@ -0,0 +1,12 @@
+# Suggested commands
+
+- Setup: `uv sync`
+- All tests: `uv run pytest` (integration tests use `$QSV_BIN`, else `qsv` on PATH; skip if none)
+- Against a specific binary variant: `QSV_BIN=/path/to/qsvlite uv run pytest -q tests/test_integration.py`
+- Single test: `uv run pytest tests/test_process.py -k <name> -v`
+- Lint: `uv run ruff check .` (autofix: `--fix`)
+- Format: `uv run ruff format .` (CI uses `--check`)
+- Types: `uv run mypy` (files configured in pyproject)
+- Build wheel/sdist: `uv build` (outputs to `dist/`, gitignored)
+
+Darwin notes: BSD `sed -i` needs `''` arg; `grep -P` unavailable (use `rg` or `grep -E`).

qsv_client-0.1.0/.serena/memories/task_completion.md

@@ -0,0 +1,9 @@
+# Task completion
+
+Run (mirrors CI lint + test jobs), all must pass:
+1. `uv run ruff format .`
+2. `uv run ruff check .`
+3. `uv run mypy`
+4. `uv run pytest` (with a real qsv available so integration tests don't skip)
+
+If the public API or error table changed, update README.md accordingly. If sync client changed, confirm the async mirror changed too (see `mem:conventions`).

qsv_client-0.1.0/.serena/memories/tech_stack.md

@@ -0,0 +1,11 @@
+# Tech stack
+
+- Python >=3.10 (ruff `target-version = py310`; CI matrix 3.10–3.13 on ubuntu + macos). Use `from __future__ import annotations`; no 3.11+ only stdlib features.
+- No runtime dependencies — keep it that way (stdlib `subprocess`/`asyncio` only).
+- Package/env manager: uv (`uv.lock` committed); dev deps in `[dependency-groups].dev`: pytest, pytest-asyncio, mypy, ruff.
+- Build: hatchling, src layout (`src/qsv_client`). License AGPL-3.0-or-later.
+- pytest: `asyncio_mode = "auto"` (async tests need no marker).
+- mypy `strict = true` over `src` AND `tests`.
+- ruff line-length 100; lint rules E,F,W,I,B,UP,SIM,RUF; `ruff format` enforced.
+- Release: GitHub release published → `.github/workflows/publish.yml` builds with `uv build`, PyPI Trusted Publishing (env `pypi`). Version is static in `pyproject.toml`.
+- External: real qsv binary needed only for integration tests; CI downloads latest dathere/qsv release and tests qsv, qsvlite, and (Linux) qsvdp variants.

qsv_client-0.1.0/.serena/project.yml

@@ -0,0 +1,169 @@
+# the name by which the project can be referenced within Serena/when chatting with the LLM.
+project_name: "qsv-client"
+
+# list of language servers to start when using the LSP backend; choose from:
+#   ada                    al                     angular                ansible                bash
+#   bsl                    clojure                cpp                    cpp_ccls               crystal
+#   csharp                 csharp_omnisharp       cue                    dart                   deno
+#   elixir                 elm                    erlang                 fortran                fsharp
+#   gdscript               gleam                  go                     groovy                 haskell
+#   haxe                   hlsl                   html                   java                   json
+#   julia                  kotlin                 latex                  lean4                  lua
+#   luau                   markdown               matlab                 msl                    nextflow
+#   nix                    ocaml                  pascal                 perl                   php
+#   php_phpactor           php_phpantom           powershell             python                 python_basedpyright
+#   python_jedi            python_pyrefly         python_ty              qml                    r
+#   rego                   ruby                   ruby_solargraph        rust                   scala
+#   scss                   solidity               svelte                 swift                  systemverilog
+#   terraform              toml                   typescript             typescript_vts         vue
+#   wolfram                yaml                   zig
+#   (This list may be outdated; generated with scripts/print_language_list.py;
+#   For the current list, see values of the LanguageServerId enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)
+# For some languages, there are several alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For Svelte projects, use svelte (subsumes typescript/javascript for .svelte projects; requires npm)
+#   - For Deno projects, use deno (serves the same .ts/.js files as typescript; requires the deno CLI on PATH)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some language servers require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple language servers, the first language server that supports a given file will be used for that file.
+# The first language server is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+language_servers:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# optional shell command to run before the language backend (LSP or JetBrains) is initialised.
+# the command runs in the project root directory and is only executed if the project is trusted
+# (see trusted_project_path_patterns in the global configuration).
+# serena waits for the command to exit: a non-zero exit code is logged as an error but does not
+# abort activation. a per-project timeout (activation_command_timeout, default 180s) is the safety
+# backstop for non-terminating commands; on expiry the process is killed and activation continues.
+# example: activation_command: "npx nx run-many -t build"
+activation_command:
+
+# maximum time in seconds to wait for activation_command to complete before killing it (default 180s).
+# must be a positive number.
+activation_command_timeout: 180.0
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# The settings are considered only if the project is trusted (see global configuration to define trusted projects).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#language-server-specific-settings
+ls_specific_settings: {}
+
+# list of workspace folder paths (LSP backend only).
+# These folders will be used to build up Serena's symbol index.
+# Paths must be within the project root and should thus be relative to the project root.
+# Furthermore, the paths should not be filtered by ignore settings.
+# Default setting: The entire project root folder (".") is considered.
+# In (large) monorepos, this can be used to index only subfolders of the project root, e.g.
+#   ls_workspace_folders:
+#     - "./subproject1"
+#     - "./subproject2"
+ls_workspace_folders:
+- "."
+
+# list of additional workspace folder paths for cross-package reference support.
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries, but these folders are not indexed by Serena,
+# i.e. the respective symbols will not be found using Serena's symbol search tools.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+ls_additional_workspace_folders: []
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Important: quote patterns that start with `*`, otherwise YAML treats them as aliases.
+# Example:
+#   ignored_paths:
+#     - "examples/**"
+#     - ".worktrees/**"
+#     - "**/bin/**"
+#     - "**/obj/**"
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
+fixed_tools: []
+
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+default_modes:
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

qsv_client-0.1.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+Python library that runs the [qsv](https://github.com/dathere/qsv) CSV toolkit as a subprocess
+(qsv itself is not bundled). Sync `Qsv` and asyncio `AsyncQsv` clients with the same API.
+No runtime dependencies. Python 3.10+.
+
+## Commands
+
+```bash
+uv sync                                  # setup
+uv run pytest                            # all tests; integration tests need $QSV_BIN or qsv on PATH
+QSV_BIN=/path/to/qsvlite uv run pytest -q tests/test_integration.py   # other binary variants
+uv run ruff format . && uv run ruff check . && uv run mypy            # must be clean before done
+```
+
+CI runs lint, format check, and mypy, plus tests on ubuntu/macos x Python 3.10–3.13 against
+qsv, qsvlite, and qsvdp (Linux only).
+
+## Layout (`src/qsv_client/`)
+
+- `client.py`: `_Base` (env, argv, min-version check, `_finish` turns the raw result into
+  `QsvResult` or an exception), `Qsv`, `AsyncQsv`, `find_qsv`.
+- `_process.py`: the only place that spawns and kills processes. Returns `RawResult` and never
+  raises qsv errors.
+- `errors.py`: the `QsvError` hierarchy and exit-code constants. `error_from_run` maps errors
+  by JSON `kind` first, then by exit code.
+- `capabilities.py`: parses `qsv --capabilities`, falling back to `--version` + `--list`.
+
+## Invariants
+
+- `_Base._build_env` always sets `QSV_ERROR_FORMAT=json`. Older qsv versions ignore it, so
+  their errors are classified by exit code.
+- Exit codes 0 and 255 (qsv's "warning") count as success.
+- On timeout, cancellation, or KeyboardInterrupt, the whole process group is killed: SIGTERM,
+  then SIGKILL after `kill_grace`. A timeout raises `QsvTimeout` (exit code 124) even when
+  `check=False`.
+- LLM settings for describegpt are passed as env vars (`QSV_LLM_*`), never on argv.
+- `min_version` is enforced inside `_probe`, so it holds however the capabilities cache is
+  filled. Internal probes use `_run_unchecked` to avoid recursing into the version check.
+
+## Conventions
+
+- `Qsv` and `AsyncQsv` are mirrored by hand. Apply every change to both. In `AsyncQsv`,
+  `capabilities` and `version` are coroutines, not properties.
+- Keep it dependency-free and 3.10-compatible (`from __future__ import annotations`).
+- mypy is strict and covers `tests/` too. Ruff line length is 100.
+- New error kind: add a subclass in `errors.py`, map it in `_KIND_TO_CLASS` (and
+  `_EXIT_CODE_TO_CLASS` if it has its own exit code), export it from `__init__.py`, and update
+  the README errors table.
+- Tests: unit tests use the `fake_qsv(body)` fixture (an executable Python stand-in for qsv).
+  Integration tests use the `qsv`/`csv_files` fixtures, skip without a real binary, and must
+  pass on qsv, qsvlite, and qsvdp.