Skip to main content

fatoora Python bindings

This package wraps Diplomat-generated native bindings with the public fatoora Python API. See Diplomat bindings.

Development (uv)

uv venv
uv pip install .

Build a wheel (uv)

uv build --wheel

Wheels (CI)

  • GitHub Actions uses cibuildwheel to produce platform wheels in dist/ (wheel-only publishing).
  • See .github/workflows/python.yml for the build matrix.

Notes

  • The build step compiles fatoora-ffi with cargo 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 generic FfiError.
  • 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.

Metadata

Release files for fatoora-rs 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for fatoora-rs 0.3.0
File
fatoora_rs-0.3.0-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details
fatoora_rs-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details
fatoora_rs-0.3.0-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details
fatoora_rs-0.3.0-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details
fatoora_rs-0.3.0-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details
fatoora_rs-0.3.0-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details
fatoora_rs-0.3.0-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details
fatoora_rs-0.3.0-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details
fatoora_rs-0.3.0-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details
fatoora_rs-0.3.0-cp310-cp310-win_amd64.whl CPython 3.10 CPython 3.10 Windows x86-64 Details
fatoora_rs-0.3.0-cp310-cp310-manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details
fatoora_rs-0.3.0-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details
fatoora_rs-0.3.0-cp39-cp39-win_amd64.whl CPython 3.9 CPython 3.9 Windows x86-64 Details
fatoora_rs-0.3.0-cp39-cp39-manylinux_2_28_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.28+ x86-64 Details
fatoora_rs-0.3.0-cp39-cp39-macosx_11_0_arm64.whl CPython 3.9 CPython 3.9 macOS 11.0+ ARM64 Details

Total release size: 81.9 MB

Release files / fatoora_rs-0.3.0-cp313-cp313-win_amd64.whl

Download URL fatoora_rs-0.3.0-cp313-cp313-win_amd64.whl
Size 5.3 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
fa20777cbb3ca79b81807922f86e154876b774d500f631043f751f0c06c30233
BLAKE2b-256 checksum
How to use checksums
5ddb7fbce400073cee3f50b964cc684f6c51ace37b4679f8f435d7065498dc08
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

Release files / fatoora_rs-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL fatoora_rs-0.3.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
f6e96865e418046a03fa62f2f3af01af9fbbec61e70c52d0fbb058f5caf2f37e
BLAKE2b-256 checksum
How to use checksums
271b248d8c67badad023e0b601bc8716cbdd18de74676a574f9e6242069728e6
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

Release files / fatoora_rs-0.3.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL fatoora_rs-0.3.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
aeea3310ab45f764da7cf24ad29c901c94cb12c2d70c314f39d2fe319617ca4d
BLAKE2b-256 checksum
How to use checksums
fa3d8382c92e3a6a29d0e7ffe4efe290c1c47d15ff512ea518e33e53e2c13e74
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

Release files / fatoora_rs-0.3.0-cp312-cp312-win_amd64.whl

Download URL fatoora_rs-0.3.0-cp312-cp312-win_amd64.whl
Size 5.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
e721cd7484dfc0831312a0038128d0e253d8cc02b1a1f479abc03ba17612dac3
BLAKE2b-256 checksum
How to use checksums
2d20320da6b94b09ad76d6e25ae31211d148e3188ae89244f67a2d1bee04fcc4
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

Release files / fatoora_rs-0.3.0-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL fatoora_rs-0.3.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
e4e1cf3362d9a96e16681867a85881947ed1d5a0c95f34d5c2069806f39eb751
BLAKE2b-256 checksum
How to use checksums
19c29a2cc591cd165ccd02b6a82d2d38413283a9927a4e278c5838d1cabb2f36
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

Release files / fatoora_rs-0.3.0-cp312-cp312-macosx_11_0_arm64.whl

Download URL fatoora_rs-0.3.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
bd37c25f49b8a3eea1fc18dc5f1fc1968f1718e8aeec16837332729a2562a565
BLAKE2b-256 checksum
How to use checksums
01f090e325b6d0a8d5dd53f56fd67ab58852e89f78fb2d570beb88dba9dc01a7
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

Release files / fatoora_rs-0.3.0-cp311-cp311-win_amd64.whl

Download URL fatoora_rs-0.3.0-cp311-cp311-win_amd64.whl
Size 5.3 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
0b5d92e71e163fd3ab7b61afd5d638226b69cc60ffac748fc4584f49bd3f0d92
BLAKE2b-256 checksum
How to use checksums
74599785a135fd646aca452162918dccff14700aca52b6ce42a7d25b08bfd33b
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

Release files / fatoora_rs-0.3.0-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL fatoora_rs-0.3.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
c6498b664633282af9bc796beadb8a823a0c8a4ed1966979eb54f22741b6ef58
BLAKE2b-256 checksum
How to use checksums
a96e5dbc2bc62d535cec4500d585393f71d31a2eb698726804e9463ab20a2d2e
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

Release files / fatoora_rs-0.3.0-cp311-cp311-macosx_11_0_arm64.whl

Download URL fatoora_rs-0.3.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
4dea520868bb6b256d6f90f8adcec8abfb6613a06c37aa83afab5f3f628e3c09
BLAKE2b-256 checksum
How to use checksums
b9b188cf4b47f54fc1902e64cfbdf40c0a440c7b7e58ac13b7a89660e1bff7fd
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

Release files / fatoora_rs-0.3.0-cp310-cp310-win_amd64.whl

Download URL fatoora_rs-0.3.0-cp310-cp310-win_amd64.whl
Size 5.3 MB
Tags CPython 3.10 Windows x86-64
SHA-256 checksum
How to use checksums
15b2df5d2c956d8b0661164cdebdc8e7f1d7bd377d53d94fa568a58ffadd2362
BLAKE2b-256 checksum
How to use checksums
cf61cd4224adca169279cf95e52828c633dc534f945d30176832ad3bcbc11d60
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

Release files / fatoora_rs-0.3.0-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL fatoora_rs-0.3.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
4381d6292bd619d28958994e26678f54e8c98aae8f45416d0d66320627c04591
BLAKE2b-256 checksum
How to use checksums
b93de319ed509b85983ac53d1818c00f3046e131eb566a8ddc7094ef803b1185
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

Release files / fatoora_rs-0.3.0-cp310-cp310-macosx_11_0_arm64.whl

Download URL fatoora_rs-0.3.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
8fb04fea5a5f3a01fad7c5afb4b539988d29c16f6150a4f986895b4859c06128
BLAKE2b-256 checksum
How to use checksums
f8b5282bebb86770a475e82fdbf8866b7505b88f66b9c80c765104f26659540f
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

Release files / fatoora_rs-0.3.0-cp39-cp39-win_amd64.whl

Download URL fatoora_rs-0.3.0-cp39-cp39-win_amd64.whl
Size 5.3 MB
Tags CPython 3.9 Windows x86-64
SHA-256 checksum
How to use checksums
53215447bab8d871ec5d526c2e7b88bb323220a0266997f0a61608d9ca57e57e
BLAKE2b-256 checksum
How to use checksums
8ba625ca95d314a65ca43a64f3e92434f3acff2539811853a031a973d2117170
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

Release files / fatoora_rs-0.3.0-cp39-cp39-manylinux_2_28_x86_64.whl

Download URL fatoora_rs-0.3.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
99bd0fb7a7b5dac9ee7989d50485e7d8496c5f8bcdaeb545be8591b77578c136
BLAKE2b-256 checksum
How to use checksums
4b7057406a48ec9b8dd48c7e883e87e96c3eab5a472596069ab4622c141c1fce
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

Release files / fatoora_rs-0.3.0-cp39-cp39-macosx_11_0_arm64.whl

Download URL fatoora_rs-0.3.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
596402d7e80c6005a6529569d02eda1cc5e95d185638a0fe4fe3b2b94e347308
BLAKE2b-256 checksum
How to use checksums
bf3216bd400764d8c04ae84b4867abc425317fc8a8780bbcd4af80713fcb2fdc
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

Release history Release notifications | RSS feed

This release

0.3.0 This release

15 release files

0.2.0

15 release files

0.1.3

20 release files

0.1.0

1 release file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page