harriers-lustr

Jurisdiction-agnostic company-register lookup. Give it a jurisdiction and a registration id (CZ: IČO), get back jurisdiction-neutral company data — name, VAT id, legal form, seat address, responsible tax office — through one small interface.

Bundled providers: CZ → ARES and SK → RPO (both real, public REST APIs). Framework-free (only depends on httpx); an optional Django cache adapter is included.

Install

From PyPI:

pip install harriers-lustr

Usage

import harriers_lustr

# Method 1 — the registration-id format for jurisdiction (drives input UI).
fmt = harriers_lustr.id_format("CZ")
print(fmt.label, fmt.example)          # "IČO" "27082440"

# Method 2 — the company data for a registration id.
subject = harriers_lustr.fetch_subject("CZ", "27082440")
print(subject.name)                    # "Alza.cz a.s."
print(subject.vat_id)                  # "CZ27082440"
print(subject.legal_form_name)         # "Akciová společnost"
print(subject.tax_office_code)         # "451"  (ÚFO resolved from the seat's kraj)

fetch_subject returns a frozen RegistrySubject dataclass and raises typed errors: InvalidRegistrationId, RegistryNotFound, RegistryUnavailable, UnknownJurisdiction (all subclasses of RegistryError).

harriers_lustr.jurisdictions() lists the supported jurisdictions for a picker.

Slovakia

The identity (name, legal form, seat) comes from RPO, which needs no auth. The VAT id (IČ DPH) lives in a separate register — the Financial Administration's OpenData portal — which needs a free, self-service API key:

harriers_lustr.configure_sk(fs_dph_key="…")     # or set LUSTR_SK_DPH_KEY in the environment

The key is required: the VAT lookup is a step of every SK company lookup, so a missing key or an unreachable FS register raises RegistryUnavailable instead of returning a subject. That way an empty vat_id always means "not a VAT payer" and never "could not be checked".

Caching

Lookups are cached (12h TTL) so repeated queries don't hit the register. By default the cache is a process-local in-memory store — zero config. To share a cache across processes, inject any backend with get/set/delete:

harriers_lustr.configure_cache(my_cache)

Django

An adapter over django.core.cache ships in harriers_lustr.contrib.django (imports Django lazily, so it stays an optional dependency). Wire it once at startup:

import harriers_lustr
from harriers_lustr.contrib.django import DjangoCache

harriers_lustr.configure_cache(DjangoCache())          # the "default" cache alias
harriers_lustr.configure_cache(DjangoCache("redis"))   # a named alias

Mapping a RegistrySubject onto your own models (an Organization, a contact/party, …) stays in your project — harriers-lustr only returns the neutral data.

Adding a jurisdiction

Subclass RegistryProvider (implement id_format + fetch, optionally normalize_id) and register it:

import harriers_lustr

class MyProvider(harriers_lustr.RegistryProvider):
    jurisdiction = "PL"
    name = "Polska"
    register_name = "KRS"
    def id_format(self): ...
    def fetch(self, registration_id): ...

harriers_lustr.register_provider(MyProvider())

Development

pip install -e ".[test]"
pytest

Releasing

The version is derived from the git tag (hatch-vcs). To cut a release:

git tag v0.1.0
git push origin v0.1.0

The CI publish job builds the sdist+wheel and uploads them to PyPI via trusted publishing (OIDC — no API token stored in CI). One-time prerequisite: the PyPI project harriers-lustr must list this GitLab repo as a trusted publisher — for the very first release, register a pending publisher on PyPI for gitlab.com namespace harriers, project lustr.

License

MIT — see LICENSE.