GeekMagicWeatherClockAPI 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

GeekMagicWeatherClockAPI/core.py

@@ -4,196 +4,251 @@ from urllib.parse import quote
 
 
 class SmallTV:
-    def __init__(self, ip: str):
+    """
+    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.THEMES = {
-            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",
+
+        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 upload(self, file_path, retries=3):
+    def _get(self, endpoint: str, **kwargs) -> dict:
         """
-        Upload a GIF/image to the SmallTV.
-        Retries on malformed header responses from SmallTV firmware.
+        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():
-            raise FileNotFoundError(file_path)
+            return self._build_result(
+                success=False,
+                error=f"File not found: {file_path}",
+            )
 
         filename = file_path.name
 
-        with open(file_path, "rb") as f:
-            gif_data = f.read()
+        try:
+            gif_data = file_path.read_bytes()
+        except OSError as exc:
+            return self._build_result(success=False, error=str(exc))
 
-        headers = {
-            "X-Requested-With": "XMLHttpRequest"
-        }
+        last_result: dict = {}
 
         for attempt in range(1, retries + 1):
-            # Delete any partial/failed upload before retrying
+            # Clean up any partial upload from a previous failed attempt.
             if attempt > 1:
-                print(f"Cleaning up failed upload, retrying... (attempt {attempt}/{retries})")
-                try:
-                    self.delete(filename)
-                except Exception:
-                    pass
+                self.delete(filename)
 
             files = {
                 "update": (filename, gif_data, "image/gif"),
                 "image": (filename, gif_data, "image/gif"),
             }
 
-            try:
-                r = requests.post(
-                    f"{self.base_url}/doUpload?dir=/image/",
-                    files=files,
-                    headers=headers,
-                    timeout=30
-                )
-                print("Upload Status:", r.status_code)
-                return True
-
-            except requests.exceptions.InvalidHeader:
-                print(f"Upload failed (malformed headers from SmallTV firmware) — attempt {attempt}/{retries}")
-                if attempt == retries:
-                    try:
-                        self.delete(filename)
-                    except Exception:
-                        pass
-                    raise RuntimeError(
-                        f"Upload of '{filename}' failed after {retries} attempts."
-                    )
+            result = self._post("/doUpload?dir=/image/", files=files)
+            last_result = result
 
-        return False
+            if result["success"]:
+                return result
 
-    def set_image(self, filename):
-        """
-        Set the currently displayed image.
-        """
+            # Only retry on malformed-header errors (firmware quirk).
+            if result.get("error") and "malformed" not in result["error"].lower():
+                return result
 
-        encoded_filename = quote(filename)
-
-        r = requests.get(
-            f"{self.base_url}/set?img=/image/{encoded_filename}",
-            timeout=10
+        # 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
 
-        print("Set Status:", r.status_code)
-
-        return r
-    
-    def set_theme(self, theme):
+    def set_image(self, filename: str) -> dict:
         """
-        Set the SmallTV theme.
-
-        Accepts:
-            1-7
-            or
-            "Weather Clock Today"
-            "Weather Forecast"
-            "Photo Album"
-            "Time Style 1"
-            "Time Style 2"
-            "Time Style 3"
-            "Simple Weather Clock"
+        Set the currently displayed image on the device.
         """
+        encoded = quote(filename)
+        return self._get(f"/set?img=/image/{encoded}")
 
-        if isinstance(theme, str):
-            theme_lookup = {
-                v.lower(): k
-                for k, v in self.THEMES.items()
-            }
+    def set_theme(self, theme) -> dict:
+        """
+        Set the active SmallTV theme.
 
-            theme_id = theme_lookup.get(theme.lower())
+        *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:
-                raise ValueError(
-                    f"Unknown theme '{theme}'"
+                return self._build_result(
+                    success=False,
+                    error=f"Unknown theme '{theme}'. Valid themes: {list(self.THEMES.values())}",
                 )
         else:
-            theme_id = int(theme)
+            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:
-            raise ValueError(
-                f"Theme must be between 1 and 7"
+            return self._build_result(
+                success=False,
+                error=f"Theme ID must be between 1 and 7, got {theme_id}.",
             )
 
-        r = requests.get(
-            f"{self.base_url}/set?theme={theme_id}",
-            timeout=10
-        )
-
-        print(
-            f"Theme set to {theme_id}: "
-            f"{self.THEMES[theme_id]}"
-        )
-        print("Status:", r.status_code)
+        return self._get(f"/set?theme={theme_id}")
 
-        return r
-    
-    def set_brightness(self, value):
+    def set_brightness(self, value) -> dict:
         """
-        Set SmallTV brightness (0–100).
+        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}.",
+            )
 
-        value = int(value)
-
-        if value < 0 or value > 100:
-            raise ValueError("Brightness must be between 0 and 100")
-
-        r = requests.get(
-            f"{self.base_url}/set?brt={value}",
-            timeout=10
-        )
-
-        print(f"Brightness set to {value}")
-        print("Status:", r.status_code)
-
-        return r
+        return self._get(f"/set?brt={value}")
 
-    def delete(self, filename):
+    def delete(self, filename: str) -> dict:
         """
-        Delete an image from the SmallTV.
+        Delete an image from the device.
         """
+        encoded = quote(filename)
+        return self._get(f"/delete?file=/image/{encoded}")
 
-        encoded_filename = quote(filename)
-
-        r = requests.get(
-            f"{self.base_url}/delete?file=/image/{encoded_filename}",
-            timeout=10
-        )
-
-        print("Delete Status:", r.status_code)
-
-        return r
-
-    def upload_and_set(self, file_path):
+    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)
 
-        self.upload(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, new_file):
+    def replace(self, old_filename: str, new_file) -> dict:
         """
-        Delete an old image, upload a new one, and display it.
-        """
-
-        try:
-            self.delete(old_filename)
-        except Exception:
-            pass
+        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.dist-info/METADATA

@@ -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/*`.

geekmagicweatherclockapi-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+GeekMagicWeatherClockAPI/__init__.py,sha256=sIM2Yj7PGpD0r8SrPGvoboz_USBJww7bQB-71qM7ZBc,49
+GeekMagicWeatherClockAPI/core.py,sha256=FsMzJKNj3_r2nyGt82oV2LDKe9tu0w3Rw5Qamitq0Eg,8449
+geekmagicweatherclockapi-0.1.1.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
+geekmagicweatherclockapi-0.1.1.dist-info/METADATA,sha256=25p8KkZuC8V6Qvi3GhFQOl0917B6yQQ0IQR3EfxkQwQ,5935
+geekmagicweatherclockapi-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+geekmagicweatherclockapi-0.1.1.dist-info/top_level.txt,sha256=3viXouZ_1SkVcqd-ChcYP3Nj1AoIoa2xFxm_XfsbPGQ,25
+geekmagicweatherclockapi-0.1.1.dist-info/RECORD,,

geekmagicweatherclockapi-0.1.0.dist-info/METADATA

@@ -1,125 +0,0 @@
-Metadata-Version: 2.4
-Name: GeekMagicWeatherClockAPI
-Version: 0.1.0
-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 simple 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.
-
----
-
-## Installation
-
-```bash
-pip install GeekMagicWeatherClockAPI
-```
-
-## Requirements
-
-- Python 3.7+
-- [`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")
-```
-
----
-
-## Usage
-
-### Upload an image
-
-```python
-tv.upload("my_animation.gif")
-tv.upload("my_animation.gif", retries=5)  # Custom retry count
-```
-
-### 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
-
-```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 |
-
----
-
-## Full Example
-
-```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")
-tv.replace("spaceman.gif", "new_image.gif")
-tv.delete("new_image.gif")
-```
-
----
-
-## Notes
-
-- The SmallTV firmware occasionally returns malformed `Content-Length` headers on upload responses. The `upload` method treats this as a failure and retries automatically.
-- All methods can raise `requests.exceptions.ConnectionError` if the device is unreachable.
-- File management methods operate on the `/image/` directory on the device.

geekmagicweatherclockapi-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-GeekMagicWeatherClockAPI/__init__.py,sha256=sIM2Yj7PGpD0r8SrPGvoboz_USBJww7bQB-71qM7ZBc,49
-GeekMagicWeatherClockAPI/core.py,sha256=FdqOxePm5qN2xBwQ9iEpfRBtHXj7cJ_rnUvGbmeg7i8,5269
-geekmagicweatherclockapi-0.1.0.dist-info/licenses/LICENSE,sha256=Btzdu2kIoMbdSp6OyCLupB1aRgpTCJ_szMimgEnpkkE,1056
-geekmagicweatherclockapi-0.1.0.dist-info/METADATA,sha256=ZcW-myU1Gjf9_o6svNkow4z3GInKWe-9nr_PEe_fCak,2704
-geekmagicweatherclockapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-geekmagicweatherclockapi-0.1.0.dist-info/top_level.txt,sha256=3viXouZ_1SkVcqd-ChcYP3Nj1AoIoa2xFxm_XfsbPGQ,25
-geekmagicweatherclockapi-0.1.0.dist-info/RECORD,,