CiviCRM v3/v4 REST API Python wrapper
Project description
Getting Started
This is a brand-new project and code is subject to change at any time.
Install with python3 -m pip install civipy. If you are using a Python version
older than 3.11 and want to use pyproject.toml configuration, install with
python3 -m pip install civipy[pyproject].
Configuration
Configure your credentials in environment variables, a .civipy file, or in
pyproject.toml in a tools.civipy section. By default, CiviPy will read a .civipy
file anywhere in the current working directory up to your project root, or your
project's pyproject.toml file, or a .civipy file in the user's home folder.
Settings in environment variables will overwrite any file settings. Alternatively,
you can call civipy.config.SETTINGS.init() to set the configuration values.
| Setting | Environment Variable | .civipy File |
pyproject.toml File |
|---|---|---|---|
[tool.civipy] |
|||
| Connection (required) | CIVI_REST_BASE |
rest_base=http://civi.py |
rest-base = "http://civi.py" |
| API Version | CIVI_API_VERSION |
api_version=4 |
api-version = "4" |
| Access Token (required) | CIVI_USER_KEY |
user_key=... |
user-key = "..." |
| Site Token (required for v3) | CIVI_SITE_KEY |
site_key=... |
site-key = "..." |
| Log File | CIVI_LOG_FILE |
log_file=/tmp/civipy.log |
log-file = "/tmp/civipy.log" |
| Log Level | CIVI_LOG_LEVEL |
log_level=WARNING |
log-level = "WARNING" |
| Config File | CIVI_CONFIG |
Connection
The Connection setting lets you specify the URL of your REST API, or the cv or
drush or wp-cli executable on your file system. If "http" is found in the setting,
the system will use http calls to the REST API. If the string "drush" is found, it
will use drush. If the string "wp" is found, it will use wp-cli. And if none of these
are found, it will attempt to call the cv command line API.
API Version
Set to "3" to use the CiviCRM v3 API, or "4" (the default) to use the CiviCRM v4 API.
Log File
To log to a file instead of the screen, set the Log File setting to the file path you want to log to.
Config File
You can specify in an environment variable either a directory to find a .civipy
configuration file in, or a file to read as a .civipy configuration file.
Usage
There is a Django-style .objects attribute on each record model with filter, values,
order_by, and all methods for querying; and create, delete, and update methods
for making changes. Model instances also have save and delete methods.
from civipy import CiviContact
contact = CiviContact.objects.filter(email_primary__email="ana@ananelson.com")[0]
contact.nick_name = "Ana"
contact.save()
Each CiviCRM Entity is represented by a subclass of CiviCRMBase; if you need an entity that is not in the project, you can easily add it by subclassing CiviCRMBase and naming it the entity name prepended with "Civi", e.g.
import civipy
class CiviNewEntity(civipy.CiviCRMBase):
pass
Copyright & License
civipy Copyright © 2020 Ana Nelson
Licensed under the GPL v3
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
