timebutler-client 0.0.2

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 the get_absences so far, 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

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