klokku-python-client 0.1.0__py3-none-any.whl

klokku_python_client/__init__.py

@@ -0,0 +1,35 @@
+from .api_client import (
+    # Exception classes
+    KlokkuApiError,
+    KlokkuAuthenticationError,
+    KlokkuNetworkError,
+    KlokkuApiResponseError,
+    KlokkuDataParsingError,
+    KlokkuDataStructureError,
+    
+    # Data classes
+    Budget,
+    User,
+    Event,
+    
+    # Main API client
+    KlokkuApi,
+)
+
+__all__ = [
+    # Exception classes
+    'KlokkuApiError',
+    'KlokkuAuthenticationError',
+    'KlokkuNetworkError',
+    'KlokkuApiResponseError',
+    'KlokkuDataParsingError',
+    'KlokkuDataStructureError',
+    
+    # Data classes
+    'Budget',
+    'User',
+    'Event',
+    
+    # Main API client
+    'KlokkuApi',
+]

klokku_python_client/api_client.py

@@ -0,0 +1,304 @@
+import aiohttp
+import logging
+from typing import Optional
+
+from dataclasses import dataclass
+
+_LOGGER = logging.getLogger(__name__)
+
+class KlokkuApiError(Exception):
+    """Base exception for all Klokku API errors."""
+    pass
+
+class KlokkuAuthenticationError(KlokkuApiError):
+    """Raised when authentication fails or user is not authenticated."""
+    pass
+
+class KlokkuNetworkError(KlokkuApiError):
+    """Raised when there's a network-related error."""
+    pass
+
+class KlokkuApiResponseError(KlokkuApiError):
+    """Raised when the API returns an error response."""
+    def __init__(self, status_code: int, message: str = None):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"API returned error {status_code}: {message}")
+
+class KlokkuDataParsingError(KlokkuApiError):
+    """Raised when there's an error parsing the API response data."""
+    pass
+
+class KlokkuDataStructureError(KlokkuApiError):
+    """Raised when the API response data doesn't have the expected structure."""
+    pass
+
+@dataclass(frozen=True)
+class Budget:
+    id: int
+    name: str
+    weeklyTime: int
+    icon: str = ""
+    status: str = "ACTIVE"
+
+@dataclass(frozen=True)
+class User:
+    id: int
+    username: str
+    display_name: str
+
+@dataclass(frozen=True)
+class Event:
+    id: int
+    startTime: str
+    budget: Budget
+
+class KlokkuApi:
+
+    url: str = ""
+    username: str = ""
+    user_id: int = 0
+    session: Optional[aiohttp.ClientSession] = None
+
+    def __init__(self, url):
+        self.url = url
+        self.session = None
+
+    async def __aenter__(self):
+        self.session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self.session:
+            await self.session.close()
+            self.session = None
+
+    async def authenticate(self, username: str) -> bool:
+        """
+        Authenticate with the API using a username.
+        :param username: The username to authenticate with.
+        :return: True if authentication was successful, False otherwise.
+        :raises KlokkuNetworkError: If there's a network error.
+        :raises KlokkuApiResponseError: If the API returns an error response.
+        :raises KlokkuDataParsingError: If there's an error when parsing the response.
+        :raises KlokkuDataStructureError: If the response doesn't have the expected structure.
+        """
+        try:
+            users = await self.get_users()
+            if not users:
+                return False
+            for user in users:
+                if user.username == username:
+                    self.user_id = user.id
+                    return True
+            return False
+        except KlokkuApiError as e:
+            _LOGGER.error(f"Authentication error: {e}")
+            return False
+
+    @staticmethod
+    def __headers(user_id: int) -> dict:
+        return {
+            "X-User-Id": str(user_id)
+        }
+
+    async def get_current_event(self) -> Event | None:
+        """
+        Fetch the current budget from the API.
+        :return: Parsed current budget data as a dictionary.
+        :raises KlokkuAuthenticationError: If the user is not authenticated.
+        :raises KlokkuNetworkError: If there's a network error.
+        :raises KlokkuApiResponseError: If the API returns an error response.
+        :raises KlokkuDataParsingError: If there's an error when parsing the response.
+        :raises KlokkuDataStructureError: If the response doesn't have the expected structure.
+        """
+        if not self.user_id:
+            error = KlokkuAuthenticationError("Unauthenticated - cannot fetch current budget")
+            _LOGGER.warning(str(error))
+            return None
+
+        url = f"{self.url}api/event/current"
+        try:
+            # Create a session if one doesn't exist
+            if not self.session:
+                self.session = aiohttp.ClientSession()
+                close_after = True
+            else:
+                close_after = False
+
+            try:
+                async with self.session.get(url, headers=self.__headers(self.user_id)) as response:
+                    if response.status >= 400:
+                        error_msg = await response.text()
+                        raise KlokkuApiResponseError(response.status, error_msg)
+
+                    try:
+                        data = await response.json()
+                    except aiohttp.ClientResponseError as e:
+                        raise KlokkuDataParsingError(f"Failed to parse JSON response: {e}")
+
+                    try:
+                        result = Event(
+                            id=data["id"],
+                            startTime=data["startTime"],
+                            budget=Budget(**data["budget"]),
+                        )
+                    except (KeyError, TypeError, ValueError) as e:
+                        raise KlokkuDataStructureError(f"Unexpected data structure in response: {e}")
+            except aiohttp.ClientConnectionError as e:
+                raise KlokkuNetworkError(f"Connection error: {e}")
+
+            # Close the session if we created it in this method
+            if close_after:
+                await self.session.close()
+                self.session = None
+
+            return result
+        except KlokkuApiError as e:
+            _LOGGER.error(f"Error fetching current budget: {e}")
+            return None
+
+    async def get_all_budgets(self) -> list[Budget] | None:
+        """
+        Fetch all budgets from the API.
+        :return: Parsed list of all budgets.
+        :raises KlokkuAuthenticationError: If the user is not authenticated.
+        :raises KlokkuNetworkError: If there's a network error.
+        :raises KlokkuApiResponseError: If the API returns an error response.
+        :raises KlokkuDataParsingError: If there's an error when parsing the response.
+        :raises KlokkuDataStructureError: If the response doesn't have the expected structure.
+        """
+        if not self.user_id:
+            error = KlokkuAuthenticationError("Unauthenticated - cannot fetch budgets")
+            _LOGGER.warning(str(error))
+            return None
+
+        url = f"{self.url}api/budget"
+        try:
+            # Create a session if one doesn't exist
+            if not self.session:
+                self.session = aiohttp.ClientSession()
+                close_after = True
+            else:
+                close_after = False
+
+            try:
+                async with self.session.get(url, headers=self.__headers(self.user_id)) as response:
+                    if response.status >= 400:
+                        error_msg = await response.text()
+                        raise KlokkuApiResponseError(response.status, error_msg)
+
+                    try:
+                        data = await response.json()
+                    except aiohttp.ClientResponseError as e:
+                        raise KlokkuDataParsingError(f"Failed to parse JSON response: {e}")
+
+                    try:
+                        result = [Budget(**budget) for budget in data]
+                    except (KeyError, TypeError, ValueError) as e:
+                        raise KlokkuDataStructureError(f"Unexpected data structure in response: {e}")
+            except aiohttp.ClientConnectionError as e:
+                raise KlokkuNetworkError(f"Connection error: {e}")
+
+            # Close the session if we created it in this method
+            if close_after:
+                await self.session.close()
+                self.session = None
+
+            return result
+        except KlokkuApiError as e:
+            _LOGGER.error(f"Error fetching all budgets: {e}")
+            return None
+
+    async def get_users(self) -> list[User] | None:
+        """
+        Fetch all users from the API.
+        :return: Parsed list of all users.
+        :raises KlokkuNetworkError: If there's a network error.
+        :raises KlokkuApiResponseError: If the API returns an error response.
+        :raises KlokkuDataParsingError: If there's an error when parsing the response.
+        :raises KlokkuDataStructureError: If the response doesn't have the expected structure.
+        """
+        url = f"{self.url}api/user"
+        try:
+            # Create a session if one doesn't exist
+            if not self.session:
+                self.session = aiohttp.ClientSession()
+                close_after = True
+            else:
+                close_after = False
+
+            try:
+                async with self.session.get(url) as response:
+                    if response.status >= 400:
+                        error_msg = await response.text()
+                        raise KlokkuApiResponseError(response.status, error_msg)
+
+                    try:
+                        data = await response.json()
+                    except aiohttp.ClientResponseError as e:
+                        raise KlokkuDataParsingError(f"Failed to parse JSON response: {e}")
+
+                    try:
+                        result = [User(id=user["id"], username=user["username"], display_name=user["displayName"]) for user in data]
+                    except (KeyError, TypeError) as e:
+                        raise KlokkuDataStructureError(f"Unexpected data structure in response: {e}")
+            except aiohttp.ClientConnectionError as e:
+                raise KlokkuNetworkError(f"Connection error: {e}")
+
+            # Close the session if we created it in this method
+            if close_after:
+                await self.session.close()
+                self.session = None
+
+            return result
+        except KlokkuApiError as e:
+            _LOGGER.error(f"Error fetching all users: {e}")
+            return None
+
+    async def set_current_budget(self, budget_id: int):
+        """
+        Sets the currently used budget.
+        :param budget_id: The ID of the budget to set as current.
+        :return: The response data or None if an error occurred.
+        :raises KlokkuAuthenticationError: If the user is not authenticated.
+        :raises KlokkuNetworkError: If there's a network error.
+        :raises KlokkuApiResponseError: If the API returns an error response.
+        :raises KlokkuDataParsingError: If there's an error when parsing the response.
+        """
+        if not self.user_id:
+            error = KlokkuAuthenticationError("Unauthenticated - cannot set current budget")
+            _LOGGER.warning(str(error))
+            return None
+
+        url = f"{self.url}api/event"
+        try:
+            # Create a session if one doesn't exist
+            if not self.session:
+                self.session = aiohttp.ClientSession()
+                close_after = True
+            else:
+                close_after = False
+
+            try:
+                async with self.session.post(url, headers=self.__headers(self.user_id), json={"budgetId": budget_id}) as response:
+                    if response.status >= 400:
+                        error_msg = await response.text()
+                        raise KlokkuApiResponseError(response.status, error_msg)
+
+                    try:
+                        data = await response.json()
+                    except aiohttp.ClientResponseError as e:
+                        raise KlokkuDataParsingError(f"Failed to parse JSON response: {e}")
+            except aiohttp.ClientConnectionError as e:
+                raise KlokkuNetworkError(f"Connection error: {e}")
+
+            # Close the session if we created it in this method
+            if close_after:
+                await self.session.close()
+                self.session = None
+
+            return data
+        except KlokkuApiError as e:
+            _LOGGER.error(f"Error setting current budget: {e}")
+            return None

klokku_python_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: klokku-python-client
+Version: 0.1.0
+Summary: Klokku REST API client
+License: MIT
+Author: Mariusz Józala
+Requires-Python: >=3.13
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Requires-Dist: aiohttp (>=3.11.16,<4.0.0)
+Project-URL: Homepage, https://klokku.com
+Project-URL: Issues, https://github.com/klokku/klokku-python-client/issues
+Project-URL: Repository, https://github.com/klokku/klokku-python-client
+Description-Content-Type: text/markdown
+
+# Klokku Python Client
+
+A Python client for interacting with the Klokku REST API.
+
+## Installation
+
+### Using pip
+
+```bash
+pip install klokku-python-client
+```
+
+### Using Poetry
+
+```bash
+poetry add klokku-python-client
+```
+
+## Usage
+
+The client provides an asynchronous interface to the Klokku API:
+
+```python
+import asyncio
+from klokku_python_client import KlokkuApi
+
+async def main():
+    # Create a client instance
+    async with KlokkuApi("https://api.klokku.example.com/") as client:
+        # Authenticate with a username
+        authenticated = await client.authenticate("your_username")
+        if not authenticated:
+            print("Authentication failed")
+            return
+
+        # Get all budgets
+        budgets = await client.get_all_budgets()
+        if budgets:
+            print(f"Found {len(budgets)} budgets:")
+            for budget in budgets:
+                print(f"- {budget.name} (ID: {budget.id})")
+
+        # Get current event
+        current_event = await client.get_current_event()
+        if current_event:
+            print(f"Current budget: {current_event.budget.name}")
+            print(f"Started at: {current_event.startTime}")
+
+        # Set a different budget
+        if budgets and len(budgets) > 1:
+            new_budget_id = budgets[1].id
+            result = await client.set_current_budget(new_budget_id)
+            if result:
+                print(f"Set current budget to ID: {new_budget_id}")
+
+# Run the async function
+asyncio.run(main())
+```
+
+## Features
+
+- Asynchronous API client using `aiohttp`
+- Authentication with username
+- Get list of users
+- Get all budgets
+- Get current event/budget
+- Set current budget
+- Context manager support for proper resource cleanup
+
+## Development
+
+### Setup
+
+1. Clone the repository
+2. Install dependencies with Poetry:
+
+```bash
+poetry install
+```
+
+### Testing
+
+The project uses pytest for testing with aioresponses for mocking HTTP requests.
+
+To install test dependencies:
+
+```bash
+pip install -e ".[test]"
+```
+
+Or with Poetry:
+
+```bash
+poetry install --with test
+```
+
+To run the tests:
+
+```bash
+pytest
+```
+
+For more details about testing, see the [tests README](tests/README.md).
+
+## Requirements
+
+- Python 3.13+
+- aiohttp 3.11+
+
+## License
+
+[MIT](LICENSE)
+

klokku_python_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+klokku_python_client/__init__.py,sha256=1AOx109cSpBOiz_-bLMFgZxEU-EkYl9KksZL3aK3pYM,631
+klokku_python_client/api_client.py,sha256=6xXKOvlTuE57ynSpN70ZSRt2w5-E3yyLMg94yW7mzeI,11735
+klokku_python_client-0.1.0.dist-info/METADATA,sha256=pZXy4QbfegI_A02G7A6EKOWNinNPA8D-n6qGGaEQe6c,2767
+klokku_python_client-0.1.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+klokku_python_client-0.1.0.dist-info/RECORD,,

klokku_python_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.2
+Root-Is-Purelib: true
+Tag: py3-none-any