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

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!")

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.