PyNetioConf 0.3.0b1__tar.gz

pynetioconf-0.3.0b1/LICENSE

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

pynetioconf-0.3.0b1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: PyNetioConf
+Version: 0.3.0b1
+Summary: Universal module to control and configure all NETIO devices
+Keywords: NETIO
+Author: NETIO products a.s.
+Author-email: NETIO products a.s. <support@netio.eu>
+License-Expression: MIT
+License-File: 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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Development Status :: 4 - Beta
+Requires-Dist: websocket-client
+Requires-Dist: requests
+Requires-Dist: urllib3
+Requires-Dist: typing-extensions>=4.4.0 ; python_full_version < '3.12'
+Maintainer: Jakub Šperl
+Maintainer-email: Jakub Šperl <jsperl@netio.eu>
+Requires-Python: >=3.10
+Project-URL: Homepage, https://netio-products.com/
+Project-URL: Repository, https://github.com/netioproducts/PyNetioConf
+Project-URL: Issues, https://github.com/netioproducts/PyNetioConf/issues
+Project-URL: Changelog, https://github.com/netioproducts/PyNetioConf/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# PyNetioConf
+
+A Python module for configuring, controlling and monitoring NETIO devices with a unified API no matter which device
+or firmware version you're using.
+
+## Warning
+
+This module is currently under development and is not ready for production use. There might be breaking changes
+happening with relative frequency until the official release. The module is tested internally and should work
+correctly, but should still be considered beta release.
+
+Currently, the module supports control and many configuration options on ESP devices running the 2.x.x through 5.x.x
+firmware versions.  
+NOTE: Even though this library uses an API that supports older firmware versions such as 3.2.6, they are no longer
+supported as firmware versions and any bugs on deprecated firmware versions won't be fixed.
+
+## Installation
+
+### Git
+
+- Clone this repository and install the module from the cloned folder:
+
+```bash
+git clone https://github.com/netioproducts/PyNetioConf.git
+cd PyNetioConf
+
+# with uv: creates a .venv in the project folder and installs the module into it in editable mode
+uv sync
+
+# or with pip: if you can't or don't want to install site-wide packages, create a virtual environment first
+python3 -m venv pnc_venv
+source pnc_venv/bin/activate
+pip3 install -e .
+```
+
+- To update, run `git pull` in the `PyNetioConf` directory. Since the package is installed in editable mode, the
+  changes are picked up straight away, but to be sure you can rerun `uv sync` (or `pip3 install -e .`).
+
+### Manual
+
+- Alternatively if you don't have git installed, you can download the code as a ZIP file from GitHub by clicking the
+  green "Code" button.
+- After downloading the code, extract it to a directory and open that location in the terminal.
+- Once in the target directory run `uv sync`, or `pip3 install -e .` if you use pip.
+    - With pip, if this produces an error or you wish to keep site-wide packages separate, create a virtual
+      environment first: `python3 -m venv pnc_venv && source pnc_venv/bin/activate` then run `pip3 install -e .`
+
+### PyPI
+
+```bash
+# with uv
+uv add PyNetioConf
+
+# or with pip
+pip install PyNetioConf
+```
+
+While only beta versions are published, this installs the latest beta. Once a stable version is released,
+installers will prefer it, and betas will need to be requested explicitly with
+`uv add --prerelease=allow PyNetioConf` or `pip install --pre PyNetioConf`.
+
+## Usage
+
+### Development
+
+- After installing the pip package, you can easily use the library in your projects. To start off, you need to
+  connect to the device, for that you need to create a `NetioManager` class instance which will handle any devices
+  you connect to and their user sessions.
+
+```python
+from PyNetioConf import NetioManager
+
+nm = NetioManager()
+# The NetioManager instance handles all the devices and their sessions, preventing any session crowding and 
+# collisions in case of multiple device instances
+
+device = nm.init_device("powerpdu-8qs.netio-products.com", "demo", "demo")
+
+# You can now control and configure the device using its class methods
+# To check all the available methods check the NETIODevice class documentation.
+device.set_output(1, False)
+
+# While some cases should be universally available on all device versions, some featuers require
+# certain firmware versions or user permissions, to be sure consult the NETIODevice class documentation.*
+
+# To avoid any problems, encapsulate your logic in a try/except block
+from PyNetioConf.exceptions import FeatureNotSupported
+
+try:
+    # MQTT certificate auth is only available on version 5.0.x or later
+    device.upload_mqtt_ca_certificate("certificate_string")
+except FeatureNotSupported as e:
+    print("Device doesn't support MQTT cert authentication.")
+
+# or
+
+try:
+    device.set_output(1, True)
+except PermissionError as e:
+    print("Logged in account doesn't have permissions to alter output states.")
+```
+
+_Note: Currently the firmware version and permission requirements might be missing and will be added over time. In
+the meantime please check method implementations for your specific version in `esp_xxx_device.py` files_.
+
+- To see sample usage of the package functions see: `examples/*`
+
+### Using pre-made scripts
+
+- This repository contains some common usage scenarios as pre-made example scripts, if you are only looking for
+  specific use-case and don't intend to develop using this library this section goes over the usage of those scripts.
+- All the pre-made scripts are located in `./examples/` and to use them you will need to have
+  installed the library as described in the Installation section of the readme.
+- Once you have the library installed you can choose whichever script you want to use and open the file in any text
+  editor.
+- In the editor you change any necessary constants (variables in UPPER_CASE) such as: `USERNAME` and `PASSWORD`
+- For this example let's say I want to update the firmware using the `update_firmware.py` script:
+    - First I follow the comments in the file and set all my constants to the ones of my device.
+    - ```python
+      DEVICE_IP = "192.168.1.17"
+      USERNAME = "admin"
+      PASSWORD = "admin"
+      FIRMWARE_PATH = "/home/user/Downloads/release503.package"
+    - Then I run the file with python from the `PyNetioConf` directory: `python3 examples/update_firmware.py`
+      (with uv, run it as `uv run examples/update_firmware.py`)
+    - If I did all the steps correctly I should see an output simillar to the following:
+    - ```
+      TODO
+    - To use any of the other scripts, follow the comments in the file for instructions and then run it the same way
+      as this script.
+
+## Documentation
+
+Documentation is currently provided for functions as docstrings in the source code. Different forms of documentation
+are being worked on and will be provided as the library matures.
+
+## Issues and Suggestions
+
+If you find a bug or an issue, or have a suggestion, please use the GitHub issue tracker and create a new issue, before
+doing so, check if your issue isn't listed already. If reporting a bug please turn on logging DEBUG level and include
+the output in the report.

pynetioconf-0.3.0b1/README.md

@@ -0,0 +1,141 @@
+# PyNetioConf
+
+A Python module for configuring, controlling and monitoring NETIO devices with a unified API no matter which device
+or firmware version you're using.
+
+## Warning
+
+This module is currently under development and is not ready for production use. There might be breaking changes
+happening with relative frequency until the official release. The module is tested internally and should work
+correctly, but should still be considered beta release.
+
+Currently, the module supports control and many configuration options on ESP devices running the 2.x.x through 5.x.x
+firmware versions.  
+NOTE: Even though this library uses an API that supports older firmware versions such as 3.2.6, they are no longer
+supported as firmware versions and any bugs on deprecated firmware versions won't be fixed.
+
+## Installation
+
+### Git
+
+- Clone this repository and install the module from the cloned folder:
+
+```bash
+git clone https://github.com/netioproducts/PyNetioConf.git
+cd PyNetioConf
+
+# with uv: creates a .venv in the project folder and installs the module into it in editable mode
+uv sync
+
+# or with pip: if you can't or don't want to install site-wide packages, create a virtual environment first
+python3 -m venv pnc_venv
+source pnc_venv/bin/activate
+pip3 install -e .
+```
+
+- To update, run `git pull` in the `PyNetioConf` directory. Since the package is installed in editable mode, the
+  changes are picked up straight away, but to be sure you can rerun `uv sync` (or `pip3 install -e .`).
+
+### Manual
+
+- Alternatively if you don't have git installed, you can download the code as a ZIP file from GitHub by clicking the
+  green "Code" button.
+- After downloading the code, extract it to a directory and open that location in the terminal.
+- Once in the target directory run `uv sync`, or `pip3 install -e .` if you use pip.
+    - With pip, if this produces an error or you wish to keep site-wide packages separate, create a virtual
+      environment first: `python3 -m venv pnc_venv && source pnc_venv/bin/activate` then run `pip3 install -e .`
+
+### PyPI
+
+```bash
+# with uv
+uv add PyNetioConf
+
+# or with pip
+pip install PyNetioConf
+```
+
+While only beta versions are published, this installs the latest beta. Once a stable version is released,
+installers will prefer it, and betas will need to be requested explicitly with
+`uv add --prerelease=allow PyNetioConf` or `pip install --pre PyNetioConf`.
+
+## Usage
+
+### Development
+
+- After installing the pip package, you can easily use the library in your projects. To start off, you need to
+  connect to the device, for that you need to create a `NetioManager` class instance which will handle any devices
+  you connect to and their user sessions.
+
+```python
+from PyNetioConf import NetioManager
+
+nm = NetioManager()
+# The NetioManager instance handles all the devices and their sessions, preventing any session crowding and 
+# collisions in case of multiple device instances
+
+device = nm.init_device("powerpdu-8qs.netio-products.com", "demo", "demo")
+
+# You can now control and configure the device using its class methods
+# To check all the available methods check the NETIODevice class documentation.
+device.set_output(1, False)
+
+# While some cases should be universally available on all device versions, some featuers require
+# certain firmware versions or user permissions, to be sure consult the NETIODevice class documentation.*
+
+# To avoid any problems, encapsulate your logic in a try/except block
+from PyNetioConf.exceptions import FeatureNotSupported
+
+try:
+    # MQTT certificate auth is only available on version 5.0.x or later
+    device.upload_mqtt_ca_certificate("certificate_string")
+except FeatureNotSupported as e:
+    print("Device doesn't support MQTT cert authentication.")
+
+# or
+
+try:
+    device.set_output(1, True)
+except PermissionError as e:
+    print("Logged in account doesn't have permissions to alter output states.")
+```
+
+_Note: Currently the firmware version and permission requirements might be missing and will be added over time. In
+the meantime please check method implementations for your specific version in `esp_xxx_device.py` files_.
+
+- To see sample usage of the package functions see: `examples/*`
+
+### Using pre-made scripts
+
+- This repository contains some common usage scenarios as pre-made example scripts, if you are only looking for
+  specific use-case and don't intend to develop using this library this section goes over the usage of those scripts.
+- All the pre-made scripts are located in `./examples/` and to use them you will need to have
+  installed the library as described in the Installation section of the readme.
+- Once you have the library installed you can choose whichever script you want to use and open the file in any text
+  editor.
+- In the editor you change any necessary constants (variables in UPPER_CASE) such as: `USERNAME` and `PASSWORD`
+- For this example let's say I want to update the firmware using the `update_firmware.py` script:
+    - First I follow the comments in the file and set all my constants to the ones of my device.
+    - ```python
+      DEVICE_IP = "192.168.1.17"
+      USERNAME = "admin"
+      PASSWORD = "admin"
+      FIRMWARE_PATH = "/home/user/Downloads/release503.package"
+    - Then I run the file with python from the `PyNetioConf` directory: `python3 examples/update_firmware.py`
+      (with uv, run it as `uv run examples/update_firmware.py`)
+    - If I did all the steps correctly I should see an output simillar to the following:
+    - ```
+      TODO
+    - To use any of the other scripts, follow the comments in the file for instructions and then run it the same way
+      as this script.
+
+## Documentation
+
+Documentation is currently provided for functions as docstrings in the source code. Different forms of documentation
+are being worked on and will be provided as the library matures.
+
+## Issues and Suggestions
+
+If you find a bug or an issue, or have a suggestion, please use the GitHub issue tracker and create a new issue, before
+doing so, check if your issue isn't listed already. If reporting a bug please turn on logging DEBUG level and include
+the output in the report.

pynetioconf-0.3.0b1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "PyNetioConf"
+version = "0.3.0b1"
+requires-python = ">= 3.10"
+description = "Universal module to control and configure all NETIO devices"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["NETIO"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Development Status :: 4 - Beta",
+]
+dependencies = [
+    "websocket-client",
+    "requests",
+    "urllib3",
+    "typing-extensions>=4.4.0; python_version < '3.12'",
+]
+
+[[project.authors]]
+name = "NETIO products a.s."
+email = "support@netio.eu"
+
+[[project.maintainers]]
+name = "Jakub Šperl"
+email = "jsperl@netio.eu"
+
+[project.urls]
+Homepage = "https://netio-products.com/"
+Repository = "https://github.com/netioproducts/PyNetioConf"
+Issues = "https://github.com/netioproducts/PyNetioConf/issues"
+Changelog = "https://github.com/netioproducts/PyNetioConf/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "PyNetioConf"
+source-exclude = [
+    ".venv",
+    "devhelpers",
+]

pynetioconf-0.3.0b1/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[project]
+name = "PyNetioConf"
+version = "0.3.0b1"
+requires-python = ">= 3.10"
+authors = [
+    { name = "NETIO products a.s.", email = "support@netio.eu" }
+]
+maintainers = [
+    { name = "Jakub Šperl", email = "jsperl@netio.eu" }
+]
+
+description = "Universal module to control and configure all NETIO devices"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["NETIO"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Development Status :: 4 - Beta",
+]
+
+dependencies = [
+    "websocket-client",
+    "requests",
+    "urllib3",
+    "typing-extensions>=4.4.0; python_version < '3.12'"
+]
+
+[project.urls]
+Homepage = "https://netio-products.com/"
+Repository = "https://github.com/netioproducts/PyNetioConf"
+Issues = "https://github.com/netioproducts/PyNetioConf/issues"
+Changelog = "https://github.com/netioproducts/PyNetioConf/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "PyNetioConf"
+# uv_build does not read .gitignore; keep local-only folders out of builds made outside CI.
+source-exclude = [".venv", "devhelpers"]

pynetioconf-0.3.0b1/src/PyNetioConf/ESPCore/__init__.py

@@ -0,0 +1,5 @@
+# from .esp_200_device import ESP200Device
+# from .esp_300_device import ESP300Device
+# from .esp_400_device import ESP400Device
+# from .esp_500_device import ESP500Device
+# from .esp_device import ESPDevice

pynetioconf-0.3.0b1/src/PyNetioConf/ESPCore/esp_200_device.py

@@ -0,0 +1,16 @@
+"""
+Implementation specifics for ESP devices with the firmware 2.x.x.
+"""
+from .esp_device import ESPDevice
+from .. import NetioManager
+
+
+class ESP200Device(ESPDevice):
+    """
+    A class to control ESP devices with the firmware 2.x.x.
+    """
+
+    def __init__(self, host: str, username: str, password: str, sn_number: str, hostname: str, keep_alive: bool =
+    True, netio_manager: NetioManager | None = None, use_https: bool = False):
+        super().__init__(host, username, password, sn_number, hostname, keep_alive, netio_manager, use_https)
+        self.fw_version = self.get_version()

pynetioconf-0.3.0b1/src/PyNetioConf/ESPCore/esp_300_device.py

@@ -0,0 +1,16 @@
+"""
+Implementation specifics for ESP devices with the firmware 3.x.x.
+"""
+from .esp_200_device import ESP200Device
+from .. import NetioManager
+
+
+class ESP300Device(ESP200Device):
+    """
+    A class to control ESP devices with the firmware 3.x.x.
+    """
+
+    def __init__(self, host: str, username: str, password: str, sn_number: str, hostname: str, keep_alive: bool =
+    True, netio_manager: NetioManager | None = None, use_https: bool = False):
+        super().__init__(host, username, password, sn_number, hostname, keep_alive, netio_manager, use_https)
+        self.fw_version = self.get_version()

pynetioconf-0.3.0b1/src/PyNetioConf/ESPCore/esp_400_device.py

@@ -0,0 +1,16 @@
+"""
+Implementation specifics for ESP devices with the firmware 4.0.x.
+"""
+from .esp_300_device import ESP300Device
+from .. import NetioManager
+
+
+class ESP400Device(ESP300Device):
+    """
+    A class to control ESP devices with the firmware 4.0.x.
+    """
+
+    def __init__(self, host: str, username: str, password: str, sn_number: str, hostname: str, keep_alive: bool =
+    True, netio_manager: NetioManager | None = None, use_https: bool = False):
+        super().__init__(host, username, password, sn_number, hostname, keep_alive, netio_manager, use_https)
+        self.fw_version = self.get_version()