Skip to main content

Bukvarix

Local Wordstat-like CLI over a Bukvarix keyword dump (Moscow, frequencies only — no SERP data).

Development

uv sync
uv run bukvarix --help

The gate before a commit is gate check, run from the package root on this machine: the command is [publish] gate_command in .agents/antagor/antagor.toml. It covers ruff (security S rules included), ty, pytest with the coverage floor from pyproject.toml, the help snapshots and the consumer contracts.

Release

antagor publish runs the gate, bumps the last vX.Y.Z tag (the version comes from the tag — there is no version = in pyproject.toml), writes CHANGELOG.md, tags and pushes. At 0.x a breaking change is a minor bump.

Install

On this machine, from a local checkout:

uv tool install --editable .

On any other machine (any OS), from the Gitea package registry:

</code></pre>
<p>Or from a release tag:</p>
<pre><code class="language-bash">uv tool install "rb-bukvarix @ git+https://homeserver.tailee01ab.ts.net:3000/bolandeu/rb_bukvarix.git@vX.Y.Z"

This is also how an AI agent bootstraps this CLI on a fresh machine/sandbox where it isn't installed yet — see src/rb_bukvarix/data/SKILL.md.

Installed under the old distribution name bukvarix (before 0.3)? Remove it first, otherwise two tools claim the same bukvarix command: uv tool uninstall bukvarix.

Update an installed copy:

uv tool upgrade rb-bukvarix

After install, the command bukvarix is available globally on macOS, Linux and Windows alike — no shelling out, no hardcoded POSIX paths.

To pick up later changes of the cli-generator template, run uvx copier update --trust --defaults in this repo.

The database

bukvarix queries a single DuckDB file (~41GB on the real Moscow dump). It lives in the user data dir, never in the repo: platformdirs.user_data_dir("bukvarix")/rb_bukvarix.duckdb — on macOS ~/Library/Application Support/bukvarix/rb_bukvarix.duckdb, on Linux ~/.local/share/bukvarix/rb_bukvarix.duckdb. Path resolution, in order:

  1. BUKVARIX_DB_PATH env var — explicit override for one process/session.
  2. bukvarix db set-path PATH — persisted via the OS user config dir (survives across shells/processes without needing to be sourced from a shell profile, which a non-interactive process wouldn't see anyway).
  3. The user-data default above — the normal case; leave 1 and 2 unset unless the database really lives elsewhere.

search/freq fail with a structured DATABASE_NOT_READY error if nothing has been imported yet; stats --json always succeeds and reports keywords_rows: 0 in that case. Building the database from a raw Bukvarix

Architecture

This project follows a fixed CLI architecture:

  • src/rb_bukvarix/commands/ — argument parsing only, no business logic.
  • src/rb_bukvarix/core/ — services (including database-path resolution), the DuckDB query/import/normalize layer (core/db.py), models, errors.
  • src/rb_bukvarix/credentials/ — OS keychain (keyring) + env vars, kept for fleet-wide consistency; unused today (bukvarix has no external API).
  • src/rb_bukvarix/output/ — human (rich) and --json rendering.

Run bukvarix doctor to check environment and database readiness, and bukvarix --help for the full command surface. Every command supports --json for machine/agent consumption (envelope: {"ok": true, ...} on success, {"ok": false, "error": {"code", "message", "action"}} on failure); human-mode errors go to stderr, so stdout is always safe to pipe. db import-keywords/db normalize/db reindex mutate the database file in place and require --confirm (or an interactive yes) — see AGENTS.md for the backup discipline around them.

search/freq/stats/db ... work from any directory against one machine-wide database — no bukvarix init needed. init/status/config exist for parity with this CLI's sibling tools (a project can require a minimum CLI version via .bukvarix/config.toml's [cli] min_version) but hold no data bukvarix's own commands read.

See src/rb_bukvarix/data/SKILL.md for the agent-facing usage guide bundled with this package — install it into an AI tool with bukvarix skill install, or get it as plain text with bukvarix --ai (works even without file access).

Metadata

Release files for rb-bukvarix 0.6.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rb-bukvarix 0.6.7
File Size Uploaded Provenance Actions
rb_bukvarix-0.6.7.tar.gz 113.8 kB Without provenance Details for rb_bukvarix-0.6.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rb-bukvarix 0.6.7
File Interpreter ABI Platform Actions
rb_bukvarix-0.6.7-py3-none-any.whl Python 3 none any Details for rb_bukvarix-0.6.7-py3-none-any.whl

Total release size: 190.1 kB

Release files / rb_bukvarix-0.6.7.tar.gz

Download URL rb_bukvarix-0.6.7.tar.gz
Size 113.8 kB
Tags Source
SHA-256 checksum
How to use checksums
1e2e98baf226ccb62bc7b79f9bb1c5b5b8d1d89653210f59813ddad2c4149938
BLAKE2b-256 checksum
How to use checksums
ede33b5bbfe8cf3269d89934210395d5723dbedbd1653763a2daee92a9f1a0aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / rb_bukvarix-0.6.7-py3-none-any.whl

Download URL rb_bukvarix-0.6.7-py3-none-any.whl
Size 76.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
63fee2524f2cd5a377acc0002c9d2c5b326aff6ba1e4f358dd0fa044eb8dbb9c
BLAKE2b-256 checksum
How to use checksums
360978eea48acdcc675dc37a56beb15fd482fffc9da0fc8a8cd623f57efbe6ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for rb-bukvarix 0.6.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.7 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page