qtx-nav-core 0.2.2

Python NAV core client port skeleton

qtx-nav-core

Python package for the NAV Online Szamla core client.

Install/package name: qtx-nav-core

Python import package: qtx_nav_core

Quick Start Map

If you open this package months later, start with this mental model:

• NavAuth: technical user credentials for NAV signing and authentication
• NavSoftwareInfo: software metadata block included in each request
• NavRequestContext: immutable container that carries auth, software info, and request ID prefix
• NavRequestBody: abstract extension point for a concrete NAV operation
• NavXmlRequestBuilder: creates the full NAV XML document from context plus request body
• NavApiClient: low-level HTTP client for XML and multipart requests
• NavCallSpec: one request execution description, including path and optional file upload settings
• NavRequestRunner: high-level orchestrator that builds XML, sends the request, and validates NAV result status
• NavDocumentStatus: parsed summary of NAV's <result> block
• NavApiKind / NAV_XML_PROFILES: NAV API profile selection for OSA/eVAT namespaces and request versions
• NavUtils: shared helper methods for hashing, decoding, status parsing, and response formatting

Typical Usage Flow

1. Create a NavAuth instance.
2. Create a NavSoftwareInfo instance for the calling application.
3. Create a NavRequestContext from the auth object and software info.
4. Implement a concrete NavRequestBody subclass for the target NAV endpoint.
5. Create a NavApiClient with the NAV base URL.
6. Create a NavRequestRunner with the API client and request context.
7. Execute the call with NavCallSpec.
8. Read the returned XML or let NavValidationError surface NAV-side failures.

API Kind Detection

NavApiClient.api_kind is derived from the configured base URL. URLs containing .eafa. use NavApiKind.EVAT; URLs containing .onlineszamla. use NavApiKind.OSA. NavRequestRunner passes this value to NavXmlRequestBuilder, which then selects the matching XML namespaces and request version from NAV_XML_PROFILES.

Software Info

NavSoftwareInfo is required for every request. Create and pass a populated instance into NavRequestContext; otherwise XML generation raises ValueError before the NAV call is sent.

The current model defaults are empty development placeholders only. Real callers must set the software identifier, name, version, developer contact, developer country code, and developer tax number explicitly.

software = NavSoftwareInfo(
    software_id="MOCK-EVAT-12345678",
    software_name="Mock eVAT Client",
    software_operation="LOCAL_SOFTWARE",
    software_main_version="1.0",
    software_dev_name="Mock Developer",
    software_dev_contact="[e-mail]",
    software_dev_country_code="HU",
    software_dev_tax_number="12345678",
)

context = NavRequestContext(auth=auth, software=software)

Package Reference

For a longer in-package reminder that is shipped with the installed distribution, see qtx_nav_core/docs/package_map.md.

Scope

This package currently contains:

• package layout matching the Dart core library
• minimal public exports
• placeholder modules for models, services, and utils
• test directory and tooling configuration

Package layout

qtx_nav_core/
  models/
  services/
  utils/
tests/

Development

pip install -e .[dev]
pytest
ruff check .