NAZK API Python Client

A strictly typed, async-first Python client for the NAZK API (ЄДИНИЙ ДЕРЖАВНИЙ РЕЄСТР ДЕКЛАРАЦІЙ).

Features

Strictly Typed: Fully typed API responses using Pydantic. Handles complex document structures (Steps 0-17).
Async First: Built on top of httpx for high-performance asynchronous IO.
Resilient: Automatic retries for transient errors (502, 503, 504) with exponential backoff via tenacity.
Easy Pagination: Async generator for fetching paginated lists of documents effortlessly.
Type-safe Filtering: Builder pattern/kwargs-based filtering for searching documents.

Installation

pip install -r requirements.txt

Quick Start

Fetching Countries

import asyncio
from nazk_api import NAZKClient

async def main():
    async with NAZKClient() as client:
        countries = await client.get_countries()
        print(f"Found {len(countries)} countries.")

asyncio.run(main())

Searching Documents

import asyncio
from nazk_api import NAZKClient, SearchFilter

async def search_documents():
    async with NAZKClient() as client:
        # Define search criteria using the strongly typed SearchFilter
        filter_obj = SearchFilter(query="Шевченко")
        
        # Fetch first page of results
        docs = await client.get_documents_list(filter_obj)
        print(f"Found {len(docs)} documents on the first page.")
        
        if docs:
            # Fetch full details of the first document
            doc_id = docs[0].id
            details = await client.get_document(doc_id)
            print(f"Document {doc_id} details:", details)

asyncio.run(search_documents())

Pagination with Async Generators

You can lazily iterate over all documents that match your search filter across multiple pages:

import asyncio
from nazk_api import NAZKClient, SearchFilter

async def fetch_all():
    async with NAZKClient() as client:
        filter_obj = SearchFilter(query="Шевченко")
        async for doc in client.get_all_documents(filter_obj):
            print(f"Document ID: {doc.id}, Name: {doc.lastname} {doc.firstname}")

asyncio.run(fetch_all())

Development & Testing

We use pytest for testing. The tests are anonymized and do not rely on hardcoded document IDs. Instead, they dynamically search the API to find current documents to test against.

python -m pytest tests/

License

MIT

FilesExpand file tree

README.md

Latest commit

History