api_interface

main.Kimai.api_interface

Kimai API Interface Module.

Classes

KimaiAPI(api_key, base_url)

A class to interact with the Clockify API for project management.

Initialize the KimaiAPI instance.

Parameters:

Name	Type	Description	Default
api_key	str	Your personal Kimai API key.	required
base_url	str	The base url of Kimai API.	required

Source code in main/Kimai/api_interface.py

def __init__(self, api_key: str, base_url: str):
    """Initialize the KimaiAPI instance.

    Args:
        api_key: Your personal Kimai API key.
        base_url: The base url of Kimai API.
    """
    if not api_key or not base_url:
        raise ValueError("Missing Kimai API key, base_url or both.")

    self.api_key = api_key
    self.base_url = base_url
    self.headers = {
        "Accept": "application/json",
        "Authorization": f"Bearer {self.api_key}",
    }

Methods:

get_time_entries(start_date, end_date, project_id)

Retrieve detailed time entries for a specified workspace using the API.

Parameters:

Name	Type	Description	Default
start_date	datetime	First day of the time entries to be retrieved.	required
end_date	datetime	Last day of the time entries to be retrieved.	required
project_id	int	Kimai id of the project to retrieve time entries for.	required

Returns:

Type	Description
list[dict[str, Any]]	List of dictionaries containing the entry id, project id, user email and
list[dict[str, Any]]	begin and end date time for the entry.

Raises:

Type	Description
HTTPError	If the API request fails.

Source code in main/Kimai/api_interface.py

def get_time_entries(  # type: ignore[explicit-any]
    self, start_date: datetime, end_date: datetime, project_id: int
) -> list[dict[str, Any]]:
    """Retrieve detailed time entries for a specified workspace using the API.

    Args:
        start_date: First day of the time entries to be retrieved.
        end_date: Last day of the time entries to be retrieved.
        project_id: Kimai id of the project to retrieve time entries for.

    Returns:
        List of dictionaries containing the entry id, project id, user email and
        begin and end date time for the entry.

    Raises:
        HTTPError: If the API request fails.
    """
    url = f"{self.base_url}/timesheets"

    payload: Mapping[str, Any] = {  # type: ignore[explicit-any]
        "begin": start_date.strftime("%Y-%m-%dT00:00:00"),
        "end": end_date.strftime("%Y-%m-%dT23:59:59"),
        "full": 1,
        "billable": 1,
        "size": 500,
        "project": project_id,
        "user": "all",
    }

    response = requests.request(
        "GET", url, headers=self.headers, params=payload, verify=False
    )

    if response.status_code == 200:
        try:
            return [_process_entry(p) for p in response.json()]
        except ValueError as e:
            logger.error(
                "There was a problem processing time entries for project "
                f"{project_id}: {e}"
            )
            return []
    else:
        response.raise_for_status()
    return []