Clockify SDK
A Python SDK for interacting with the Clockify API. This SDK provides a simple and intuitive interface to manage your Clockify workspace, including time entries, projects, tasks, and reports.
Features
- 🔑 Simple authentication with API key
- 📊 Manage time entries
- 📁 Handle projects and tasks
- 👥 Manage clients and users
- 🔄 Workspace management
- ✨ Type hints for better IDE support
Installation
pip install clockify-sdk
Quick Start
First, create a .env
file in your project root:
CLOCKIFY_API_KEY=your-api-key
CLOCKIFY_WORKSPACE_ID=your-workspace-id # Optional, defaults to first workspace
Then use the SDK:
from dotenv import load_dotenv
import os
from clockify_sdk import Clockify
from datetime import datetime
load_dotenv()
client = Clockify(
api_key=os.getenv("CLOCKIFY_API_KEY"),
workspace_id=os.getenv("CLOCKIFY_WORKSPACE_ID")
)
workspaces = client.get_workspaces()
start_time = datetime.now(timezone.utc)
end_time = datetime.fromisoformat("2024-03-17T11:00:00+00:00")
time_entry = client.time_entries.add_time_entry(
start=start_time,
end=end_time,
description="Working on feature X",
project_id="project-id"
)
projects = client.projects.get_all()
project = client.projects.create({
"name": "New Project",
"clientId": "client-id",
"isPublic": True
})
time_entries = client.time_entries.get_all(
user_id=client.user_id,
start_date="2024-03-01",
end_date="2024-03-17"
)
report = client.reports.generate(
start_date="2024-03-01",
end_date="2024-03-17",
project_ids=["project-id-1", "project-id-2"]
)
Advanced Usage
Working with Tasks
task = client.tasks.create({
"name": "Implement new feature",
"assigneeId": "user-id"
}, project_id="project-id")
tasks = client.tasks.get_all(project_id="project-id")
Managing Clients
new_client = client.clients.create({
"name": "New Client",
"note": "Important client"
})
clients = client.clients.get_all()
User Management
current_user = client.users.get_current_user()
users = client.users.get_all()
Error Handling
The SDK provides clear error messages and exceptions:
from clockify_sdk.exceptions import ClockifyError
try:
client.time_entries.create({
"projectId": "invalid-id",
"description": "Test entry"
})
except ClockifyError as e:
print(f"Error: {e.message}")
Development
git clone https://github.com/fraqtory/clockify-sdk.git
cd clockify-sdk
- Create and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate
- Install development dependencies:
pip install -e ".[dev]"
pytest
mypy clockify_sdk
ruff check .
black .
isort .
Documentation
For detailed documentation, visit https://clockify-sdk.readthedocs.io
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.