cybertqdm 0.2.1__tar.gz

cybertqdm-0.2.1/LICENSE

@@ -0,0 +1,15 @@
+The MIT License (MIT)
+Copyright © 2026 David Zellhöfer
+
+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.

cybertqdm-0.2.1/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: cybertqdm
+Version: 0.2.1
+Summary: A wrapper around tqdm that displays progress on an e-ink display connected over USB
+Keywords: tqdm,progress bar,e-ink,e-paper,raspberry pi pico,micropython
+Author: David Zellhöfer
+Author-email: David Zellhöfer <david.zellhoefer@hwr-berlin.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: mpremote>=1.29.0
+Requires-Dist: pyserial>=3.5
+Requires-Dist: tqdm>=4.70.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# cybertqdm
+
+`cybertqdm` is a wrapper around [`tqdm`](https://pypi.org/project/tqdm/) that will also display on an external e-ink display connected via USB.
+
+It is called `cybertqdm` because it turns `tqdm` into a _cyber-physical system_ (Yes, that's an existing term, see the [Wikipedia](https://en.wikipedia.org/wiki/Cyber-physical_system)). It will show a process bar as illustrated below.
+
+![cybertqdm running on the e-ink display](https://8bit-inferno.de/_persistent/img/cybertqdm.gif))
+
+## Using `cybertqdm`
+
+As `cybertqdm` wraps [`tqdm`](https://pypi.org/project/tqdm/) it works exactly the same. As a result, normal `tqdm` output will be printed to the console accompanied by a progess bar on an external e-ink display.
+
+```python
+from cybertqdm import cybertqdm
+import time
+
+for _ in cybertqdm(60, desc="Loosing faith in humanity...", epaper_interval=10):
+        time.sleep(0.5)
+```
+
+Please note that the e-ink display will not update as fast as the `tqdm` console output. The refresh interval is controlled by `epaper_interval` (in seconds).
+
+If no e-ink display is available while using `cybertqdm`, a warning is displayed and normal `tqdm` operation is unaffected.
+
+## Installation
+
+In contrast to most other PyPi packages, `cybertqdm` is a _cyber-physical system_. Thus, you will have to satisfy certain hardware requirements and software requirements on your embedded device. 
+
+### Operating System Requirements
+
+`cybertqdm` has been tested with the following operating systems (OS):
+
+| OS  | Supported |
+|-------|-----|
+| Linux (Ubuntu) | ✔ |
+| macOS (27.2.x)    | ✔ |
+| Windows (11)    | ✔ |
+
+The package might work on other OS as well because it is implemented in pure Python.
+
+When using Linux, access to `/dev/ttyACM*` is often prohibited. Therefore, you must grant the appropriate permissions to the user running `cybertqm`:
+
+```
+sudo usermod -aG dialout $USER   # Debian/Ubuntu/Fedora
+```
+
+After a logout, `cybertqdm` should work as expected.
+
+### Hardware Requirements
+
+The current version of `cybertqdm` requires the following components:
+
+1. One [Raspberry Pi Pico 2](https://www.raspberrypi.com/products/raspberry-pi-pico-2/) with a (pre-)soldered header. A Pi Pico might also work but `cybertqdm` is only tested on a Pi Pico 2.
+2. One [Waveshare e-paper 2.13 inch display module](https://www.waveshare.com/wiki/Pico-ePaper-2.13) (250×122 pixels, black and white)
+3. One USB-Micro to whatever-you-need-USB __data__ cable
+
+### Hardware Setup
+
+You only have to follow these steps once if you don't change your Pico 2 setup afterwards. If you reconnect your Pico 2 it will work directly – on every computer that has `cybertqdm` installed.
+
+1. Install MicroPython on your Raspberry Pico 2 following the [official instructions](https://www.raspberrypi.com/documentation/microcontrollers/micropython.html).
+2. Copy the necessary files to your Raspberry Pico 2:
+   - All necessary files come bundled with the PyPi package. In order to retrieve them, run the following Python script:
+    
+    ```python
+        import cybertqdm as ctqdm
+        from cybertqdm.diagnostics import show_device_files
+        from importlib.resources import files
+
+        print("cybertqdm version: "+ ctqdm.__version__)
+        show_device_files()
+    ```
+   - The result should look similar to this sample output (assuming you are using [uv](https://github.com/astral-sh/uv) as a package manager):
+    ```python
+        cybertqdm version: 0.1.x
+        The following files need to be copied to the device:
+            .../.cache/uv/archive-v0/xQJrc_fVJrWXacY9/lib/python3.15/site-packages/cybertqdm/device/epd.py 
+            .../.cache/uv/archive-v0/xQJrc_fVJrWXacY9/lib/python3.15/site-packages/cybertqdm/device/main.py
+    ```
+    - Now copy the files to your Pico 2 using `mpremote` using the paths shown above:
+    ```
+        mpremote cp <your_path>main.py :main.py
+        mpremote cp <your_path>epd.py :epd.py
+    ```
+    - Then test the installation: `mpremote exec "import main"` which should print `init` etc. if everything worked correctly. You can close the running script by pressing Ctrl-C.
+    - Reset your Pico 2 using `mpremote reset` which also starts `main.py` automatically.
+    - To check wheter the communication with the Pico 2 works, run the following diagnosis which provides help to fix common issues:
+    ```python
+        from cybertqdm.diagnostics import run_checks
+
+        run_checks()
+    ```
+    - If everthing works as expected, the result will look like as shown below. Please note that the actual `/dev/` path depends on your operating system. Otherwise, diagnostics and tips to fix your problem will be output.
+    ```
+        Pico 2 detected at port: /dev/cu.usbmodem11101
+        Port opened.
+
+        Sending: 0/10 ... OK
+        Sending: 5/10 ... OK
+        Sending: 10/10 ... OK
+
+        Pico 2 works as expected.
+    ```

cybertqdm-0.2.1/README.md

@@ -0,0 +1,103 @@
+# cybertqdm
+
+`cybertqdm` is a wrapper around [`tqdm`](https://pypi.org/project/tqdm/) that will also display on an external e-ink display connected via USB.
+
+It is called `cybertqdm` because it turns `tqdm` into a _cyber-physical system_ (Yes, that's an existing term, see the [Wikipedia](https://en.wikipedia.org/wiki/Cyber-physical_system)). It will show a process bar as illustrated below.
+
+![cybertqdm running on the e-ink display](https://8bit-inferno.de/_persistent/img/cybertqdm.gif))
+
+## Using `cybertqdm`
+
+As `cybertqdm` wraps [`tqdm`](https://pypi.org/project/tqdm/) it works exactly the same. As a result, normal `tqdm` output will be printed to the console accompanied by a progess bar on an external e-ink display.
+
+```python
+from cybertqdm import cybertqdm
+import time
+
+for _ in cybertqdm(60, desc="Loosing faith in humanity...", epaper_interval=10):
+        time.sleep(0.5)
+```
+
+Please note that the e-ink display will not update as fast as the `tqdm` console output. The refresh interval is controlled by `epaper_interval` (in seconds).
+
+If no e-ink display is available while using `cybertqdm`, a warning is displayed and normal `tqdm` operation is unaffected.
+
+## Installation
+
+In contrast to most other PyPi packages, `cybertqdm` is a _cyber-physical system_. Thus, you will have to satisfy certain hardware requirements and software requirements on your embedded device. 
+
+### Operating System Requirements
+
+`cybertqdm` has been tested with the following operating systems (OS):
+
+| OS  | Supported |
+|-------|-----|
+| Linux (Ubuntu) | ✔ |
+| macOS (27.2.x)    | ✔ |
+| Windows (11)    | ✔ |
+
+The package might work on other OS as well because it is implemented in pure Python.
+
+When using Linux, access to `/dev/ttyACM*` is often prohibited. Therefore, you must grant the appropriate permissions to the user running `cybertqm`:
+
+```
+sudo usermod -aG dialout $USER   # Debian/Ubuntu/Fedora
+```
+
+After a logout, `cybertqdm` should work as expected.
+
+### Hardware Requirements
+
+The current version of `cybertqdm` requires the following components:
+
+1. One [Raspberry Pi Pico 2](https://www.raspberrypi.com/products/raspberry-pi-pico-2/) with a (pre-)soldered header. A Pi Pico might also work but `cybertqdm` is only tested on a Pi Pico 2.
+2. One [Waveshare e-paper 2.13 inch display module](https://www.waveshare.com/wiki/Pico-ePaper-2.13) (250×122 pixels, black and white)
+3. One USB-Micro to whatever-you-need-USB __data__ cable
+
+### Hardware Setup
+
+You only have to follow these steps once if you don't change your Pico 2 setup afterwards. If you reconnect your Pico 2 it will work directly – on every computer that has `cybertqdm` installed.
+
+1. Install MicroPython on your Raspberry Pico 2 following the [official instructions](https://www.raspberrypi.com/documentation/microcontrollers/micropython.html).
+2. Copy the necessary files to your Raspberry Pico 2:
+   - All necessary files come bundled with the PyPi package. In order to retrieve them, run the following Python script:
+    
+    ```python
+        import cybertqdm as ctqdm
+        from cybertqdm.diagnostics import show_device_files
+        from importlib.resources import files
+
+        print("cybertqdm version: "+ ctqdm.__version__)
+        show_device_files()
+    ```
+   - The result should look similar to this sample output (assuming you are using [uv](https://github.com/astral-sh/uv) as a package manager):
+    ```python
+        cybertqdm version: 0.1.x
+        The following files need to be copied to the device:
+            .../.cache/uv/archive-v0/xQJrc_fVJrWXacY9/lib/python3.15/site-packages/cybertqdm/device/epd.py 
+            .../.cache/uv/archive-v0/xQJrc_fVJrWXacY9/lib/python3.15/site-packages/cybertqdm/device/main.py
+    ```
+    - Now copy the files to your Pico 2 using `mpremote` using the paths shown above:
+    ```
+        mpremote cp <your_path>main.py :main.py
+        mpremote cp <your_path>epd.py :epd.py
+    ```
+    - Then test the installation: `mpremote exec "import main"` which should print `init` etc. if everything worked correctly. You can close the running script by pressing Ctrl-C.
+    - Reset your Pico 2 using `mpremote reset` which also starts `main.py` automatically.
+    - To check wheter the communication with the Pico 2 works, run the following diagnosis which provides help to fix common issues:
+    ```python
+        from cybertqdm.diagnostics import run_checks
+
+        run_checks()
+    ```
+    - If everthing works as expected, the result will look like as shown below. Please note that the actual `/dev/` path depends on your operating system. Otherwise, diagnostics and tips to fix your problem will be output.
+    ```
+        Pico 2 detected at port: /dev/cu.usbmodem11101
+        Port opened.
+
+        Sending: 0/10 ... OK
+        Sending: 5/10 ... OK
+        Sending: 10/10 ... OK
+
+        Pico 2 works as expected.
+    ```

cybertqdm-0.2.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "cybertqdm"
+version = "0.2.1"
+description = "A wrapper around tqdm that displays progress on an e-ink display connected over USB"
+keywords = [
+    "tqdm",
+    "progress bar",
+    "e-ink",
+    "e-paper",
+    "raspberry pi pico",
+    "micropython",
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "mpremote>=1.29.0",
+    "pyserial>=3.5",
+    "tqdm>=4.70.1",
+]
+
+[[project.authors]]
+name = "David Zellhöfer"
+email = "david.zellhoefer@hwr-berlin.de"
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-exclude = [
+    "patch_publish.sh",
+    "test_release.sh",
+]
+
+[[tool.uv.index]]
+name = "cybertqdm"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

cybertqdm-0.2.1/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "cybertqdm"
+version = "0.2.1"
+description = "A wrapper around tqdm that displays progress on an e-ink display connected over USB"
+keywords = ["tqdm", "progress bar", "e-ink", "e-paper", "raspberry pi pico", "micropython"]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "David Zellhöfer", email = "david.zellhoefer@hwr-berlin.de" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "mpremote>=1.29.0",
+    "pyserial>=3.5",
+    "tqdm>=4.70.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+source-exclude = ["patch_publish.sh","test_release.sh"]   # the build script shouldn't be included but we exclude it explicitly
+
+[[tool.uv.index]]
+name = "cybertqdm"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

cybertqdm-0.2.1/src/cybertqdm/__init__.py

@@ -0,0 +1,5 @@
+from .cybertqdm import cybertqdm, CyberTqdm
+from importlib.metadata import version
+
+__all__ = ["CyberTqdm", "cybertqdm"]
+__version__ = version("cybertqdm")

cybertqdm-0.2.1/src/cybertqdm/cybertqdm.py

@@ -0,0 +1,120 @@
+import glob
+import time
+import warnings
+
+import serial
+from serial.tools import list_ports
+from tqdm import tqdm
+
+__all__ = ["CyberTqdm", "cybertqdm"]
+
+PICO_VID = (
+    0x2E8A  # Raspberry Pi vendor ID; used to detect the device in macOS and Linux
+)
+
+
+def find_pico_ports():
+    """Check serial ports of connected Pico devices, should work on any OS."""
+    return sorted(p.device for p in list_ports.comports() if p.vid == PICO_VID)
+
+
+class CyberTqdm(tqdm):
+    """A tqdm wrapper that also prints a progres bar onto a e-ink display.
+
+    To prevent wearing down the e-ink display too fast, console and e-ink update interval differs.
+
+    - console: normal tqdm update interval
+    - e-ink display: updates at start, then every `epaper_interval` seconds with a final update when the observed task ends.
+    - If no Pico 2 is detected or the connection is lost, a warning is output. Console operation remains unaffected.
+    """
+
+    _ser = None  # common connection for progress bars
+    _unavailable = False  # in case of errors do not try to reconnect again and again...
+
+    def __init__(self, *args, port=None, epaper_interval=30, **kwargs):
+        self._epaper_interval = epaper_interval
+        self._last_send = 0.0
+        self._epaper_done = False
+        self._open_port(port)
+        super().__init__(*args, **kwargs)
+
+    # --- connection ---------------------------------------------------------
+    @staticmethod
+    def _open_port(port):
+        cls = CyberTqdm
+        if (cls._ser is not None and cls._ser.is_open) or cls._unavailable:
+            return
+        if port is None:
+            # ports = sorted(glob.glob("/dev/cu.usbmodem*")) # works only on macOS
+            ports = find_pico_ports()
+            if not ports:
+                cls._unavailable = True
+                warnings.warn(
+                    "E-ink display unavailable – falling back to console output."
+                )
+                return
+            port = ports[0]
+        try:
+            cls._ser = serial.Serial(port, 115200, timeout=0, write_timeout=2)
+        except (serial.SerialException, OSError) as e:
+            cls._unavailable = True
+            warnings.warn(
+                f"E-ink display unavailable ({e}) – falling back to console output."
+            )
+
+    @staticmethod
+    def _drop_port(err):
+        cls = CyberTqdm
+        warnings.warn(
+            f"Lost connection to e-ink display ({err}) – falling back to console output."
+        )
+        try:
+            cls._ser.close()
+        except Exception:
+            pass
+        cls._ser = None
+        cls._unavailable = True
+
+    # --- send data -------------------------------------------------------------
+    def _send(self):
+        ser = CyberTqdm._ser
+        if ser is None or self.disable:
+            return
+        try:
+            if ser.in_waiting:  # drop OK/busy messages from the Pico 2
+                ser.read(ser.in_waiting)
+            d = self.format_dict
+            desc = (
+                (self.desc or "").replace("|", "/").replace("\n", " ").strip(": ")[:30]
+            )
+            n = int(d["n"])
+            total = int(d["total"] or 0)
+            rate = d["rate"] or 0.0
+            ser.write(f"{desc}|{n}|{total}|{rate:.2f}\n".encode())
+            ser.flush()
+        except (serial.SerialException, OSError) as e:
+            self._drop_port(e)
+        self._last_send = time.time()
+
+    # --- tqdm hooks ---------------------------------------------------------
+    def display(self, msg=None, pos=None):
+        if time.time() - self._last_send >= self._epaper_interval:
+            self._send()
+        return super().display(msg, pos)
+
+    def close(self):
+        if not getattr(self, "_epaper_done", True):
+            self._epaper_done = True
+            self._send()  # always display final state of the progress bar
+        super().close()
+
+
+def cybertqdm(*args, **kwargs):
+    """Shortcut for CyberTqdm(range(*args), **kwargs)."""
+    return CyberTqdm(range(*args), **kwargs)
+
+
+if __name__ == "__main__":
+    # quick test: 60 steps, each sleeping for 0.5 seconds, e-ink display update every 10 seconds
+    for _ in cybertqdm(60, desc="Loosing faith in humanity...", epaper_interval=10):
+        time.sleep(0.5)