vacant 0.4.11

Python bindings for the vacant Rust engine — domain availability via authoritative DNS.

vacant — domain availability via authoritative DNS

Python bindings for the vacant Rust engine. Asks the authoritative TLD nameservers directly instead of WHOIS — fast, no rate limits, no waiting.

The wheel ships the same Rust engine compiled in, with a small Python facade and a vacant CLI entry point. Lockstep-versioned with the vacant crate: vacant 0.3.x (Python) wraps vacant 0.3.x (Rust) exactly.

Prefer a browser? vacant.alltuner.com is a hosted web UI built on vacant — a separate app that uses this package, not something it installs.

Install

Pick the path that matches how you'll use it:

CLI

brew install alltuner/tap/vacant   # macOS, Linux — native Rust binary
cargo install vacant               # any platform with a Rust toolchain
uvx vacant google.com              # one-shot, no install (Python wheel)

The brew / cargo paths give you the native Rust binary (instant startup, ideal for daily use). uvx runs the Python wheel — convenient when you don't want to install anything, slightly slower to start because it boots a Python interpreter.

MCP server

Expose vacant to AI agents over the Model Context Protocol (stdio). Needs the mcp extra:

uvx --from 'vacant[mcp]' vacant mcp

It registers one tool — check_domains(domains, verify=false) — returning a {domain, status} per input. Point any MCP client at it:

{ "mcpServers": { "vacant": { "command": "uvx", "args": ["--from", "vacant[mcp]", "vacant", "mcp"] } } }

Library

pip install vacant
# or with uv:
uv add vacant

from vacant import check_many, Status

results = check_many(["example.com", "anthropic.com", "totally-made-up-zxqv.cat"])
for r in results:
    print(r.domain, r.status.value, r.detail)

The on-disk SQLite cache is shared with the Rust CLI — runs against the same ~/.cache/vacant/results.db, so the brew binary and a Python script see each other's results.

from vacant import DiskCache, check_many

cache = DiskCache()  # default ~/.cache/vacant/results.db
results = check_many(["example.com"], cache=cache)

How it works

vacant.check_many calls into the Rust engine via PyO3 (vacant._core). The engine:

1. Normalizes the input.
2. Looks up cache; returns hits immediately.
3. Runs a per-zone precheck (length, charset, reserved labels) from the bundled rules.toml.
4. For inputs that pass, asks the parent zone's NS directly. Delegation → registered; NXDOMAIN/NODATA → unconfirmed (not delegated, not verified). Pass verify=True to confirm unconfirmed names against the registry's RDAP endpoint, promoting them to available (404) or registered (200, e.g. a held domain). available only ever means RDAP-confirmed.

available is not a registrability guarantee, though: new gTLD registries (especially community/city zones like .barcelona, .cat, .amsterdam, .berlin) keep reservation and premium lists invisible to DNS, WHOIS, and RDAP, so a name can read available yet still be refused at checkout (e.g. radio.barcelona). Tracked for an in-engine fix in #26.

Cache shape, rules format, and verdict semantics are all the engine's — see alltuner/vacant for the source of truth.

Develop

The Python package lives in the alltuner/vacant monorepo alongside the Rust engine, so dev commands run from the repo root:

just                 # menu
just py-develop      # build the maturin extension into the local venv
just py-check        # ruff + pytest
just py-wheel        # build a release wheel locally

License

MIT — see ../LICENSE.