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:
BUKVARIX_DB_PATHenv var — explicit override for one process/session.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).- 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--jsonrendering.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.