Fatoority Python bindings
This package wraps Diplomat-generated native bindings with the public fatoora
Python API. Install with pip install fatoority and import as fatoora. See Diplomat bindings.
Development (uv)
uv venv
uv pip install .
Build a wheel (uv)
uv build --wheel
Wheels (CI)
- GitHub Actions uses
cibuildwheelto produce platform wheels indist/(wheel-only publishing). - See
.github/workflows/python.ymlfor the build matrix.
Notes
- The build step compiles
fatoora-ffiwithcargo build -p fatoora-ffi --release. - The shared library is bundled into the Python package.
- Building the native extension requires CMake and a C++20 compiler. Nanobind is pinned in the build dependencies. Reinstall the package after native changes.
- ZATCA API responses are exposed via opaque handles with getters (no JSON payloads).
- Errors are raised as typed exceptions mapped from FFI error codes (see
FfiErrorKind). Each exception exposes.code,.kind, and.details, a dictionary containing structured validation issues or diagnostics. Unknown codes remain available on a genericFfiError. - Reinstall the package after changes; the extension loads its bundled shared library.
Examples
python examples/load_lib.py
python examples/invoice_basic.py
python examples/invoice_parse.py
Tests
uv pip install -e .[dev]
SKIP_ZATCA_LIVE_API=1 uv run pytest tests
High-level API
from fatoora import InvoiceBuilder, InvoiceSubType, InvoiceTypeKind, VatCategory
builder = InvoiceBuilder.new(
invoice_type=InvoiceTypeKind.TAX,
invoice_subtype=InvoiceSubType.SIMPLIFIED,
)
builder.set_id("INV-1")
builder.set_uuid("123e4567-e89b-12d3-a456-426614174000")
builder.set_issue_datetime("2024-01-01T12:30:00Z")
builder.set_currency("SAR")
builder.set_previous_invoice_hash("hash")
builder.set_invoice_counter(1)
builder.set_payment_means_code("10")
builder.set_vat_category(VatCategory.STANDARD)
builder.set_seller(
name="Acme Inc",
country_code="SAU",
city="Riyadh",
street="King Fahd",
building_number="1234",
postal_code="12222",
vat_id="399999999900003",
)
builder.add_line_item(
description="Item",
quantity="1.0",
unit_code="PCE",
unit_price="100.0",
vat_rate="15.0",
vat_category=VatCategory.STANDARD,
)
invoice = builder.build()
print(invoice.xml())
set_issue_datetime expects a ZATCA ISO UTC timestamp string (YYYY-MM-DDTHH:MM:SSZ).
Local ZATCA validation
from fatoora import Config, validate_zatca_invoice_from_str
with Config() as config:
report = validate_zatca_invoice_from_str(
config, xml, previous_invoice_hash=previous_hash_from_history,
)
if not report["is_valid"]:
print(report["stages"])
The report retains warnings and distinguishes rejection from incomplete coverage.
Missing predecessor context leaves the report incomplete. Execution failures raise
a typed exception with any partial report in error.details["report"]. Standard
invoices skip signature/QR checks in this SDK profile. Local integrity does not
establish issuer trust or remote acceptance. The wheel embeds runtime schemas
and native rules; Java, SDK files and a source checkout are unnecessary.
1 maintainer
Metadata
1 maintainer
Release files for fatoority 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 82.0 MB
Release files / fatoority-0.4.0-cp313-cp313-win_amd64.whl
| Download URL | fatoority-0.4.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
fa7cebda7c9099d7dd7adf9e8c63466e4c6739c99a7b6cd17f0c5f811c69c304
|
|
BLAKE2b-256 checksum How to use checksums |
814f04c67944d31073d44d2938421b7015a93bab95e6efc4c6ac7d4bae76bdb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | fatoority-0.4.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
e64dacb7c04daa30a83d822f58d6d10fe0e0b133addb1d54fce1492f47fcdf5c
|
|
BLAKE2b-256 checksum How to use checksums |
341a9c8317b1e37e189bb4b913a0ac6fed86228d6d2040f49759fbd057f29d73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | fatoority-0.4.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c355f1aaabfceda1b00a93fffdcffac94c26667772ebab68c1f64c12173e15a4
|
|
BLAKE2b-256 checksum How to use checksums |
aed646e7b8355cdd680338b675bb4630dd847bbc6be67142546e863619a401cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp312-cp312-win_amd64.whl
| Download URL | fatoority-0.4.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
21fc6e1127c7784d40022d6977c52a439251da3735c8501c95f9419e5e34286f
|
|
BLAKE2b-256 checksum How to use checksums |
45a9a09be480437b79b20741d3d06b7266e6cada44f795d7bbe7e3da30285fe4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | fatoority-0.4.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
4931b9586f75465d0dc3753d80243cadc5c04fe6142d941d6246dc1b6571ca68
|
|
BLAKE2b-256 checksum How to use checksums |
4a62943825bdc055bec12cae5fe1d06f82b53174fb61e6dcd0f3ad073d1b8a85
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | fatoority-0.4.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c9cc49f9a57f8eb14a5887893e8fddf9e36395da2f1ebcb980412c09e6b5f642
|
|
BLAKE2b-256 checksum How to use checksums |
fb1c4fc2047ebea55a349d5bdeda37b3833b9b1bfa31449166ea9ecb7d75b726
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp311-cp311-win_amd64.whl
| Download URL | fatoority-0.4.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8f6535a413249fcc8d44e9a3db75a612de376928460384281175f49342668f8e
|
|
BLAKE2b-256 checksum How to use checksums |
026156fc443dc6ac61da08e4f1ab5f1f6b4484180875a52ffc71510c6ba247a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | fatoority-0.4.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
2b683619df78fd96701a2e0b98840da41eb7c56ac56764cb543e7cffc6f2533f
|
|
BLAKE2b-256 checksum How to use checksums |
c992387853c058fb4c9ac6ab613852a242dc3d5982a18fb02e74578641aad4ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | fatoority-0.4.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
d0f16f19c499a9faaa60141380ce5c5f26b821730513c73c456e930cf803f247
|
|
BLAKE2b-256 checksum How to use checksums |
12d11254c71679b9f4f6ff5ea8aa8b90081676722bd8baff043b290d95dd0a1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp310-cp310-win_amd64.whl
| Download URL | fatoority-0.4.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
ac3f1a93c2b7f0f798fda8b830e79fe9fcd8078aa8742dc767ece4c5c6e8da80
|
|
BLAKE2b-256 checksum How to use checksums |
914dc6f0d23b53263f152e65562ccf9dd2776d2700067b1a8f8786f8d3e52827
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | fatoority-0.4.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
5d3b3a5b361bd8703c636893dd5776928348b946ac5fd48faf15025b041e4ce9
|
|
BLAKE2b-256 checksum How to use checksums |
bf7fe494a08256372784c8fa90fc3ab309462a8a9ff57fd34582fab2803aace7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | fatoority-0.4.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4ba9806d4de9a880f74fcd4f36d7a2be3c8c46ea47fbac68723c11a0b47543a0
|
|
BLAKE2b-256 checksum How to use checksums |
ef0bca8a5a683e52fb94fd15b7080b3f9e4efad38b8787a1638f60472bafc3e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp39-cp39-win_amd64.whl
| Download URL | fatoority-0.4.0-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
0558e340afb5118722cc797036020e1f6041721898f7cb748f7c5a5e0688712b
|
|
BLAKE2b-256 checksum How to use checksums |
b9e141795128daa35d8114b2a1fbbc05dd099924d61337530b4a0018cd92e723
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | fatoority-0.4.0-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
846c0638447c3de59d7dc0e27c2f4e31a10ed23b1d3a08dd5e0da18ecb10ef42
|
|
BLAKE2b-256 checksum How to use checksums |
fe9ababd8701e8950d14432d6713f5349d8e2ee8f86ad9686d1eda4dc14614e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency logRelease files / fatoority-0.4.0-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | fatoority-0.4.0-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
441dec28faa43541c7aade2f906abad6552d3bd5229e75c04db13ab131915768
|
|
BLAKE2b-256 checksum How to use checksums |
1730db8a38f851037eaf6a72bb4d01ee6863a7c53e1c5fa07344a98e68d29e29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 11, 2026.
Transparency log
