busylib 0.0.1__py3-none-any.whl → 0.0.1a0__py3-none-any.whl

busylib/__init__.py

@@ -0,0 +1,82 @@
+"""
+Main library for interacting with the Busy Bar API.
+"""
+
+from typing import IO
+
+from busylib.client import ApiClient
+from busylib.types import ApiResponse
+
+
+class BusyBar:
+    """
+    Main library class for interacting with the Busy Bar API.
+    """
+
+    def __init__(self, addr: str = "10.0.4.20"):
+        """
+        Creates an instance of BUSY Bar.
+        Initializes the API client with the provided address.
+
+        :param addr: The address of the device.
+        """
+        self._addr = addr
+        self._client = ApiClient(f"http://{self._addr}/api/")
+
+    def upload_asset(
+        self, app_id: str, file_name: str, file: bytes | IO[bytes]
+    ) -> ApiResponse | None:
+        """
+        Uploads an asset to the device.
+
+        :param app_id: Application ID for organizing assets.
+        :param file_name: Filename for the uploaded asset.
+        :param file: File data to upload (bytes or file-like object).
+        :return: Result of the upload operation.
+        """
+        return self._client.upload_asset(app_id, file_name, file)
+
+    def delete_assets(self, app_id: str) -> ApiResponse | None:
+        """
+        Deletes all assets for a specific application from the device.
+
+        :param app_id: Application ID whose assets should be deleted.
+        :return: Result of the delete operation.
+        """
+        return self._client.delete_assets(app_id)
+
+    def draw_display(self, app_id: str, elements: list[dict]) -> ApiResponse | None:
+        """
+        Draws elements on the device display.
+
+        :param app_id: Application ID for organizing display elements.
+        :param elements: Array of display elements (text or image).
+        :return: Result of the draw operation.
+        """
+        return self._client.draw_display(app_id, elements)
+
+    def clear_display(self) -> ApiResponse | None:
+        """
+        Clears the device display.
+
+        :return: Result of the clear operation.
+        """
+        return self._client.clear_display()
+
+    def play_sound(self, app_id: str, path: str) -> ApiResponse | None:
+        """
+        Plays an audio file from the assets directory.
+
+        :param app_id: Application ID for organizing assets.
+        :param path: Path to the audio file within the app's assets directory.
+        :return: Result of the play operation.
+        """
+        return self._client.play_audio(app_id, path)
+
+    def stop_sound(self) -> ApiResponse | None:
+        """
+        Stops any currently playing audio on the device.
+
+        :return: Result of the stop operation.
+        """
+        return self._client.stop_audio()

busylib/client.py

@@ -0,0 +1,108 @@
+import requests
+from typing import IO
+from busylib.types import ApiResponse
+
+
+class ApiClient:
+    def __init__(self, base_url: str):
+        if not base_url.endswith("/"):
+            base_url += "/"
+        self.base_url = base_url
+        self.session = requests.Session()
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, object] | None = None,
+        json: object | None = None,
+        data: object | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> ApiResponse:
+        url = f"{self.base_url}{endpoint}"
+        try:
+            response = self.session.request(
+                method, url, params=params, json=json, data=data, headers=headers
+            )
+            response.raise_for_status()
+            if response.status_code == 204 or not response.content:
+                return None
+            # We expect a JSON response that can be mapped to our dataclass
+            data = response.json()
+            return ApiResponse(
+                success=data.get("success", True), message=data.get("message")
+            )
+        except requests.exceptions.RequestException as e:
+            # Re-raise as a custom exception for better error handling upstream
+            raise ConnectionError(f"API request failed: {e}") from e
+
+    def post(
+        self,
+        endpoint: str,
+        params: dict[str, object] = None,
+        json: object | None = None,
+        data: object | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> ApiResponse | None:
+        return self._request(
+            "POST", endpoint, params=params, json=json, data=data, headers=headers
+        )
+
+    def get(
+        self, endpoint: str, params: dict[str, object] | None = None
+    ) -> ApiResponse | None:
+        return self._request("GET", endpoint, params=params)
+
+    def delete(
+        self, endpoint: str, params: dict[str, object] | None = None
+    ) -> ApiResponse | None:
+        return self._request("DELETE", endpoint, params=params)
+
+    def upload_asset(
+        self, app_id: str, file_name: str, file: bytes | IO[bytes]
+    ) -> ApiResponse | None:
+        """
+        Uploads an asset to the device.
+        """
+        payload = {"app_id": app_id, "file": file_name}
+        headers = {"Content-Type": "application/octet-stream"}
+        return self.post("v0/assets/upload", params=payload, data=file, headers=headers)
+
+    def delete_assets(self, app_id: str) -> ApiResponse | None:
+        """
+        Deletes all assets for a specific application from the device.
+        """
+        params = {"app_id": app_id}
+        return self.delete("v0/assets/upload", params=params)
+
+    def play_audio(self, app_id: str, path: str) -> ApiResponse | None:
+        """
+        Plays an audio file from the assets directory.
+        """
+        params = {"app_id": app_id, "path": path}
+        return self.post("v0/audio/play", params=params)
+
+    def stop_audio(self) -> ApiResponse | None:
+        """
+        Stops any currently playing audio on the device.
+        """
+        return self.delete("v0/audio/play")
+
+    def draw_display(
+        self, app_id: str, elements: list[dict[str, object]]
+    ) -> ApiResponse | None:
+        """
+        Draws elements on the device display.
+        """
+        default_values = {"timeout": 5, "x": 0, "y": 0, "display": "front"}
+
+        normalized_elements = [default_values | e for e in elements]
+        return self.post(
+            "v0/display/draw", json={"app_id": app_id, "elements": normalized_elements}
+        )
+
+    def clear_display(self) -> ApiResponse | None:
+        """
+        Clears the device display.
+        """
+        return self.delete("v0/display/draw")

busylib/types.py

@@ -0,0 +1,9 @@
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class ApiResponse:
+    """A generic response from the BusyBar API"""
+
+    success: bool
+    message: str | None = None

busylib-0.0.1a0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: busylib
+Version: 0.0.1a0
+Summary: Python library for Busy Bar API
+Author-email: Valerii Lisai <v.lisai@flipperdevices.com>
+Project-URL: Homepage, https://github.com/busy-app/busylib
+Project-URL: Repository, https://github.com/busy-app/busylib
+Project-URL: Documentation, https://busylib.readthedocs.io
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.32.4
+Provides-Extra: dev
+Requires-Dist: pytest==8.4.1; extra == "dev"
+Requires-Dist: requests-mock==1.12.1; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# busylib
+
+A simple and intuitive Python client for interacting with the Busy Bar API. This library allows you to programmatically control the device's display, audio, and assets.
+
+## Features
+
+-   Easy-to-use API for all major device functions.
+-   Upload and manage assets for your applications.
+-   Control the display by drawing text and images.
+-   Play and stop audio files.
+-   Built-in validation for device IP addresses.
+
+## Installation
+
+You can install `busylib` directly from PyPI:
+
+```bash
+pip install busylib
+```
+
+## Usage
+
+First, import and initialize the `BusyBar` client with the IP address of your device.
+
+```python
+from busylib import BusyBar
+
+try:
+    # Default IP is 10.0.4.20, but you can specify your own
+    bb = BusyBar("192.168.1.100")
+except ValueError as e:
+    print(f"Error: {e}")
+
+# Now you can use the bb object to interact with your device.
+```
+
+## API Examples
+
+Here are some examples of how to use the library to control your Busy Bar device.
+
+### Uploading an Asset
+
+You can upload files (like images or sounds) to be used by your application on the device.
+
+```python
+# Upload a file from bytes
+with open("path/to/your/image.png", "rb") as f:
+    file_bytes = f.read()
+    bb.upload_asset(
+        app_id="my-app",
+        file_name="logo.png",
+        file=file_bytes
+    )
+
+# Or upload directly from a file-like object
+with open("path/to/your/sound.mp3", "rb") as f:
+    bb.upload_asset(
+        app_id="my-app",
+        file_name="notification.mp3",
+        file=f
+    )
+```
+
+### Drawing on the Display
+
+Draw text or images on the device's screen. The `draw_display` method accepts a list of elements to render.
+
+```python
+elements = [
+    {
+        "type": "text",
+        "value": "Hello, World!",
+        "x": 10,
+        "y": 20,
+        "color": "#FFFFFF" # Optional
+    },
+    {
+        "type": "image",
+        "path": "logo.png", # Must be uploaded first
+        "x": 50,
+        "y": 40
+    }
+]
+
+bb.draw_display(app_id="my-app", elements=elements)
+```
+
+### Clearing the Display
+
+To clear everything from the screen:
+
+```python
+bb.clear_display()
+```
+
+### Playing a Sound
+
+Play an audio file that you have already uploaded.
+
+```python
+bb.play_sound(app_id="my-app", path="notification.mp3")
+```
+
+### Stopping a Sound
+
+To stop any audio that is currently playing:
+
+```python
+bb.stop_sound()
+```
+
+### Deleting All Assets for an App
+
+This will remove all files associated with a specific `app_id`.
+
+```python
+bb.delete_assets(app_id="my-app")
+```
+
+## Development
+
+To set up a development environment, clone the repository and install the package in editable mode with test dependencies:
+
+```bash
+git clone https://github.com/busy-app/busylib
+cd busylib
+python3 -m venv .venv
+source .venv/bin/activate
+make install-dev
+```
+
+To run the tests:
+
+```bash
+make test
+```

busylib-0.0.1a0.dist-info/RECORD

@@ -0,0 +1,8 @@
+busylib/__init__.py,sha256=uxjPUviskpLD81tC5UqRFTTNr1jh7KkvPaKOnUivhFg,2605
+busylib/client.py,sha256=725I_M8AdLUhDI3OjxSZe-giNQsA68lc5Sm1tBFIEJY,3728
+busylib/types.py,sha256=LlBb1-lQraCjAitU-ImI52EXsayXCMcLvEjyuLXsABQ,176
+busylib-0.0.1a0.dist-info/licenses/LICENSE,sha256=aJO9BQGuVb1fvGzHcgWYiwcC9kEFyD-FBb8SPO-ATJ4,1071
+busylib-0.0.1a0.dist-info/METADATA,sha256=ryevnkeOa9xCku8ZdCn14mVJau_SqLbbAfG3jzP_Org,3826
+busylib-0.0.1a0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+busylib-0.0.1a0.dist-info/top_level.txt,sha256=tXeqg2EVVj4E8-ywimkxRzuCJq2HqMXA0571IB15PDA,8
+busylib-0.0.1a0.dist-info/RECORD,,

busylib-0.0.1a0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 Flipper Devices Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

busylib-0.0.1.dist-info/METADATA

@@ -1,19 +0,0 @@
-Metadata-Version: 2.4
-Name: busylib
-Version: 0.0.1
-Summary: Package name reserved
-Home-page: https://github.com/yourusername/busylib
-Author: Your Name
-Author-email: your.email@example.com
-Classifier: Development Status :: 1 - Planning
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.6
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: home-page
-Dynamic: requires-python
-Dynamic: summary
-
-This package name is reserved for future use

busylib-0.0.1.dist-info/RECORD

@@ -1,5 +0,0 @@
-busylib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-busylib-0.0.1.dist-info/METADATA,sha256=Sv52rhD4zCfqKgPLYbddqmEiCJX7vUJ1MxYM-QxtexA,492
-busylib-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-busylib-0.0.1.dist-info/top_level.txt,sha256=tXeqg2EVVj4E8-ywimkxRzuCJq2HqMXA0571IB15PDA,8
-busylib-0.0.1.dist-info/RECORD,,