Client

The main entry points for interacting with CiviCRM.

CiviClient

class civicrm_py.CiviClient

Bases: object

Async client for CiviCRM API v4.

Usage:

async with CiviClient(settings) as client:

response = await client.request(“Contact”, “get”, {“limit”: 10})

Or with environment variables:

async with CiviClient.from_env() as client:

response = await client.request(“Contact”, “get”)

__init__(settings=None, *, base_url=None, api_key=None, site_key=None, timeout=30, verify_ssl=True, debug=False, max_retries=3)

Initialize CiviClient.

Either provide a CiviSettings instance or individual parameters. If neither settings nor base_url is provided, will attempt to load from environment variables.

Parameters:

• settings (CiviSettings | None) – Pre-configured CiviSettings instance.

• base_url (str | None) – CiviCRM API base URL.

• api_key (str | None) – API key for authentication.

• site_key (str | None) – Optional site key.

• timeout (int) – Request timeout in seconds.

• verify_ssl (bool) – Whether to verify SSL certificates.

• debug (bool) – Enable debug logging.

• max_retries (int) – Maximum retry attempts.

classmethod from_env()

Create client from environment variables.

Returns:

CiviClient configured from environment.

Return type:

CiviClient

property settings: CiviSettings

Get client settings.

async request(entity, action, params=None)

Make API request.

Parameters:

• entity (str) – CiviCRM entity name (e.g., ‘Contact’, ‘Activity’).

• action (str) – API action (e.g., ‘get’, ‘create’, ‘delete’).

• params (APIRequest | dict[str, Any] | None) – Request parameters.

Returns:

API response with values and metadata.

Raises:

• CiviConnectionError – On network error.

• CiviTimeoutError – On request timeout.

• CiviAuthError – On authentication failure.

• CiviAPIError – On API error response.

Return type:

APIResponse[dict[str, Any]]

async get(entity, *, select=None, where=None, order_by=None, limit=None, offset=None)

Get entities with optional filtering.

Parameters:

• entity (str) – Entity name.

• select (list[str] | None) – Fields to return.

• where (list[list[Any]] | None) – Filter conditions.

• order_by (dict[str, str] | None) – Sort order.

• limit (int | None) – Max records.

• offset (int | None) – Skip records.

Returns:

API response.

Return type:

APIResponse[dict[str, Any]]

async create(entity, values)

Create a new entity.

Parameters:

• entity (str) – Entity name.

• values (dict[str, Any]) – Field values for the new entity.

Returns:

API response with created entity.

Return type:

APIResponse[dict[str, Any]]

async update(entity, values, where)

Update existing entities.

Parameters:

• entity (str) – Entity name.

• values (dict[str, Any]) – Field values to update.

• where (list[list[Any]]) – Filter to select entities to update.

Returns:

API response with updated entities.

Return type:

APIResponse[dict[str, Any]]

async delete(entity, where)

Delete entities.

Parameters:

• entity (str) – Entity name.

• where (list[list[Any]]) – Filter to select entities to delete.

Returns:

API response.

Return type:

APIResponse[dict[str, Any]]

async get_fields(entity)

Get field metadata for an entity.

Parameters:

entity (str) – Entity name.

Returns:

API response with field definitions.

Return type:

APIResponse[dict[str, Any]]

async close()

Close the client and release resources.

async __aenter__()

Enter async context.

async __aexit__(exc_type, exc_val, exc_tb)

Exit async context.

SyncCiviClient

class civicrm_py.SyncCiviClient

Bases: object

Sync client for CiviCRM API v4.

Usage:

with SyncCiviClient(settings) as client:

response = client.request(“Contact”, “get”, {“limit”: 10})

__init__(settings=None, *, base_url=None, api_key=None, site_key=None, timeout=30, verify_ssl=True, debug=False, max_retries=3)

Initialize SyncCiviClient.

Parameters:

• settings (CiviSettings | None) – Pre-configured CiviSettings instance.

• base_url (str | None) – CiviCRM API base URL.

• api_key (str | None) – API key for authentication.

• site_key (str | None) – Optional site key.

• timeout (int) – Request timeout in seconds.

• verify_ssl (bool) – Whether to verify SSL certificates.

• debug (bool) – Enable debug logging.

• max_retries (int) – Maximum retry attempts.

classmethod from_env()

Create client from environment variables.

property settings: CiviSettings

Get client settings.

request(entity, action, params=None)

Make API request.

get(entity, *, select=None, where=None, order_by=None, limit=None, offset=None)

Get entities with optional filtering.

create(entity, values)

Create a new entity.

update(entity, values, where)

Update existing entities.

delete(entity, where)

Delete entities.

get_fields(entity)

Get field metadata for an entity.

close()

Close the client and release resources.

__enter__()

Enter sync context.

__exit__(exc_type, exc_val, exc_tb)

Exit sync context.