spoolman 0.1.0__py3-none-any.whl

spoolman/__init__.py

@@ -0,0 +1,16 @@
+"""Asynchronous Python client for Spoolman."""
+
+from .exceptions import SpoolmanConnectionError, SpoolmanError, SpoolmanResponseError
+from .models import Filament, Info, Spool, Vendor
+from .spoolman import Spoolman
+
+__all__ = [
+    "Filament",
+    "Info",
+    "Spool",
+    "Spoolman",
+    "SpoolmanConnectionError",
+    "SpoolmanError",
+    "SpoolmanResponseError",
+    "Vendor",
+]

spoolman/exceptions.py

@@ -0,0 +1,17 @@
+"""Asynchronous Python client for Spoolman."""
+
+
+class SpoolmanError(Exception):
+    """Base class for Spoolman exceptions."""
+
+
+class SpoolmanConnectionError(SpoolmanError):
+    """Error raised when connection to the API fails."""
+
+
+class SpoolmanResponseError(SpoolmanError):
+    """Error raised when the API returns a error."""
+
+    def __init__(self, data: dict[str, str], code: int) -> None:
+        """Initialize the exception."""
+        super().__init__(f'{data["message"]} (code: {code})')

spoolman/models.py

@@ -0,0 +1,77 @@
+"""Asynchronous Python client for Spoolman."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime  # noqa: TC003
+
+from mashumaro import DataClassDictMixin, field_options
+
+
+@dataclass
+class Info(DataClassDictMixin):
+    """Data class for the 'info' endpoint."""
+
+    version: str
+    debug_mode: bool
+    automatic_backups: bool
+    db_type: str
+    git_commit: str
+    build_date: datetime
+    data_dir: str
+    logs_dir: str
+    backups_dir: str
+
+
+@dataclass
+class Filament(DataClassDictMixin):
+    """Data class for filament data."""
+
+    id: int
+    name: str
+    color: str = field(metadata=field_options(alias="color_hex"))
+    vendor: Vendor
+    external_id: str
+    registered: datetime
+
+    material: str
+    density: float
+    diameter: float
+    weight: float
+    spool_weight: float
+    extruder_temp: int = field(metadata=field_options(alias="settings_extruder_temp"))
+    bed_temp: int = field(metadata=field_options(alias="settings_bed_temp"))
+
+
+@dataclass
+class Spool(DataClassDictMixin):
+    """Data class for spool data."""
+
+    id: int
+    filament: Filament
+
+    initial_weight: float
+    spool_weight: float
+    used_weight: float
+    used_length: float
+    remaining_weight: float
+    remaining_length: float
+
+    archived: bool
+    registered: datetime
+    first_used: datetime | None = field(
+        default=None, metadata=field_options(alias="first_used")
+    )
+    last_used: datetime | None = field(
+        default=None, metadata=field_options(alias="last_used")
+    )
+
+
+@dataclass
+class Vendor(DataClassDictMixin):
+    """Data class for vendor data."""
+
+    id: int
+    name: str
+    external_id: str
+    registered: datetime

spoolman/spoolman.py

@@ -0,0 +1,232 @@
+"""Asynchronous Python client for Spoolman."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from dataclasses import dataclass
+from importlib import metadata
+from typing import Any, Self, cast
+
+from aiohttp import ClientError, ClientSession
+from aiohttp.hdrs import METH_GET
+from yarl import URL
+
+from .exceptions import SpoolmanConnectionError, SpoolmanError, SpoolmanResponseError
+from .models import Filament, Info, Spool, Vendor
+
+VERSION = metadata.version(__package__)
+
+
+@dataclass
+class Spoolman:
+    """Main class for handling connections with the Spoolman API."""
+
+    host: str
+    port: int = 7912
+
+    request_timeout: float = 10.0
+    session: ClientSession | None = None
+
+    _close_session: bool = False
+
+    async def _request(
+        self,
+        uri: str,
+        *,
+        method: str = METH_GET,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Handle a request to the Spoolman API.
+
+        Args:
+        ----
+            uri: Request URI, without '/api/', for example, 'status'.
+            method: HTTP method to use.
+            params: Extra options to improve or limit the response.
+
+        Returns:
+        -------
+            A Python dictionary (JSON decoded) with the response from
+            the Spoolman API.
+
+        Raises:
+        ------
+            SpoolmanConnectionError: If the connection to the API fails.
+            SpoolmanError: If the API returns an error.
+            SpoolmanResponseError: If the API returns a error.
+
+        """
+        url = URL.build(
+            scheme="http",
+            host=self.host,
+            port=int(self.port),
+            path="/api/v1/",
+        ).join(URL(uri))
+
+        headers = {
+            "User-Agent": f"PythonSpoolman/{VERSION}",
+            "Accept": "application/json",
+        }
+
+        if self.session is None:
+            self.session = ClientSession()
+            self._close_session = True
+
+        try:
+            async with asyncio.timeout(self.request_timeout):
+                response = await self.session.request(
+                    method,
+                    url,
+                    params=params,
+                    headers=headers,
+                )
+
+                if response.status == 404:
+                    response_data = await response.json()
+                    raise SpoolmanResponseError(response_data, response.status)
+
+                response.raise_for_status()
+
+        except TimeoutError as exception:
+            msg = "Timeout occurred while connecting to the Spoolman API."
+            raise SpoolmanConnectionError(msg) from exception
+        except (ClientError, socket.gaierror) as exception:
+            msg = "Error occurred while connecting to the Spoolman API."
+            raise SpoolmanConnectionError(msg) from exception
+
+        content_type = response.headers.get("content-type", "")
+        if "application/json" not in content_type:
+            text = await response.text()
+            msg = "Unexpected response from the Spoolman API."
+            raise SpoolmanError(
+                msg,
+                {"Content-Type": content_type, "Response": text},
+            )
+
+        return cast(dict[str, Any], await response.json())
+
+    async def info(self) -> Info:
+        """Get information about the Spoolman API.
+
+        Returns
+        -------
+            A dictionary with information about the Spoolman API.
+
+        """
+        response = await self._request("info")
+        return Info.from_dict(response)
+
+    async def health(self) -> bool:
+        """Check the health of the Spoolman API.
+
+        Returns
+        -------
+            True if the API is healthy, False otherwise.
+
+        """
+        response: dict[str, str] = await self._request("health")
+        return response["status"] == "healthy"
+
+    async def get_filaments(self) -> list[Filament]:
+        """Get a list of all available filaments.
+
+        Returns
+        -------
+            A list with filament data.
+
+        """
+        response = await self._request("filament")
+        return [Filament.from_dict(item) for item in response]
+
+    async def get_filament(self, filament_id: int) -> Filament:
+        """Get a specific filament by ID.
+
+        Args:
+        ----
+            filament_id: The ID of the filament to retrieve.
+
+        Returns:
+        -------
+            A dictionary with the filament data.
+
+        """
+        response = await self._request(f"filament/{filament_id}")
+        return Filament.from_dict(response)
+
+    async def get_spools(self) -> list[Spool]:
+        """Get a list of all available spools.
+
+        Returns
+        -------
+            A list with spool data.
+
+        """
+        response = await self._request("spool")
+        return [Spool.from_dict(item) for item in response]
+
+    async def get_spool(self, spool_id: int) -> Spool:
+        """Get a specific spool by ID.
+
+        Args:
+        ----
+            spool_id: The ID of the spool to retrieve.
+
+        Returns:
+        -------
+            A dictionary with the spool data.
+
+        """
+        response = await self._request(f"spool/{spool_id}")
+        return Spool.from_dict(response)
+
+    async def get_vendors(self) -> list[Vendor]:
+        """Get a list of all available vendors.
+
+        Returns
+        -------
+            A list with vendor data.
+
+        """
+        response = await self._request("vendor")
+        return [Vendor.from_dict(item) for item in response]
+
+    async def get_vendor(self, vendor_id: int) -> Vendor:
+        """Get a specific vendor by ID.
+
+        Args:
+        ----
+            vendor_id: The ID of the vendor to retrieve.
+
+        Returns:
+        -------
+            A dictionary with the vendor data.
+
+        """
+        response = await self._request(f"vendor/{vendor_id}")
+        return Vendor.from_dict(response)
+
+    async def close(self) -> None:
+        """Close open client session."""
+        if self.session and self._close_session:
+            await self.session.close()
+
+    async def __aenter__(self) -> Self:
+        """Async enter.
+
+        Returns
+        -------
+            The Spoolman object.
+
+        """
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Async exit.
+
+        Args:
+        ----
+            _exc_info: Exec type.
+
+        """
+        await self.close()

spoolman-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Klaas Schoute
+
+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.

spoolman-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.1
+Name: spoolman
+Version: 0.1.0
+Summary: Asynchronous Python client for Spoolman API
+Home-page: https://github.com/klaasnicolaas/python-spoolman
+License: MIT
+Keywords: spoolman,api,async,client
+Author: Klaas Schoute
+Author-email: hello@student-techlife.com
+Maintainer: Klaas Schoute
+Maintainer-email: hello@student-techlife.com
+Requires-Python: >=3.11,<4.0
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiohttp (>=3.0.0)
+Requires-Dist: mashumaro (>=3.15,<4.0)
+Requires-Dist: yarl (>=1.6.0)
+Project-URL: Bug Tracker, https://github.com/klaasnicolaas/python-spoolman/issues
+Project-URL: Changelog, https://github.com/klaasnicolaas/python-spoolman/releases
+Project-URL: Documentation, https://github.com/klaasnicolaas/python-spoolman
+Project-URL: Repository, https://github.com/klaasnicolaas/python-spoolman
+Description-Content-Type: text/markdown
+
+<!-- Banner -->
+![alt Banner of the Spoolman package](https://raw.githubusercontent.com/klaasnicolaas/python-spoolman/main/assets/header_spoolman-min.png)
+
+<!-- PROJECT SHIELDS -->
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![GitHub Activity][commits-shield]][commits-url]
+[![PyPi Downloads][downloads-shield]][downloads-url]
+[![GitHub Last Commit][last-commit-shield]][commits-url]
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+[![Build Status][build-shield]][build-url]
+[![Typing Status][typing-shield]][typing-url]
+[![Code Coverage][codecov-shield]][codecov-url]
+
+
+Asynchronous Python client for [Spoolman][spoolman].
+
+## About
+
+Spoolman is a self-hosted platform for managing 3D printer filament spools. It integrates with popular 3D printing software to track spool weights in real time, providing instant insights into filament usage.
+
+## Installation
+
+```bash
+pip install spoolman
+```
+
+## Data
+
+- Application info and health
+- Filaments
+- Spools
+- Vendors
+
+### Example
+
+```python
+import asyncio
+
+from spoolman import Spoolman
+
+
+async def main() -> None:
+    """Show example on using this package."""
+    async with Spoolman(host="IP_ADDRESS") as client:
+        # Get all filaments
+        filaments = await client.get_filaments()
+        print(filaments)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+More examples can be found in the [examples folder](./examples/).
+
+## Class Parameters
+
+| Parameter | value Type | Description                                                       |
+| :-------- | :--------- | :---------------------------------------------------------------- |
+| `host`    | `str`      | The IP address of your Spoolman instance.                         |
+| `port`    | `int`      | The port of your Spoolman instance (optional). Default is `7912`. |
+
+## Contributing
+
+This is an active open-source project. We are always open to people who want to
+use the code or contribute to it.
+
+We've set up a separate document for our
+[contribution guidelines](CONTRIBUTING.md).
+
+Thank you for being involved! :heart_eyes:
+
+## Setting up development environment
+
+The simplest way to begin is by utilizing the [Dev Container][devcontainer]
+feature of Visual Studio Code or by opening a CodeSpace directly on GitHub.
+By clicking the button below you immediately start a Dev Container in Visual Studio Code.
+
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+This Python project relies on [Poetry][poetry] as its dependency manager,
+providing comprehensive management and control over project dependencies.
+
+You need at least:
+
+- Python 3.11+
+- [Poetry][poetry-install]
+
+### Installation
+
+Install all packages, including all development requirements:
+
+```bash
+poetry install
+```
+
+_Poetry creates by default an virtual environment where it installs all
+necessary pip packages_.
+
+### Pre-commit
+
+This repository uses the [pre-commit][pre-commit] framework, all changes
+are linted and tested with each commit. To setup the pre-commit check, run:
+
+```bash
+poetry run pre-commit install
+```
+
+And to run all checks and tests manually, use the following command:
+
+```bash
+poetry run pre-commit run --all-files
+```
+
+### Testing
+
+It uses [pytest](https://docs.pytest.org/en/stable/) as the test framework. To run the tests:
+
+```bash
+poetry run pytest
+```
+
+To update the [syrupy](https://github.com/tophat/syrupy) snapshot tests:
+
+```bash
+poetry run pytest --snapshot-update
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2024 Klaas Schoute
+
+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.
+
+
+<!-- LINKS FROM PLATFORM -->
+[spoolman]: https://github.com/Donkie/Spoolman
+
+<!-- MARKDOWN LINKS & IMAGES -->
+[build-shield]: https://github.com/klaasnicolaas/python-spoolman/actions/workflows/tests.yaml/badge.svg
+[build-url]: https://github.com/klaasnicolaas/python-spoolman/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/klaasnicolaas/python-spoolman/branch/main/graph/badge.svg?token=C92VQ5QJ21
+[codecov-url]: https://codecov.io/gh/klaasnicolaas/python-spoolman
+[commits-shield]: https://img.shields.io/github/commit-activity/y/klaasnicolaas/python-spoolman.svg
+[commits-url]: https://github.com/klaasnicolaas/python-spoolman/commits/main
+[devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
+[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/klaasnicolaas/python-spoolman
+[downloads-shield]: https://img.shields.io/pypi/dm/spoolman
+[downloads-url]: https://pypistats.org/packages/spoolman
+[last-commit-shield]: https://img.shields.io/github/last-commit/klaasnicolaas/python-spoolman.svg
+[license-shield]: https://img.shields.io/github/license/klaasnicolaas/python-spoolman.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2024.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[pypi]: https://pypi.org/project/spoolman/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/spoolman
+[releases-shield]: https://img.shields.io/github/release/klaasnicolaas/python-spoolman.svg
+[releases]: https://github.com/klaasnicolaas/python-spoolman/releases
+[typing-shield]: https://github.com/klaasnicolaas/python-spoolman/actions/workflows/typing.yaml/badge.svg
+[typing-url]: https://github.com/klaasnicolaas/python-spoolman/actions/workflows/typing.yaml
+
+[poetry-install]: https://python-poetry.org/docs/#installation
+[poetry]: https://python-poetry.org
+[pre-commit]: https://pre-commit.com
+

spoolman-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+spoolman/__init__.py,sha256=KPT4TNG6AfbKSTW37VXeseYC3HTCGG-xpWMsiSGAgkM,382
+spoolman/exceptions.py,sha256=hkIz38_iDIyxFjHX2Dct95bQVqjkLukgdVjboBu17Lk,499
+spoolman/models.py,sha256=Yn8sb-hZN56sp6fEDdGSfrgmJpnStJBBNqxzRICR2uU,1712
+spoolman/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spoolman/spoolman.py,sha256=GsXibjjRhZD6Zr9siPlgE8m3fr95ywsWpUGzLY1u4Ig,6360
+spoolman-0.1.0.dist-info/LICENSE,sha256=nOLtdGoimVCQz204AqZzOsotGIdncRI-hQ7hRHk3P2I,1070
+spoolman-0.1.0.dist-info/METADATA,sha256=nO5_8xtXpwqbOxWgC-t_7Z2sVmskFhu031nH74V9fnk,7996
+spoolman-0.1.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+spoolman-0.1.0.dist-info/RECORD,,

spoolman-0.1.0.dist-info/WHEEL

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