pyJPI 0.1.13__py3-none-any.whl

pyjpi/__init__.py

@@ -0,0 +1,28 @@
+"""JPI Library."""
+
+from __future__ import annotations
+
+import asyncio
+from importlib.metadata import PackageNotFoundError, version
+
+import aiohttp
+
+from .library import JPILibrary
+
+
+async def _get_version() -> str:
+    """Returns the version of the package (hopefully)."""
+    try:
+        return await asyncio.to_thread(version, "pyJPI")
+    except PackageNotFoundError:
+        return "0+local"
+
+
+async def jpiInit(session: aiohttp.ClientSession) -> JPILibrary:
+    """
+    Initialize the library.
+    Returns an object with an initialized HTTP session.
+    This same object will have to be provided later on each called method.
+    """
+    package_version = await _get_version()
+    return JPILibrary(session, package_version)

pyjpi/library.py

@@ -0,0 +1,96 @@
+"""
+A library to interact with JPI devices.
+Rationale: according to HomeAssistant documentation, the integration MUST not interact directly with the physical devices.
+Instead, it MUST use a library published on pyPI repository.
+This file is so the first version of such the interaction library.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+import logging
+
+from aiohttp.web import HTTPError
+
+
+class JPILibrary:
+    """Class for the pyJPI library."""
+
+    def __init__(self, session, version):
+        """Initialize a HTTP session."""
+        self._session = session
+        self._initialized = datetime.now()
+        self._log = logging.getLogger(__name__)
+        self._log.debug("JPILibrary v%s successfully instantiated", version)
+
+    def _batt_parse_text(self, text: str) -> dict:
+        """
+        Parse battery info text into a structured dictionary.
+        Input:
+            Niveau: 52%
+            En charge: NON
+            Alim. connectée: NON
+        Output:
+            {'level': 52, 'charging': False, 'power': False}
+        """
+        result = {}
+        for line in text.splitlines():
+            if not line.strip():
+                continue  # skip empty lines
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if key == "Niveau":
+                result["level"] = int(value.strip("%"))
+            elif key == "En charge":
+                result["charging"] = value.upper() == "OUI"
+            elif key == "Alim. connectée":
+                result["power"] = value.upper() == "OUI"
+        return result
+
+    async def battInfo(self, url: str):
+        """
+        Returns the battery informations as a hash:
+            level: <int>
+            charging: <bool>
+            power: <bool>
+        """
+        target = f"{url}?action=battInfo"
+        resp = await self.get(target)
+        result = None
+        self._log.debug("battInfo resp=%s", resp)
+        if resp:
+            result = self._batt_parse_text(resp["text"])
+        return result
+
+    async def getDeviceName(self, url: str):
+        """
+        Returns the device name as provided by the manufacturer.
+        E.g. Samsung sets that as 'Samsung SM-J320FN' for a Galaxy J3.
+        """
+        target = f"{url}?action=getDeviceName"
+        resp = await self.get(target)
+        self._log.debug("getDeviceName resp=%s", resp)
+        device_name = None
+        if resp:
+            device_name = resp["text"]
+        return device_name
+
+    async def get(self, url: str):
+        """
+        Returns an object containing the raw HTTP response from GETting the provided url plus the got text content.
+        Uses async I/O to avoid blocking the main event loop.
+        Throw an exception in case of an error.
+        """
+        resp = None
+        result = None
+        try:
+            resp = await self._session.get(url)
+        except HTTPError as e:
+            self._log.error("HTTPError exception: %s", e)
+            return False
+        if resp:
+            text = await resp.text()
+            result = {"text": text, "resp": resp}
+        return result

pyjpi-0.1.13.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pyJPI
+Version: 0.1.13
+Summary: A library to access Android devices which run JPI
+Author-email: Pierre Wieser <p.wieser@trychlos.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/trychlos/pyjpi
+Project-URL: Issues, https://github.com/trychlos/pyjpi/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pyJPI - An asynchronous Python module to interact with Android devices running JPI
+
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/trychlos/pyjpi)
+[![Latest release](https://github.com/trychlos/pyjpi/workflows/Latest%20release/badge.svg)](https://github.com/trychlos/pyjpi/actions)
+[![Newest commit](https://github.com/trychlos/pyjpi/workflows/Latest%20commit/badge.svg)](https://github.com/trychlos/pyjpi/actions)
+
+[![PyPI version fury.io](https://badge.fury.io/py/pyjpi.svg)](https://pypi.python.org/pypi/pyjpi/)
+
+<!--
+[![CodeRabbit.ai is Awesome](https://img.shields.io/badge/AI-orange?label=CodeRabbit&color=orange&link=https%3A%2F%2Fcoderabbit.ai)](https://coderabbit.ai)
+[![renovate maintained](https://img.shields.io/badge/maintained%20with-renovate-blue?logo=renovatebot)](https://github.com/compatech/python-airos/issues/8)
+
+[![CodeFactor](https://www.codefactor.io/repository/github/compatech/python-airos/badge)](https://www.codefactor.io/repository/github/plugwise/python-airos)
+[![codecov](https://codecov.io/gh/compatech/python-airos/graph/badge.svg?token=WI5K2IZWNS)](https://codecov.io/gh/compatech/python-airos)
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=CoMPaTech_python-airos&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=CoMPaTech_python-airos)
+-->
+
+## Overview
+
+`pyJPI` is an asynchronous Python library designed to programmatically interact with Android devices running JPI.
+
+This library is a key component for a core integration with [Home Assistant](https://www.home-assistant.io).
+
+More details on the integration can be found on the [JPI](https://www.home-assistant.io/integrations/jpi/) page.
+
+## Features
+
+- Asynchronous operations are built with ``aiohttp` for non-blocking I/O, which is perfect for integrations and background tasks.
+- API: `battInfo`
+- API: `get`
+- API: `getDeviceName`
+
+## Installation
+
+You can install `pyJPI` from PyPI using pip:
+
+```Bash
+pip install pyjpi
+```
+
+## Usage
+
+Here is a more detailed example of how to use the library to connect, fetch status, and perform an action on an Android device running JPI.
+
+```Python
+import aiohttp
+from pyjpi import jpiInit
+
+async def main():
+    """Main function to demonstrate library usage."""
+    # Create an aiohttp session with SSL verification disabled.
+    # Be cautious with this setting; it's useful for self-signed certificates
+    # but not recommended for production environments without proper validation.
+    session = aiohttp.ClientSession( connector=aiohttp.TCPConnector( verify_ssl=False ))
+
+    # Get a handle on the pyJPI library.
+    handle = await jpiInit( session )
+
+    # Have an URL somewhere.
+    url = "http://myhost.example.com:8080"
+
+    # Then just has to call the library functions.
+    try:
+        res = await handle.get( url )
+        # returns a dict { resp: ClientResponse, text: str } or False
+        res = await handle.getDeviceName( url )
+        # returns the device name as set by the manufacturer (a single string) or False
+        res = await handle.battInfo( url )
+        # returns a dict { level: integer, charging: bool, power: bool }
+
+
+if __name__ == "__main__":
+    main()
+```
+
+## Available functions
+
+- `async jpiInit( session: aiohttp.ClientSession ) -> JPILibrary`:
+
+Initializes the library.
+
+Returns a handle on it.
+
+## Available classes
+
+- `JPILibrary`:
+
+The class which manages the devices accesses.
+
+## Available `JPILibrary` methods
+
+- `async get( url: str) -> dict`:
+
+Runs a HTTP GET method on the specified URL.
+
+Returns a dict with:
+
+```Python
+    resp: the `aiohttp.ClientResponse`
+    text: the resp.text() content
+```
+
+- `async getDeviceName( url: str) -> str`:
+
+Runs a HTTP GET method on f"{url}?action=getDeviceName" url.
+
+Returns a string which contains the device name as set by the manufacturer.
+
+- `async battInfo( url: str) -> dict`:
+
+Runs a HTTP GET method on on f"{url}?action=battInfo" url.
+
+Returns a dict with:
+
+```Python
+    level: an integer with the current battery level in %
+    charging: a boolean which says if the battery is currently charging
+    power: a boolean which says if the power is on on the device.
+```
+
+## Contributing
+
+We welcome contributions as well as additional codeowners to `pyjpi`.
+
+## Issues & help
+
+In case of support or error, please report your issue request to our [Issues tracker](https://github.com/trychlos/pyjpi/issues).

pyjpi-0.1.13.dist-info/RECORD

@@ -0,0 +1,7 @@
+pyjpi/__init__.py,sha256=psIA86RpUkgDEkN83iYyBg39kSyZ4ncKtHirmacfM3s,731
+pyjpi/library.py,sha256=w67KC7ky4oEfhxGvWLnsvDo2BM8bsa4gZZS1pHLDoLM,3158
+pyjpi-0.1.13.dist-info/licenses/LICENSE,sha256=R3qRa5L_mIKSS6sn0ZihAoffUJFYEHplpGizodZmYSU,1070
+pyjpi-0.1.13.dist-info/METADATA,sha256=RoXshzlJDCFjsBVXpj6reARZyi1UXJKis_QqZgDuG-I,5309
+pyjpi-0.1.13.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyjpi-0.1.13.dist-info/top_level.txt,sha256=jid62Fv2u4Pis12DgKx2kEUQc7OhHZbtbxcoFbG4NNU,6
+pyjpi-0.1.13.dist-info/RECORD,,

pyjpi-0.1.13.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyjpi-0.1.13.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 by @CoMPaTech
+
+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.

pyjpi-0.1.13.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyjpi