Skip to main content

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 mit openapi-generator o. Ä. Der Grund: Die Spec setzt Schemas ohne $ref ein (der Generator gewinnt die Namen wie Person oder Event zurü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 required aus der Spec. Fehlt einem echten Objekt ein Pflichtfeld, schlägt der Aufruf mit DecodeError fehl. 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_name und new_name_2) oder in Pfad und Body (posts.comments.create: post_id und post_id_2).
  • Namen aus der Position: Schemas ohne Namen in der Spec heißen nach ihrer Stelle, z. B. PostPersonsBody.
  • Größe: models.py und _resources.py haben je über 20 000 Zeilen; import churchtools_api dauert 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)

Source distribution for churchtools-api-rs 0.1.0
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)

Table of built distributions (wheels) for churchtools-api-rs 0.1.0
File Actions
churchtools_api_rs-0.1.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for churchtools_api_rs-0.1.0-cp310-abi3-win_amd64.whl
churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl CPython 3.10 abi3 Linux musl 1.2+ x86-64 Details for churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl CPython 3.10 abi3 Linux musl 1.2+ ARM64 Details for churchtools_api_rs-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
churchtools_api_rs-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for churchtools_api_rs-0.1.0-cp310-abi3-manylinux_2_28_aarch64.whl
churchtools_api_rs-0.1.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for churchtools_api_rs-0.1.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
churchtools_api_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for churchtools_api_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
churchtools_api_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for churchtools_api_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl

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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

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

Select from 8 files

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 log

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

Release history Release notifications | RSS feed

This release

0.1.0 This release

8 release files Full provenance

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