civicrm-py

Modern Python client for CiviCRM API v4 with async support and web framework integrations.

civicrm-py gives you a clean, typed Python interface to CiviCRM. It works async or sync, plays well with Django, Litestar, Flask, and FastAPI, and uses msgspec for fast serialization.

Getting Started

Install civicrm-py and make your first API call in five minutes.

Getting Started
Core Concepts

Learn about the client, queries, entities, and error handling.

Core Concepts
Framework Guides

Integrate with Django, Litestar, Flask, FastAPI, and other frameworks.

Framework Guides
API Reference

Complete documentation for all public classes and functions.

API Reference
Cookbook

Real examples for common CiviCRM tasks like contact sync, bulk updates, and reporting.

Cookbook

Key Features

  • Async and Sync: Use CiviClient for async code or SyncCiviClient for traditional apps

  • Type Safe: Full type hints with msgspec models for IDE support and validation

  • Framework Integrations: First class support for Django, Litestar, Flask, FastAPI

  • Retries and Timeouts: Built in retry logic and configurable timeouts

  • Clean API: Simple methods for get, create, update, delete operations

Quick Example

from civicrm_py import CiviClient

async with CiviClient(base_url="...", api_key="...") as client:
    response = await client.get("Contact", limit=10)
    for contact in response.values:
        print(contact["display_name"])

from civicrm_py import SyncCiviClient

with SyncCiviClient(base_url="...", api_key="...") as client:
    response = client.get("Contact", limit=10)
    for contact in response.values:
        print(contact["display_name"])

Installation

pip install civicrm-py

# With framework extras
pip install civicrm-py[django]    # Django integration
pip install civicrm-py[litestar]  # Litestar integration
pip install civicrm-py[flask]     # Flask integration
pip install civicrm-py[fastapi]   # FastAPI integration

# With ecosystem extras
pip install civicrm-py[sqlspec]   # Local database caching
pip install civicrm-py[workflows] # Workflow automation

# Combined extras
pip install 'civicrm-py[litestar,sqlspec,workflows]'

See docs for sqlspec, workflows, and pytest-databases.

Alternatives

  • civipy - Another Python client for CiviCRM. No built-in web framework integrations.

Indices and tables