timebutler-client 0.0.4

Async Python client for the Timebutler API

timebutler_client

Async Python client for the Timebutler API (official docs).

[!IMPORTANT] This is NOT an official client by Timebutler GmbH, just a community project.

Installation

pip install timebutler-client

Usage

from timebutler_client import TimebutlerClient

# Create client with your API key
client = TimebutlerClient(api_key="your-api-key")

# Fetch absences for a specific year
absences = await client.get_absences(year=2026)

for absence in absences:
    print(f"{absence.employee_number}: {absence.from_date} - {absence.to_date} ({absence.absence_type})")

Features

[!NOTE] We only implemented a subset of the Timebutler API endpoints, because the API is not very convenient to develop against (no OpenAPI, no sandbox or test system, only admin API keys).

• Async HTTP client using aiohttp
• Typed responses using Pydantic models
• Strict date parsing (European dd/mm/yyyy format)
• Employee number handling with leading zeros preserved

Supported Endpoints

Method	Description
get_absences(year)	Fetch absences for a given year
get_projects()	Fetch all projects
get_services()	Fetch all services
get_users()	Fetch all users
get_workdays()	Fetch workday schedules for all users (see note below)
get_worktime(year?, month?, user_id?)	Fetch worktime entries with optional filters

[!NOTE] get_workdays() returns a WorkdaysResult with two named fields: schedules and invalid_employees. invalid_employees contains users whose employee_number field in Timebutler is empty or non-numeric. This is expected — it occurs for DC users on test systems and for new employees who are not yet fully set up in production. Because employee numbers are mandatory for downstream processing, these users are filtered out here rather than propagating incomplete data further along the pipeline.

Example: Tracking Time by Project

from timebutler_client import TimebutlerClient

client = TimebutlerClient(api_key="your-api-key")

# Get all projects and worktime entries
projects = await client.get_projects()
worktime = await client.get_worktime(year=2026, month=1)

# Build a project name lookup
project_names = {p.id: p.name_stripped for p in projects}

# Sum hours by project
for entry in worktime:
    if entry.has_project:
        project_name = project_names.get(entry.project_id, "Unknown")
        print(f"{entry.date}: {entry.duration} on {project_name}")

Development

This project is based on the Hochfrequenz Python Template Repository. Refer to that repository for detailed setup instructions including tox configuration and IDE setup.

Quick Start

# Create dev environment
tox -e dev

# Run tests
tox -e tests

# Run linting
tox -e linting

# Run type checking
tox -e type_check

License

MIT