Installation

Requirements

The Cardinity Python SDK requires:

Python 3.8 or higher
Internet connection for API requests
Cardinity account with API credentials

Supported Python Versions

The SDK is tested and officially supports:

Python 3.8
Python 3.9
Python 3.10
Python 3.11
Python 3.12

Installation Methods

pip (Recommended)

Install the latest stable version from PyPI:

pip install cardinity-python

To install a specific version:

pip install cardinity-python==1.0.0

uv (Fast Alternative)

If you’re using the uv package manager:

uv add cardinity-python

Development Installation

To install from source for development:

git clone https://github.com/trendpro/cardinity-python.git
cd cardinity-python
uv install --dev

Or with pip:

git clone https://github.com/trendpro/cardinity-python.git
cd cardinity-python
pip install -e ".[dev]"

Dependencies

The SDK has minimal required dependencies:

Core Dependencies

requests (>=2.25.0): HTTP library for API communication
requests-oauthlib (>=1.3.0): OAuth 1.0 authentication
cerberus (>=1.3.0): Data validation
python-dateutil (>=2.8.0): Date/time parsing

Development Dependencies

pytest (>=6.0): Testing framework
pytest-cov: Test coverage reporting
ruff: Code formatting and linting
mypy: Static type checking
sphinx: Documentation generation
sphinx-rtd-theme: Documentation theme

Verification

After installation, verify that the SDK is working correctly:

import cardinity

# Check version
print(f"Cardinity SDK version: {cardinity.__version__}")

# Test import
from cardinity import Cardinity
print("Installation successful!")

Virtual Environment (Recommended)

It’s highly recommended to use a virtual environment:

Using venv

python -m venv cardinity-env
source cardinity-env/bin/activate  # On Windows: cardinity-env\Scripts\activate
pip install cardinity-python

Using conda

conda create -n cardinity python=3.11
conda activate cardinity
pip install cardinity-python

Using uv

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv add cardinity-python

Troubleshooting

Common Issues

ImportError: No module named ‘cardinity’

Make sure you’ve activated your virtual environment and installed the package correctly.

SSL Certificate Errors

Ensure your system has up-to-date SSL certificates. On macOS, you might need to run:

/Applications/Python\ 3.x/Install\ Certificates.command

Permission Errors

Use --user flag with pip if you encounter permission issues:

pip install --user cardinity-python

Platform-Specific Notes

Windows

Use PowerShell or Command Prompt
Consider using Windows Subsystem for Linux (WSL) for better compatibility

macOS

Xcode Command Line Tools may be required for some dependencies
Install with: xcode-select --install

Linux

Most distributions work out of the box
Ensure python3-dev is installed for compiling dependencies

Next Steps

Once installed, proceed to the Quick Start Guide guide to learn how to configure your API credentials and make your first API call.