zm-py 0.5.5.dev13__tar.gz → 0.5.6.dev1__tar.gz

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zm-py
-Version: 0.5.5.dev13
+Version: 0.5.6.dev1
 Summary: A loose python wrapper around the ZoneMinder REST API.
 License: Apache-2.0
 License-File: LICENSE.md
@@ -55,6 +55,18 @@ Historical sources and authorship information is available as part of the Home A
 - [ZoneMinder Sensor](https://github.com/home-assistant/home-assistant/commits/dev/homeassistant/components/sensor/zoneminder.py)
 - [ZoneMinder Switch](https://github.com/home-assistant/home-assistant/commits/dev/homeassistant/components/switch/zoneminder.py)
 
+## Documentation
+
+- **[API Reference](docs/api.md)** — all public classes, methods, properties, and enums
+- **[Architecture](docs/architecture.md)** — package structure, design patterns, caching strategy, Mermaid diagrams
+- Architecture diagrams:
+  - [Package architecture](docs/architecture-package-architecture.png)
+  - [Class relationships](docs/architecture-class-relationships.png)
+  - [Auth & request flow](docs/architecture-auth-amp-request-flow.png)
+  - [Multi-server URL routing](docs/architecture-multi-server-url-routing.png)
+  - [ZoneMinder API endpoints](docs/api-overview-zoneminder-api-endpoints.png)
+  - [Monitor state model](docs/api-overview-monitor-state-model.png)
+
 ## Installation
 
 ### PyPI
@@ -78,7 +90,9 @@ zm_client = ZoneMinder(
     server_path=SERVER_PATH,
     username=USER,
     password=PASS,
-    verify_ssl=False
+    verify_ssl=False,
+    stream_scale=50,       # optional: scale streams to 50%
+    stream_maxfps=5.0,     # optional: cap MJPEG at 5 FPS
 )
 
 # Zoneminder authentication

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/README.md

@@ -30,6 +30,18 @@ Historical sources and authorship information is available as part of the Home A
 - [ZoneMinder Sensor](https://github.com/home-assistant/home-assistant/commits/dev/homeassistant/components/sensor/zoneminder.py)
 - [ZoneMinder Switch](https://github.com/home-assistant/home-assistant/commits/dev/homeassistant/components/switch/zoneminder.py)
 
+## Documentation
+
+- **[API Reference](docs/api.md)** — all public classes, methods, properties, and enums
+- **[Architecture](docs/architecture.md)** — package structure, design patterns, caching strategy, Mermaid diagrams
+- Architecture diagrams:
+  - [Package architecture](docs/architecture-package-architecture.png)
+  - [Class relationships](docs/architecture-class-relationships.png)
+  - [Auth & request flow](docs/architecture-auth-amp-request-flow.png)
+  - [Multi-server URL routing](docs/architecture-multi-server-url-routing.png)
+  - [ZoneMinder API endpoints](docs/api-overview-zoneminder-api-endpoints.png)
+  - [Monitor state model](docs/api-overview-monitor-state-model.png)
+
 ## Installation
 
 ### PyPI
@@ -53,7 +65,9 @@ zm_client = ZoneMinder(
     server_path=SERVER_PATH,
     username=USER,
     password=PASS,
-    verify_ssl=False
+    verify_ssl=False,
+    stream_scale=50,       # optional: scale streams to 50%
+    stream_maxfps=5.0,     # optional: cap MJPEG at 5 FPS
 )
 
 # Zoneminder authentication

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zm-py"
-version = "0.5.5.dev13"
+version = "0.5.6.dev1"
 description = "A loose python wrapper around the ZoneMinder REST API."
 authors = ["Rohan Kapoor <rohan@rohankapoor.com>"]
 maintainers = ["Nic Boet <nic@boet.cc>"]

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/tests/README.md

@@ -87,6 +87,7 @@ ZM_E2E_WRITE=1 pytest -m zm_e2e_write tests/e2e/ -v
 | `test_run_state.py` | RunState construction, properties, `active` parsing, `activate` |
 | `test_enums.py` | `TimePeriod` (period/title/get_time_period), `MonitorState`, `ControlType` values |
 | `test_exceptions.py` | Exception hierarchy, `__str__` formatting |
+| `test_server.py` | Server construction, properties, ZMS URL building, base URL building |
 | `test_client.py` | `verify_ssl`, `is_available` parsing, `get_monitors`/`get_run_states`/`get_active_state` response handling, `move_monitor` exception swallowing |
 
 ## E2E Test Modules
@@ -98,7 +99,8 @@ ZM_E2E_WRITE=1 pytest -m zm_e2e_write tests/e2e/ -v
 | `test_e2e_states.py` | Run states listing, active state, state switching | `api/states.json`, `api/states/change/{name}.json` |
 | `test_e2e_availability.py` | Daemon check, get_state/change_state plumbing, ZMS URL, auth URL helpers | `api/host/daemonCheck.json`, `api/host/getVersion.json` |
 | `test_e2e_ptz.py` | PTZ control on controllable/non-controllable monitors | `index.php` (control view) |
-| `test_e2e_api_probes.py` | Raw API response inspection -- documents actual types/shapes from ZM 1.38.x to validate BUGS.md | All endpoints |
+| `test_e2e_servers.py` | Server listing, server URLs, monitor ServerId probe | `api/servers.json` |
+| `test_e2e_api_probes.py` | Raw API response inspection -- documents actual types/shapes from ZM 1.38.x to validate bugs | All endpoints |
 
 ## API Coverage
 
@@ -117,6 +119,7 @@ GET  api/states/change/{name}.json -> ZoneMinder.set_active_state() [write]
 GET  api/monitors/alarm/...        -> Monitor.is_recording
 GET  api/monitors/daemonStatus/... -> Monitor.is_available
 GET  api/events/consoleEvents/...  -> Monitor.get_events()
+GET  api/servers.json               -> ZoneMinder.get_servers()
 POST index.php (PTZ control)       -> Monitor.ptz_control_command() [write]
 ```
 
@@ -146,11 +149,6 @@ After the test run, a summary section is printed showing:
 - Test target monitors
 - Skip reasons and counts
 
-## Known Bugs
-
-See [BUGS.md](BUGS.md) for bugs discovered in zm-py during test development.
-These are **not fixed** -- they are documented to guide future refactoring.
-
 ## Comparison with Sister Projects
 
 This test suite follows the same E2E patterns established in:

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/tests/e2e/conftest.py

@@ -202,8 +202,8 @@ def raw_session(zm_client: ZoneMinder):
     s.verify = zm_client._verify_ssl
     if zm_client._auth_token:
         s.params = {"token": zm_client._auth_token}
-    elif zm_client._cookies:
-        s.cookies = zm_client._cookies
+    elif zm_client._session.cookies:
+        s.cookies = zm_client._session.cookies
     return s
 
 

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/tests/e2e/test_e2e_auth.py

@@ -27,7 +27,7 @@ class TestLogin:
         """After login(), the client should have an auth token or cookies."""
         zm_client_fresh.login()
         has_token = zm_client_fresh._auth_token is not None
-        has_cookies = zm_client_fresh._cookies is not None
+        has_cookies = len(zm_client_fresh._session.cookies) > 0
         assert has_token or has_cookies, (
             "Expected either JWT token or session cookies after login"
         )

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/tests/test_client.py

@@ -331,6 +331,118 @@ class TestMoveMonitor:
         c._session.post.assert_called_once()
 
 
+# ---------------------------------------------------------------------------
+# goto_preset
+# ---------------------------------------------------------------------------
+
+class TestGotoPreset:
+    def _make_monitor(self, controllable=True):
+        raw = _monitor_raw(controllable="1" if controllable else "0")
+        return Monitor(_client(), raw)
+
+    def test_delegates_to_preset_command(self):
+        c = _client()
+        c._auth_token = "test-token"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        c.goto_preset(mon, 3)
+        c._session.post.assert_called_once()
+
+    def test_preset_params_contain_preset_number(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        c.goto_preset(mon, 3)
+        call_kwargs = c._session.post.call_args
+        assert call_kwargs.kwargs["params"]["control"] == "presetGoto3"
+
+    def test_raises_on_non_controllable(self):
+        c = _client()
+        c._auth_token = "tok"
+        mon = self._make_monitor(controllable=False)
+        with pytest.raises(MonitorControlTypeError):
+            c.goto_preset(mon, 1)
+
+    def test_returns_bool_on_success(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        result = c.goto_preset(mon, 5)
+        assert result is True
+
+    def test_returns_false_on_connection_error(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.side_effect = requests.exceptions.ConnectionError("refused")
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        result = c.goto_preset(mon, 1)
+        assert result is False
+
+
+# ---------------------------------------------------------------------------
+# goto_home
+# ---------------------------------------------------------------------------
+
+class TestGotoHome:
+    def _make_monitor(self, controllable=True):
+        raw = _monitor_raw(controllable="1" if controllable else "0")
+        return Monitor(_client(), raw)
+
+    def test_home_command_sends_preset_home(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        c.goto_home(mon)
+        call_kwargs = c._session.post.call_args
+        assert call_kwargs.kwargs["params"]["control"] == "presetHome"
+
+    def test_raises_on_non_controllable(self):
+        c = _client()
+        c._auth_token = "tok"
+        mon = self._make_monitor(controllable=False)
+        with pytest.raises(MonitorControlTypeError):
+            c.goto_home(mon)
+
+    def test_returns_bool_on_success(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        result = c.goto_home(mon)
+        assert result is True
+
+    def test_returns_false_on_connection_error(self):
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.side_effect = requests.exceptions.ConnectionError("refused")
+        mon = Monitor(c, _monitor_raw(controllable="1"))
+        result = c.goto_home(mon)
+        assert result is False
+
+    def test_uses_server_url_for_multi_server(self):
+        """goto_home should resolve the per-server URL."""
+        c = _client()
+        c._auth_token = "tok"
+        c._session = MagicMock()
+        c._session.post.return_value = MagicMock(ok=True)
+        raw = {"servers": [_server_raw(2, "Srv2", hostname="zm2.test", protocol="https")]}
+        with patch.object(c, "get_state", return_value=raw):
+            mon = Monitor(c, _monitor_raw(controllable="1", server_id="2"))
+            c.goto_home(mon)
+        call_kwargs = c._session.post.call_args
+        assert call_kwargs.kwargs["url"] == "https://zm2.test/zm/index.php"
+
+
 class TestStaleTokenRetry:
     """Verify _zm_request recomputes token suffix after login() refreshes the token."""
 

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/zoneminder/monitor.py

@@ -5,12 +5,16 @@ from __future__ import annotations
 from enum import Enum
 import logging
 import time
+from typing import TYPE_CHECKING
 from urllib.parse import urlencode
 
 import requests
 
 from .exceptions import ControlTypeError, MonitorControlTypeError
 
+if TYPE_CHECKING:
+    from zoneminder.zm import ZoneMinder
+
 _LOGGER = logging.getLogger(__name__)
 
 # Alarm state values as returned by the ZM API alarm status endpoint.
@@ -195,12 +199,19 @@ class TimePeriod(Enum):
 class Monitor:
     """Represents a Monitor from ZoneMinder."""
 
-    def __init__(self, client, raw_result, *, scale=None, maxfps=None):
+    def __init__(
+        self,
+        client: ZoneMinder,
+        raw_result: dict,
+        *,
+        scale: int | None = None,
+        maxfps: float | None = None,
+    ) -> None:
         """Create a new Monitor."""
         self._client = client
         self._raw_result = raw_result
-        self._scale: int | None = scale
-        self._maxfps: float | None = maxfps
+        self._scale = scale
+        self._maxfps = maxfps
         self._last_update = time.monotonic()
         raw_monitor = raw_result["Monitor"]
         self._monitor_id = int(raw_monitor["Id"])
@@ -476,3 +487,59 @@ class Monitor:
             _LOGGER.exception("Unable to connect to ZoneMinder for PTZ control")
             return False
         return bool(req.ok)
+
+    def preset_command(
+        self, preset: int, token: str | None, base_url: str, cookies: dict | None = None
+    ) -> bool:
+        """Move camera to a numbered preset position."""
+        if not self.controllable:
+            raise MonitorControlTypeError()
+
+        ptz_url = f"{base_url}index.php"
+        params: dict[str, str | int] = {
+            "view": "request",
+            "request": "control",
+            "id": self.id,
+            "control": f"presetGoto{preset}",
+        }
+        if token:
+            params["token"] = token
+
+        try:
+            req = self._client._session.post(  # pylint: disable=protected-access
+                url=ptz_url,
+                params=params,
+                cookies=cookies,
+                timeout=10,
+            )
+        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+            _LOGGER.exception("Unable to connect to ZoneMinder for preset control")
+            return False
+        return bool(req.ok)
+
+    def home_command(self, token: str | None, base_url: str, cookies: dict | None = None) -> bool:
+        """Move camera to the home position."""
+        if not self.controllable:
+            raise MonitorControlTypeError()
+
+        ptz_url = f"{base_url}index.php"
+        params: dict[str, str | int] = {
+            "view": "request",
+            "request": "control",
+            "id": self.id,
+            "control": "presetHome",
+        }
+        if token:
+            params["token"] = token
+
+        try:
+            req = self._client._session.post(  # pylint: disable=protected-access
+                url=ptz_url,
+                params=params,
+                cookies=cookies,
+                timeout=10,
+            )
+        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+            _LOGGER.exception("Unable to connect to ZoneMinder for home control")
+            return False
+        return bool(req.ok)

{zm_py-0.5.5.dev13 → zm_py-0.5.6.dev1}/zoneminder/zm.py

@@ -474,3 +474,23 @@ class ZoneMinder:
         else:
             _LOGGER.error("Failed to move camera to %s", direction)
         return result
+
+    def goto_preset(self, monitor: Monitor, preset: int) -> bool:
+        """Move camera to a numbered preset position."""
+        base_url = self.get_server_url_for_monitor(monitor.raw_monitor)
+        result = monitor.preset_command(preset, self._auth_token, base_url)
+        if result:
+            _LOGGER.info("Successfully moved camera to preset %d", preset)
+        else:
+            _LOGGER.error("Failed to move camera to preset %d", preset)
+        return result
+
+    def goto_home(self, monitor: Monitor) -> bool:
+        """Move camera to the home position."""
+        base_url = self.get_server_url_for_monitor(monitor.raw_monitor)
+        result = monitor.home_command(self._auth_token, base_url)
+        if result:
+            _LOGGER.info("Successfully moved camera to home position")
+        else:
+            _LOGGER.error("Failed to move camera to home position")
+        return result