https://github.com/fraqtory/clockify-sdk
Python SDK for Clockify API
https://github.com/fraqtory/clockify-sdk
api clockify sdk
Last synced: 3 months ago
JSON representation
Python SDK for Clockify API
- Host: GitHub
- URL: https://github.com/fraqtory/clockify-sdk
- Owner: Fraqtory
- License: mit
- Created: 2025-03-16T18:20:36.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-20T09:34:34.000Z (6 months ago)
- Last Synced: 2025-11-27T13:22:14.325Z (4 months ago)
- Topics: api, clockify, sdk
- Language: Python
- Homepage:
- Size: 87.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
- 📈 Advanced reporting with minimum hours tracking
- 🔴 Visual alerts for developers not meeting minimum hours
- ✨ Type hints for better IDE support
## Installation
```bash
pip install clockify-sdk
```
## Quick Start
First, create a `.env` file in your project root:
```env
CLOCKIFY_API_KEY=your-api-key
CLOCKIFY_WORKSPACE_ID=your-workspace-id # Optional, defaults to first workspace
```
Then use the SDK:
```python
from dotenv import load_dotenv
import os
from clockify_sdk import Clockify
from datetime import datetime
# Load environment variables from .env file
load_dotenv()
# Initialize the client
client = Clockify(
api_key=os.getenv("CLOCKIFY_API_KEY"),
workspace_id=os.getenv("CLOCKIFY_WORKSPACE_ID") # Optional
)
# Get all your workspaces
workspaces = client.get_workspaces()
# Create a new time entry
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"
)
# Get all projects
projects = client.projects.get_all()
# Create a new project
project = client.projects.create({
"name": "New Project",
"clientId": "client-id",
"isPublic": True
})
# Get time entries for a specific date range
time_entries = client.time_entries.get_all(
user_id=client.user_id,
start_date="2024-03-01",
end_date="2024-03-17"
)
# Generate a detailed report
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
```python
# Create a new task
task = client.tasks.create({
"name": "Implement new feature",
"assigneeId": "user-id"
}, project_id="project-id")
# Get all tasks for a project
tasks = client.tasks.get_all(project_id="project-id")
```
### Managing Clients
```python
# Create a new client
new_client = client.clients.create({
"name": "New Client",
"note": "Important client"
})
# Get all clients
clients = client.clients.get_all()
```
### User Management
```python
# Get current user information
current_user = client.users.get_current_user()
# Get all users in workspace
users = client.users.get_all()
```
### Minimum Hours Tracking
The SDK includes advanced reporting features with minimum hours tracking:
```python
# Create a developer_minimums.json file with your team's requirements
{
"user_id_1": {
"name": "John Doe",
"minimum_weekly_hours": 40
},
"user_id_2": {
"name": "Jane Smith",
"minimum_weekly_hours": 35
}
}
# Use the project detail reporter with minimum hours tracking
from examples.project_detail import ProjectDetailReporter
reporter = ProjectDetailReporter(api_key, workspace_id)
reporter.run() # Interactive interface with 🔴 alerts for non-compliant developers
```
**Getting User IDs for Configuration:**
```bash
# List all users in your Clockify workspace to get their IDs
python examples/minimum_hours_example.py --list-users
# Or run the interactive example
python examples/minimum_hours_example.py
```
The system automatically:
- Shows 🔴 emoji prefix for developers not meeting their minimum hours
- Calculates expected minimums for monthly reports based on number of weeks
- Pro-rates minimums for partial periods (current week, this month)
## Error Handling
The SDK provides clear error messages and exceptions:
```python
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
1. Clone the repository:
```bash
git clone https://github.com/fraqtory/clockify-sdk.git
cd clockify-sdk
```
2. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows, use `.venv\Scripts\activate`
```
3. Install development dependencies:
```bash
pip install -e ".[dev]"
```
4. Run tests:
```bash
pytest
```
5. Run type checking:
```bash
mypy clockify_sdk
```
6. Run linting:
```bash
ruff check .
black .
isort .
```
## Documentation
For detailed documentation, visit [https://clockify-sdk.readthedocs.io](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.