GeekMagicWeatherClockAPI 0.1.0__tar.gz → 0.1.1__tar.gz

geekmagicweatherclockapi-0.1.1/GeekMagicWeatherClockAPI/core.py

@@ -0,0 +1,254 @@
+import requests
+from pathlib import Path
+from urllib.parse import quote
+
+
+class SmallTV:
+    """
+    HTTP client for controlling a GeekMagic SmallTV device.
+
+    All public methods return a standardized response dictionary::
+
+        {
+            "success":     bool,
+            "status_code": int | None,
+            "response":    str | None,
+            "error":       str | None,
+        }
+    """
+
+    THEMES: dict[int, str] = {
+        1: "Weather Clock Today",
+        2: "Weather Forecast",
+        3: "Photo Album",
+        4: "Time Style 1",
+        5: "Time Style 2",
+        6: "Time Style 3",
+        7: "Simple Weather Clock",
+    }
+
+    _THEME_LOOKUP: dict[str, int] = {}  # populated lazily in __init__
+
+    def __init__(self, ip: str) -> None:
+        self.ip = ip
+        self.base_url = f"http://{ip}"
+
+        self._THEME_LOOKUP = {v.lower(): k for k, v in self.THEMES.items()}
+
+        self.session = requests.Session()
+        self.session.headers.update({"X-Requested-With": "XMLHttpRequest"})
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _build_result(
+        success: bool,
+        status_code: int | None = None,
+        response: str | None = None,
+        error: str | None = None,
+    ) -> dict:
+        return {
+            "success": success,
+            "status_code": status_code,
+            "response": response,
+            "error": error,
+        }
+
+    def _get(self, endpoint: str, **kwargs) -> dict:
+        """
+        Perform a GET request against *endpoint* (relative path + query string).
+
+        Extra *kwargs* are forwarded to ``session.get()``.
+        """
+        url = f"{self.base_url}{endpoint}"
+        kwargs.setdefault("timeout", 10)
+
+        try:
+            r = self.session.get(url, **kwargs)
+            return self._build_result(
+                success=r.ok,
+                status_code=r.status_code,
+                response=r.text,
+            )
+        except requests.RequestException as exc:
+            return self._build_result(success=False, error=str(exc))
+        except Exception as exc:
+            return self._build_result(success=False, error=f"Unexpected error: {exc}")
+
+    def _post(self, endpoint: str, **kwargs) -> dict:
+        """
+        Perform a POST request against *endpoint* (relative path + query string).
+
+        Extra *kwargs* are forwarded to ``session.post()``.
+        """
+        url = f"{self.base_url}{endpoint}"
+        kwargs.setdefault("timeout", 30)
+
+        try:
+            r = self.session.post(url, **kwargs)
+            return self._build_result(
+                success=r.ok,
+                status_code=r.status_code,
+                response=r.text,
+            )
+        except requests.exceptions.InvalidHeader as exc:
+            # SmallTV firmware occasionally returns malformed response headers.
+            return self._build_result(
+                success=False,
+                error=f"Malformed response headers from device: {exc}",
+            )
+        except requests.RequestException as exc:
+            return self._build_result(success=False, error=str(exc))
+        except Exception as exc:
+            return self._build_result(success=False, error=f"Unexpected error: {exc}")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def upload(self, file_path, retries: int = 3) -> dict:
+        """
+        Upload a GIF/image to the SmallTV.
+
+        Retries up to *retries* times to work around malformed-header
+        responses emitted by some SmallTV firmware versions.
+
+        Returns a standardized result dict.
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            return self._build_result(
+                success=False,
+                error=f"File not found: {file_path}",
+            )
+
+        filename = file_path.name
+
+        try:
+            gif_data = file_path.read_bytes()
+        except OSError as exc:
+            return self._build_result(success=False, error=str(exc))
+
+        last_result: dict = {}
+
+        for attempt in range(1, retries + 1):
+            # Clean up any partial upload from a previous failed attempt.
+            if attempt > 1:
+                self.delete(filename)
+
+            files = {
+                "update": (filename, gif_data, "image/gif"),
+                "image": (filename, gif_data, "image/gif"),
+            }
+
+            result = self._post("/doUpload?dir=/image/", files=files)
+            last_result = result
+
+            if result["success"]:
+                return result
+
+            # Only retry on malformed-header errors (firmware quirk).
+            if result.get("error") and "malformed" not in result["error"].lower():
+                return result
+
+        # All attempts exhausted — clean up and surface the last error.
+        self.delete(filename)
+        last_result["error"] = (
+            f"Upload of '{filename}' failed after {retries} attempt(s). "
+            f"Last error: {last_result.get('error')}"
+        )
+        return last_result
+
+    def set_image(self, filename: str) -> dict:
+        """
+        Set the currently displayed image on the device.
+        """
+        encoded = quote(filename)
+        return self._get(f"/set?img=/image/{encoded}")
+
+    def set_theme(self, theme) -> dict:
+        """
+        Set the active SmallTV theme.
+
+        *theme* may be an integer (1–7) or one of the theme name strings:
+
+        * ``"Weather Clock Today"``
+        * ``"Weather Forecast"``
+        * ``"Photo Album"``
+        * ``"Time Style 1"``
+        * ``"Time Style 2"``
+        * ``"Time Style 3"``
+        * ``"Simple Weather Clock"``
+        """
+        if isinstance(theme, str):
+            theme_id = self._THEME_LOOKUP.get(theme.lower())
+            if theme_id is None:
+                return self._build_result(
+                    success=False,
+                    error=f"Unknown theme '{theme}'. Valid themes: {list(self.THEMES.values())}",
+                )
+        else:
+            try:
+                theme_id = int(theme)
+            except (TypeError, ValueError) as exc:
+                return self._build_result(success=False, error=str(exc))
+
+        if theme_id not in self.THEMES:
+            return self._build_result(
+                success=False,
+                error=f"Theme ID must be between 1 and 7, got {theme_id}.",
+            )
+
+        return self._get(f"/set?theme={theme_id}")
+
+    def set_brightness(self, value) -> dict:
+        """
+        Set the display brightness (0–100).
+        """
+        try:
+            value = int(value)
+        except (TypeError, ValueError) as exc:
+            return self._build_result(success=False, error=str(exc))
+
+        if not 0 <= value <= 100:
+            return self._build_result(
+                success=False,
+                error=f"Brightness must be between 0 and 100, got {value}.",
+            )
+
+        return self._get(f"/set?brt={value}")
+
+    def delete(self, filename: str) -> dict:
+        """
+        Delete an image from the device.
+        """
+        encoded = quote(filename)
+        return self._get(f"/delete?file=/image/{encoded}")
+
+    def upload_and_set(self, file_path) -> dict:
+        """
+        Upload a file and immediately display it.
+
+        Returns the result of ``set_image`` on success, or the failed
+        ``upload`` result if the upload did not succeed.
+        """
+        file_path = Path(file_path)
+
+        upload_result = self.upload(file_path)
+        if not upload_result["success"]:
+            return upload_result
+
+        return self.set_image(file_path.name)
+
+    def replace(self, old_filename: str, new_file) -> dict:
+        """
+        Delete *old_filename*, upload *new_file*, and display it.
+
+        The delete step is best-effort; failure does not abort the operation.
+        Returns the result of ``upload_and_set``.
+        """
+        self.delete(old_filename)
+        return self.upload_and_set(new_file)

geekmagicweatherclockapi-0.1.1/GeekMagicWeatherClockAPI.egg-info/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: GeekMagicWeatherClockAPI
+Version: 0.1.1
+Summary: Python wrapper for controlling the GeekMagic SmallTV
+Project-URL: Homepage, https://github.com/eman225511/GeekMagicWeatherClockAPI
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# GeekMagicWeatherClockAPI
+
+A Python wrapper for controlling the **GeekMagic SmallTV** over your local network. Supports uploading images/GIFs, switching themes, adjusting brightness, and managing files on the device.
+
+[PyPI](https://pypi.org/project/GeekMagicWeatherClockAPI/)
+
+---
+
+## Installation
+
+```bash
+pip install GeekMagicWeatherClockAPI
+```
+
+## Requirements
+
+- Python 3.10+
+- [`requests`](https://pypi.org/project/requests/) (installed automatically)
+
+---
+
+## Setup
+
+Find your SmallTV's local IP address (check your router's device list or the SmallTV's settings menu), then:
+
+```python
+from GeekMagicWeatherClockAPI import SmallTV
+
+tv = SmallTV("192.168.1.85")
+```
+
+A persistent HTTP session is created automatically. All requests reuse this session, so there's no need to manage connections manually.
+
+---
+
+## Return values
+
+Every method returns the same dictionary — no exceptions are raised for network or validation errors:
+
+```python
+{
+    "success":     bool,       # True if the device responded successfully
+    "status_code": int | None, # HTTP status code, or None if the request never completed
+    "response":    str | None, # Raw response body from the device
+    "error":       str | None, # Human-readable error message on failure, else None
+}
+```
+
+### Checking results
+
+```python
+result = tv.set_brightness(50)
+
+if result["success"]:
+    print("Done!")
+else:
+    print("Something went wrong:", result["error"])
+```
+
+---
+
+## Usage
+
+### Upload an image
+
+```python
+tv.upload("my_animation.gif")
+
+# Increase retries for flaky firmware responses
+tv.upload("my_animation.gif", retries=5)
+```
+
+### Display an image
+
+```python
+tv.set_image("my_animation.gif")
+```
+
+### Upload and immediately display
+
+```python
+tv.upload_and_set("my_animation.gif")
+```
+
+### Replace an image
+
+Deletes the old file, uploads the new one, and displays it — all in one call.
+
+```python
+tv.replace("old_animation.gif", "new_animation.gif")
+```
+
+### Delete an image
+
+```python
+tv.delete("my_animation.gif")
+```
+
+### Set brightness
+
+Accepts a value from `0` to `100`.
+
+```python
+tv.set_brightness(75)
+```
+
+### Set theme
+
+Accepts either an integer (`1`–`7`) or the theme name as a string (case-insensitive).
+
+```python
+tv.set_theme(3)
+tv.set_theme("Photo Album")
+```
+
+| ID | Theme Name           |
+|----|----------------------|
+| 1  | Weather Clock Today  |
+| 2  | Weather Forecast     |
+| 3  | Photo Album          |
+| 4  | Time Style 1         |
+| 5  | Time Style 2         |
+| 6  | Time Style 3         |
+| 7  | Simple Weather Clock |
+
+---
+
+## Examples
+
+### Basic setup and display
+
+```python
+from GeekMagicWeatherClockAPI import SmallTV
+
+tv = SmallTV("192.168.1.85")
+
+tv.upload_and_set("spaceman.gif")
+tv.set_brightness(30)
+tv.set_theme("Weather Clock Today")
+```
+
+### Checking every result
+
+```python
+tv = SmallTV("192.168.1.85")
+
+for step, result in [
+    ("upload",     tv.upload("clock.gif")),
+    ("display",    tv.set_image("clock.gif")),
+    ("brightness", tv.set_brightness(60)),
+    ("theme",      tv.set_theme(1)),
+]:
+    status = "OK" if result["success"] else f"FAILED — {result['error']}"
+    print(f"{step:12} {status}")
+```
+
+### Batch upload a folder of GIFs
+
+```python
+from pathlib import Path
+
+tv = SmallTV("192.168.1.85")
+
+gifs = list(Path("./animations").glob("*.gif"))
+
+for gif in gifs:
+    result = tv.upload(gif)
+    if result["success"]:
+        print(f"Uploaded: {gif.name}")
+    else:
+        print(f"Failed:   {gif.name} — {result['error']}")
+```
+
+### Rotate through themes on a schedule
+
+```python
+import time
+
+tv = SmallTV("192.168.1.85")
+
+themes = list(tv.THEMES.keys())  # [1, 2, 3, 4, 5, 6, 7]
+
+for theme_id in themes:
+    result = tv.set_theme(theme_id)
+    if result["success"]:
+        print(f"Now showing: {tv.THEMES[theme_id]}")
+    time.sleep(10)
+```
+
+### Night mode — dim at a set hour
+
+```python
+from datetime import datetime
+
+tv = SmallTV("192.168.1.85")
+
+hour = datetime.now().hour
+brightness = 10 if 22 <= hour or hour < 7 else 80
+
+result = tv.set_brightness(brightness)
+print(f"Brightness set to {brightness}" if result["success"] else result["error"])
+```
+
+### Upload with retry and graceful fallback
+
+```python
+tv = SmallTV("192.168.1.85")
+
+result = tv.upload("hero.gif", retries=5)
+
+if result["success"]:
+    tv.set_image("hero.gif")
+else:
+    print("Upload failed after all retries:", result["error"])
+    # Fall back to a theme instead
+    tv.set_theme("Weather Clock Today")
+```
+
+### Swap a live image safely
+
+```python
+tv = SmallTV("192.168.1.85")
+
+# Removes "old.gif", uploads "new.gif", and displays it
+result = tv.replace("old.gif", "new.gif")
+
+if not result["success"]:
+    print("Replace failed:", result["error"])
+```
+
+---
+
+## Notes
+
+- The SmallTV firmware occasionally returns malformed `Content-Length` headers on upload responses. The `upload` method automatically retries and cleans up partial uploads when this happens.
+- All methods return a structured dict and never raise — check `result["success"]` instead of wrapping calls in `try/except`.
+- File management methods operate on the `/image/` directory on the device.
+- The `THEMES` dict is a public class attribute and can be read directly to enumerate valid theme names: `SmallTV.THEMES`.
+
+---
+
+> **Dev note:** on release, bump the version in `pyproject.toml` and run `python -m build` then `twine upload dist/*`.