DeepCart Python SDK

A framework-agnostic Python client library for the DeepCart API. This SDK provides typed interfaces, comprehensive error handling, and a simple, intuitive API for interacting with DeepCart services.

Features

• 🚀 Simple and intuitive API
• 🔒 Type-safe with full type hints
• ⚡ Framework-agnostic (works with any Python framework)
• 🛡️ Comprehensive error handling
• 📝 Fully documented
• ✅ Well-tested
• 🔄 Context manager support

Installation

Install the SDK using pip:

pip install deepcart-client

Or install from source:

git clone https://github.com/DeepCart/python-sdk-python.git
cd python-sdk-python
pip install -e .

Quick Start

from deepcart import DeepCartClient

# Initialize the client
client = DeepCartClient(api_key="your-api-key-here")

# Test connectivity with a ping
response = client.ping()
print(response)  # {'status': 'ok', 'timestamp': '2024-01-01T00:00:00Z'}

# Close the client when done
client.close()

Using as a Context Manager

The recommended way to use the client is with a context manager, which automatically handles cleanup:

from deepcart import DeepCartClient

with DeepCartClient(api_key="your-api-key-here") as client:
    response = client.ping()
    print(f"Status: {response['status']}")

Configuration

The client can be configured with the following parameters:

client = DeepCartClient(
    api_key="your-api-key-here",        # Required: Your DeepCart API key
    base_url="https://api.deepcart.com/v1",  # Optional: Custom API endpoint
    timeout=30                          # Optional: Request timeout in seconds
)

API Reference

ping()

Test connectivity and authentication with the DeepCart API.

response = client.ping()
# Returns: {'status': 'ok', 'timestamp': '2024-01-01T00:00:00Z', 'message': 'pong'}

Returns: dict - A dictionary containing:

• status (str): The status of the API ("ok" if successful)
• timestamp (str): ISO 8601 formatted timestamp
• message (str): Response message ("pong")

Raises:

• DeepCartAuthError: If authentication fails
• DeepCartConnectionError: If network connection fails
• DeepCartTimeoutError: If the request times out
• DeepCartAPIError: For other API errors

Error Handling

The SDK provides specific exception types for different error scenarios:

from deepcart import (
    DeepCartClient,
    DeepCartError,
    DeepCartAPIError,
    DeepCartAuthError,
    DeepCartConnectionError,
    DeepCartTimeoutError,
)

try:
    client = DeepCartClient(api_key="your-api-key")
    response = client.ping()
except DeepCartAuthError as e:
    print(f"Authentication failed: {e}")
except DeepCartConnectionError as e:
    print(f"Connection error: {e}")
except DeepCartTimeoutError as e:
    print(f"Request timed out: {e}")
except DeepCartAPIError as e:
    print(f"API error: {e.message} (status: {e.status_code})")
except DeepCartError as e:
    print(f"General error: {e}")

Exception Hierarchy

• DeepCartError - Base exception for all SDK errors
  • DeepCartAPIError - API returned an error response
  • DeepCartAuthError - Authentication failed (invalid API key)
  • DeepCartConnectionError - Network connection issues
  • DeepCartTimeoutError - Request timed out

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/DeepCart/python-sdk-python.git
cd python-sdk-python

# Install development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=deepcart --cov-report=html

# Run specific test file
pytest tests/test_client.py

Code Quality

# Format code with black
black deepcart tests

# Lint with ruff
ruff check deepcart tests

# Type check with mypy
mypy deepcart

Requirements

• Python 3.8 or higher
• requests >= 2.25.0
• typing-extensions >= 4.0.0 (for Python < 3.10)

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/DeepCart/python-sdk-python/issues
• Documentation: https://github.com/DeepCart/python-sdk-python#readme

Changelog

0.1.0 (Initial Release)

• Initial release of DeepCart Python SDK
• Basic client implementation with ping endpoint
• Comprehensive error handling
• Full type hints support
• Test suite with pytest