Metadata-Version: 2.4
Name: qtx-nav-core
Version: 0.2.3
Summary: Python NAV core client
Author: Internal
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"

# 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 requests, multipart uploads, and multipart responses
- `NavApiResponse`: HTTP status, headers, parsed XML document, and received multipart parts
- `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 `NavApiResponse.document` and, for multipart responses, `NavApiResponse.parts`.
9. Let `NavValidationError` surface NAV-side failures when enabled.

## Response Handling

`NavRequestRunner.call(...)` returns the full `NavApiResponse`, not only the XML document. This keeps the HTTP status and headers available and also exposes multipart response parts returned by NAV.

For endpoints that can return multipart content, pass `multipart_response=True` to `runner.call(...)`. The client sends an `Accept` header that allows multipart responses, parses the MIME parts, stores them in `NavApiResponse.parts`, and uses the first XML part as `NavApiResponse.document` when one is present.

```python
response = runner.call(
    NavCallSpec(path="/query", request_body=request_body),
    multipart_response=True,
)

xml_document = response.document
for part in response.iter_parts():
    print(part.name, part.filename, part.content_type, len(part.content))
```

## 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.

```python
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="mock.dev@example.com",
    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
- public exports for auth, request building, request running, API responses, and multipart parts
- models, services, and utils for NAV XML and HTTP calls
- tests and tooling configuration

## Package layout

```text
qtx_nav_core/
  models/
  services/
  utils/
tests/
```

## Development

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

