fatoora Python bindings
This package wraps the fatoora-ffi shared library via cffi.
Development (uv)
uv venv
uv pip install -e .
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.
- 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. - For local dev without install, set
FATOORA_FFI_PATHor build and use the repotarget/output. - If a
fatoora_ffi.hheader is present (fromFATOORA_CBINDGEN=1 cargo build -p fatoora-ffi), the Python wrapper will load its declarations automatically. You can override the header withFATOORA_FFI_HEADER=/path/to/fatoora_ffi.h.
Examples
python examples/load_lib.py
python examples/invoice_basic.py
python examples/invoice_parse.py
Tests
uv pip install -e .[dev]
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).
1 maintainer
Metadata
1 maintainer
Release files for fatoora-rs 0.2.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: 65.9 MB
Release files / fatoora_rs-0.2.0-cp313-cp313-win_amd64.whl
| Download URL | fatoora_rs-0.2.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bac51a473fac0dc1264f123d1c2351d601a24174c6aca0ff3ef64ff2836965cb
|
|
BLAKE2b-256 checksum How to use checksums |
ecb4322feac2895c2647741eb4a448e66ebfcf9147b5c734787921b66c299e35
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | fatoora_rs-0.2.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
869e299e90c9ba4cee36e6098cf92af4edf1839fc5fdadbe6ea22c2d4f5862f2
|
|
BLAKE2b-256 checksum How to use checksums |
6760e42297554d9a71a121b59b18a7ffcccaa878b054f422e4cd235e3c2a8f52
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | fatoora_rs-0.2.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
56b729d22a22fa05258acc16900c04c7d37b8aa911caf1a6760dbd90dbc0ae5d
|
|
BLAKE2b-256 checksum How to use checksums |
90d3f2994fa5d472ee1ad9a2b87ae1f18c191987786a6df570074cfb20aaa33b
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp312-cp312-win_amd64.whl
| Download URL | fatoora_rs-0.2.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c088bfac683b0d5566185d54b2b35efb68e63e18bda9a3c59d9e4e0e3ec4697d
|
|
BLAKE2b-256 checksum How to use checksums |
f9867162e5a30ca4fa180e784e29fa0a1b74c449f3cfe36d9e04ccdcfcfbac84
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | fatoora_rs-0.2.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
bbe2a390f63168ced611ea6ab10f3fc111b663218722cf01cb5693dbb45e13d7
|
|
BLAKE2b-256 checksum How to use checksums |
22d7ca3644a49aeca2a713d7d2cd9b2911a9c18f7b430cd7b774670137922bd6
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | fatoora_rs-0.2.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1b40fda14ebcf22fa990099018b9dc41d11d4279cbe8e0bc3b175c408888f59d
|
|
BLAKE2b-256 checksum How to use checksums |
74dd498168680b3a144f2f8eae0c2658da9f5ccabcc04917558da1b84449198a
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp311-cp311-win_amd64.whl
| Download URL | fatoora_rs-0.2.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
de23c27d5c9c2909daec6c495aa8a3dc808a31914b3b6470332892ebc4b799e6
|
|
BLAKE2b-256 checksum How to use checksums |
baea0e522b12190b6a00611e77747ca8c7bc09d7a2cd80a23514e0df6d742166
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | fatoora_rs-0.2.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6ab720c314c33a9765089c020874d801fc171d937871a8ba9eefeecbe7fd118f
|
|
BLAKE2b-256 checksum How to use checksums |
0fee541b7ff444ab8164eb13ca223e90d3432d8771e9f6c44bed62ad300b4dec
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | fatoora_rs-0.2.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
416adedf6c8f72ef45e04e165eae23c26ec20ed6d55ed0d8fd5785de7b7165dc
|
|
BLAKE2b-256 checksum How to use checksums |
ba45915ceb4e7e9f6df5b17c9c8acb1a7ba6ccf7583787416ff66ab60d196aa4
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp310-cp310-win_amd64.whl
| Download URL | fatoora_rs-0.2.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
094a53fa0f5a69081b1b9c24f689ba119253f812c9fce94910991e8fa82d18a2
|
|
BLAKE2b-256 checksum How to use checksums |
feb8b98e4c64d86c1bab65740edea4f5af85c971133b9a740efda90af37d30e1
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | fatoora_rs-0.2.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
e7e3de983cbde0d478987d4625bce0067bdeb28d97619320cb4813a82a9f0adc
|
|
BLAKE2b-256 checksum How to use checksums |
c02879953bfaac968af531ec97b39ac98a838d69b598357ce3685d39befc1e2d
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | fatoora_rs-0.2.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
87da1e55443563c212a6ccfd59842cb9dce9b89a3b5ae2fbb007896d6f127483
|
|
BLAKE2b-256 checksum How to use checksums |
673f46e0100dc1d6dba1401d8438f009262b44a822cee4d0f9cae93eb2570b7b
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp39-cp39-win_amd64.whl
| Download URL | fatoora_rs-0.2.0-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 4.9 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8352766d7fc88d6e7a58a4bb3f21799ced9546b8397b9f2342cdf05d2b3e0e4d
|
|
BLAKE2b-256 checksum How to use checksums |
166fdd1d4542c83d38e705277a12e8b99334b516f015724e898ab27247d02f09
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | fatoora_rs-0.2.0-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.8 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
452b720d9321bbe7235041ef86830a801129a4d31a4a78368fd11c4297a3e122
|
|
BLAKE2b-256 checksum How to use checksums |
ee346079c98b6a24c6db8ea8c3fd49c52563745da7f0b9cab81736f227659ff3
|
| 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 Sep 18, 2026.
Transparency logRelease files / fatoora_rs-0.2.0-cp39-cp39-macosx_11_0_arm64.whl
| Download URL | fatoora_rs-0.2.0-cp39-cp39-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.6 MB |
| Tags | CPython 3.9 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b8cdbb010fe7d3e5c08b18650743b77a7b68d8137418739583fe20b6c50f99c2
|
|
BLAKE2b-256 checksum How to use checksums |
cfcff7deb5ffcaa13be82bb25e47cb14a48752cc6d202ff3ad6aeb0da870a86e
|
| 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 Sep 18, 2026.
Transparency log
