churchtools-api
Ein Client für die REST-API von ChurchTools, für Python und Rust. Der Kern ist in Rust geschrieben; das Python-Paket nutzt ihn für HTTP, Login-Token, Rate-Limit, Wiederholungen und Paginierung und liefert Pydantic-Modelle. Beide Varianten entstehen aus derselben API-Beschreibung und decken die gesamte API ab: 849 Operationen und 1110 Modelle (ChurchTools 3.138.1).
A ChurchTools REST API client for Python and Rust, generated from the official OpenAPI description. The documentation is in German.
churchtools-api ist ein inoffizielles Projekt und gehört nicht zu ChurchTools. Das Python-Paket heißt auf PyPI
churchtools-api-rs und wird als churchtools_api importiert; es ist nicht verwandt mit den PyPI-Paketen
churchtools und ChurchToolsApi.
Dokumentation: churchtools-api.github.io/churchtools-api
mit Einstieg, Grundlagen, Beispielprojekten und der vollständigen Referenz. Jedes Beispiel gibt es für Python und
Rust. Alle Aufrufe stehen in
codegen/OPERATIONS.md,
die Rust-API zusätzlich auf docs.rs.
Beispiel
import datetime as dt
import churchtools_api as ct
client = ct.Client("https://meinegemeinde.church.tools", token="...") # oder ct.Client.from_env()
for event in client.events.list(from_=dt.date(2026, 11, 1), to=dt.date(2026, 11, 30), include="event_services"):
print(event.start_date, event.name, [s.name for s in event.event_services or []])
for person in client.persons.list(last_name="Müller"): # paginiert, Seiten werden bei Bedarf nachgeladen
print(person.first_name, person.model_extra) # model_extra: eigene DB-Felder der Instanz
client.groups.members.list(42) # Unterressourcen
client.persons.create(department_ids=[1], first_name="Ben") # Body als Keyword-Argumente
client.files.create("person", "7", files=[ct.Upload.from_path("brief.pdf")]) # Datei hochladen
use churchtools_api::{Client, queries::GetEventsQuery};
let client = Client::new("https://meinegemeinde.church.tools", Some("...".into()))?;
let query = GetEventsQuery { from: Some("2026-11-01".parse()?), to: Some("2026-11-30".parse()?), ..Default::default() };
for event in client.events().list_with(&query)? {
println!("{} {}", event.start_date, event.name);
}
Installation
pip install churchtools-api-rs # Python ab 3.10, Import: churchtools_api
cargo add churchtools-api # Rust ab 1.88
Für Linux, macOS und Windows gibt es fertige Python-Wheels. Wo keins passt, und für Rust immer, wird aus dem Quellcode gebaut; dafür braucht es eine Rust-Toolchain und einen C-Compiler (für die TLS-Bibliothek). Details stehen in der Doku unter „Installation“.
Was der Client übernimmt
| HTTP und Anmeldung | Login-Token als Authorization: Login <token>; login_with_password für Tests und interaktive Werkzeuge |
| Sicherheit | nur https:// (Ausnahme: localhost); Token erscheint nicht in Debug-Ausgaben oder Fehlermeldungen; Weiterleitungen, die ein POST in ein GET verwandeln würden, werden nicht verfolgt |
| Rate-Limit und Wiederholungen | min_interval als Mindestabstand zwischen Anfragen; 429 wird nach Retry-After wiederholt, 502/503/504 für idempotente Methoden |
| Zeitlimits | timeout (30 s), connect_timeout (10 s), max_response_size (256 MiB) |
| Paginierung | Listen werden seitenweise nachgeladen, sobald man sie durchläuft; ab der zweiten Seite wird die nächste im Hintergrund angefordert (prefetch(False) schaltet das ab) |
| Fehler | Python: NotFound, Unauthorized, Forbidden, UnprocessableEntity, … mit message, message_key, errors; Rust: Error mit is_not_found(), status(), api() |
| Typen | Python: Pydantic-Modelle, unbekannte Felder in model_extra; Rust: serde-Structs mit extra |
| Abweichungen der API von der Spec | werden ausgeglichen, z. B. Zahlen als String, PHP-Nulldatum, [] für ein leeres Objekt, Array-Parameter mit [] |
ChurchTools-Versionen und Kompatibilität
Der Code ist aus der API-Beschreibung von ChurchTools 3.138.1 erzeugt (API_VERSION). Gegen andere Versionen
funktioniert er, soweit die API gleich ist: Neue Felder landen in model_extra/extra, neue Enum-Werte in
Antworten sind erlaubt, fehlende Endpunkte antworten mit 404.
Die Paketversion folgt SemVer. Das Projekt startet mit 0.1.0; vor 1.0 kann jede
Minor-Version inkompatible Änderungen enthalten, insbesondere wenn der Code für eine neue ChurchTools-Version neu
erzeugt wird. Änderungen stehen in CHANGELOG.md.
Stand und Vorgehen
Das Projekt ist jung und experimentell. Was bisher geschehen ist und was geplant ist:
- Eigener Generator statt eines fertigen: Der Code entsteht mit einem projekteigenen Generator
(
codegen/) aus der OpenAPI-Beschreibung von ChurchTools, nicht mitopenapi-generatoro. Ä. Der Grund: Die Spec setzt Schemas ohne$refein (der Generator gewinnt die Namen wiePersonoderEventzurück), die API weicht an einigen Stellen vom Server ab (der Generator gleicht das aus), und Python und Rust sollen dieselbe Form haben. Aus derselben Zwischendarstellung entstehen auch Doku und Tests. Das ist bei gepflegten SDKs üblich, bedeutet aber auch, dass der Generator selbst gepflegt werden muss. - Getestet und durchgesehen, aber nicht in der Breite erprobt: Alle Lese-Endpunkte und 188
Schreib-Endpunkte sind gegen eine ChurchTools-Demo-Instanz getestet; die aufgezeichneten Antworten dienen als
Offline-Tests für Python und Rust (
docs/testbericht.md). Der Code wurde zu API-Form, Fehlerbehandlung und Umgang mit Zugangsdaten durchgesehen. Das ersetzt aber keine Erfahrung mit echten Instanzen und echten Daten: Vor einer produktiven Verwendung solltest du die Aufrufe, die du brauchst, selbst gegen eine Demo-Instanz oder eine Testkopie deiner Instanz prüfen, insbesondere alles, was schreibt. - Mit jeder neuen ChurchTools-Version soll die Kompatibilität erneut geprüft werden. Eine Möglichkeit, eine Version vor ihrer Veröffentlichung zu testen, gibt es derzeit nicht; die Prüfung geschieht also, sobald die Demo-Instanz die neue Version hat.
- Die Abhängigkeiten (reqwest, rustls, pydantic, …) werden gelegentlich aktualisiert.
- Bei der Entwicklung wurde Claude Code eingesetzt, unter anderem für den Generator, die Tests und die Dokumentation. Entwurf, Entscheidungen und Prüfung liegen beim Autor.
Bekannte Grenzen
- Pflichtfelder: Die Modelle übernehmen
requiredaus der Spec. Fehlt einem echten Objekt ein Pflichtfeld, schlägt der Aufruf mitDecodeErrorfehl. Alle aufgezeichneten Antworten dekodieren; für Daten, die die Demo nicht hat, bleibt ein Restrisiko. - Unions in Rust: Bodies und Felder mit mehreren möglichen Typen sind in Rust
serde_json::Value; in Python sind sie typisiert. - Pfadparameter in Rust sind
impl Display, die IDE zeigt also keinen ID-Typ. - Doppelte Parameter: Einige Endpunkte nehmen denselben Wert in Query und Body (
groups.duplicate:new_nameundnew_name_2) oder in Pfad und Body (posts.comments.create:post_idundpost_id_2). - Namen aus der Position: Schemas ohne Namen in der Spec heißen nach ihrer Stelle, z. B.
PostPersonsBody. - Größe:
models.pyund_resources.pyhaben je über 20 000 Zeilen;import churchtools_apidauert etwa 0,3 s. - Sprache: Die Doku ist deutsch, die Beschreibungen aus der Spec (Hover-Texte, Referenz) sind englisch.
- Nur synchron: Einen Async-Client gibt es noch nicht; er ließe sich ergänzen, ohne die synchrone API zu ändern.
- Geschwindigkeit in Python: Einzelne Anfragen sind durch den Rust-Transport 2–6× billiger als mit requests oder
httpx; bei großen Listen bestimmt das Dekodieren in Pydantic-Modelle die Zeit, und das Paket ist dort so schnell wie
eine gute reine Python-Lösung, nicht schneller. Rust kann daran nichts ändern, solange Python echte Pydantic-Modelle
bekommt (der größte Posten ist das Erzeugen der Python-Objekte, nicht die Validierung); das ist eine bewusste
Entscheidung. Gegen eine echte Instanz verschwindet beides ohnehin in der Netzwerkzeit, siehe
benchmarks/README.md.
Mitmachen
Fehlermeldungen und Vorschläge sind willkommen, siehe CONTRIBUTING.md. Wie man das Projekt
baut, testet und den Generator benutzt, steht in docs/entwicklung.md. Sicherheitslücken
bitte nicht öffentlich melden, sondern wie in SECURITY.md beschrieben.
Lizenz
Der Code steht unter der MIT-Lizenz. Die generierten Dateien beruhen auf der API-Beschreibung
„ChurchTools REST API“ von ChurchTools, die unter CC BY 4.0
steht; für sie gilt zusätzlich diese Lizenz. Welche Dateien das sind und was geändert wurde, steht in
NOTICE. Lizenzangabe der Pakete: MIT AND CC-BY-4.0.
churchtools-api ist kein offizielles Produkt der ChurchTools Innovations GmbH.
Metadata
Release files for churchtools-api-rs 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| churchtools_api_rs-0.1.0.tar.gz | 912.3 kB | With provenance | Details for churchtools_api_rs-0.1.0.tar.gz |
Built distributions (wheels)
Total release size: 19.5 MB
Release files / churchtools_api_rs-0.1.0.tar.gz
| Download URL | churchtools_api_rs-0.1.0.tar.gz |
|---|---|
| Size | 912.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
54cbe4887e3f0d0282383ff9af815a898df4fa82b29659ea5c5d485d6072a135
|
|
BLAKE2b-256 checksum How to use checksums |
47c8082a3a7ab6320f498797c0c0e45e5ea96d90fa9de094d981553e92ddd14f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-win_amd64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
77d7dcabf38c03c7fc95b1cf8a6d1a3e52ed6049a687668db8f7741db1369f9e
|
|
BLAKE2b-256 checksum How to use checksums |
9279e93e778c9adea6cf99e424f4a5a7550eacbc1236b700c4f4fb181116da43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b8a46470f2b2dc2fd665ddffee1ac01ed93383db1c9ad23d5c83b2bdf220c327
|
|
BLAKE2b-256 checksum How to use checksums |
d73db181c294a37496015c3aef6274eab46a831249f1a6116e97c751be481578
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
3596afa813544a25b01d1659385fd952e1a31b84836ef4ae26d60e27b3511817
|
|
BLAKE2b-256 checksum How to use checksums |
c13ff0558abf163b1a9d2fc0cbfa604dd58296723b4868bfe70d16000a4feeca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 2.7 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
73ddb745e75165c63e8051013512df493b622109cef99c503d332b19e48e210c
|
|
BLAKE2b-256 checksum How to use checksums |
231809a89ca50ec50c01c878ffaea554da7085917d211d3fbe7e23aa4921ce52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
06c5de29eb70772372bfa8d3afbefe2a1ba48ce4eca96a98f592234c517a1778
|
|
BLAKE2b-256 checksum How to use checksums |
7e0dd7289673a687729d25b6d8435750395ba7cf78c062ece003c424f8aa3642
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
6c52410f3d118448fd05715daa0a5bab77a7b670059d2bfc89c1851ca567b657
|
|
BLAKE2b-256 checksum How to use checksums |
1419e684d89f3ad01fb7625749fa0b973d4434f0d8201943831954d92982ab43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logRelease files / churchtools_api_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | churchtools_api_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
f98e7edeaf52865e44b99d34b7ce028bc8238933937a4e9dcff4983496dd647f
|
|
BLAKE2b-256 checksum How to use checksums |
d05986128b41fd879fc65f49f30f29edf09bd89e70a910c4687c6d39617ccccb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 30, 2026.
Transparency logSecurity for churchtools-api-rs 0.1.0
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.
Full provenance
All 8 files in this release have been uploaded with provenance metadata.
Attestation for churchtools_api_rs-0.1.0.tar.gz
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 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.