googlewifiapi 0.1.0__tar.gz

googlewifiapi-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Eddie Reasoner
+
+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.

googlewifiapi-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: googlewifiapi
+Version: 0.1.0
+Summary: Asynchronous Python wrapper for the local Google Wifi JSON API
+Author-email: Eddie Reasoner <eddie.reasoner@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EReaso/GoogleWifiApi
+Project-URL: Bug Tracker, https://github.com/EReaso/GoogleWifiApi/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiohttp<3.14.0,>=3.11.0
+Requires-Dist: mashumaro>=3.22
+Requires-Dist: yarl>=1.24.5
+Dynamic: license-file
+
+# googlewifiapi
+
+An asynchronous Python client for reading status from the local JSON API exposed
+by Google Wifi routers.
+The package is designed for integrations such as Home Assistant, but can be used by any Python application that needs router status data.
+
+## About this README
+
+This README was generated by AI with human review.
+All code is either written by a human or is thoroughly reviewed.
+I'll try to keep the README updated, but sometimes I might forget.
+
+## Requirements
+
+- Python 3.13 or newer
+- A Google Wifi router reachable on the local network
+
+## Installation
+
+```bash
+pip install googlewifiapi
+```
+
+## Usage
+
+Pass an `aiohttp.ClientSession` to the client so your application controls the
+session lifecycle:
+
+```python
+import asyncio
+
+import aiohttp
+
+from googlewifiapi import GoogleWifiAPI
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        router = GoogleWifiAPI(host="192.168.86.1", sess=session)
+        await router.async_update()
+
+        if router.data is not None:
+            print(router.data.wan.online)
+            print(router.data.software.software_version)
+            print(router.data.system.last_restart)
+
+
+asyncio.run(main())
+```
+
+The host defaults to `192.168.86.1`. After a successful update:
+
+- `router.raw_data` contains the raw JSON response.
+- `router.data` contains a validated, typed `GoogleWifiStatus`.
+- IP address fields are parsed as `IPv4Address` or `IPv6Address` objects.
+- `system.last_restart` is calculated from the router's uptime.
+
+The status object exposes `dns`, `software`, `system`, and `wan` sections. Their
+fields use Python names such as `software_version`, `gateway_ip_address`, and
+`ip_prefix_length`, while the client handles the router API's camelCase keys.
+
+## Errors
+
+All library errors inherit from `GoogleWifiException`:
+
+- `GoogleWifiClientError` indicates a request, connection, timeout, or JSON
+  decoding failure.
+- `GoogleWifiDataValidationError` indicates that the response does not match
+  the expected status schema.
+
+## Development
+
+Install the test dependencies and run the test suite with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --group test
+uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.txt](LICENSE.txt).
+
+## Disclaimer
+
+This is an independent, community-developed project and is not affiliated with
+or endorsed by Google LLC. It relies on a local API that Google may change or
+remove without notice.

googlewifiapi-0.1.0/README.md

@@ -0,0 +1,88 @@
+# googlewifiapi
+
+An asynchronous Python client for reading status from the local JSON API exposed
+by Google Wifi routers.
+The package is designed for integrations such as Home Assistant, but can be used by any Python application that needs router status data.
+
+## About this README
+
+This README was generated by AI with human review.
+All code is either written by a human or is thoroughly reviewed.
+I'll try to keep the README updated, but sometimes I might forget.
+
+## Requirements
+
+- Python 3.13 or newer
+- A Google Wifi router reachable on the local network
+
+## Installation
+
+```bash
+pip install googlewifiapi
+```
+
+## Usage
+
+Pass an `aiohttp.ClientSession` to the client so your application controls the
+session lifecycle:
+
+```python
+import asyncio
+
+import aiohttp
+
+from googlewifiapi import GoogleWifiAPI
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        router = GoogleWifiAPI(host="192.168.86.1", sess=session)
+        await router.async_update()
+
+        if router.data is not None:
+            print(router.data.wan.online)
+            print(router.data.software.software_version)
+            print(router.data.system.last_restart)
+
+
+asyncio.run(main())
+```
+
+The host defaults to `192.168.86.1`. After a successful update:
+
+- `router.raw_data` contains the raw JSON response.
+- `router.data` contains a validated, typed `GoogleWifiStatus`.
+- IP address fields are parsed as `IPv4Address` or `IPv6Address` objects.
+- `system.last_restart` is calculated from the router's uptime.
+
+The status object exposes `dns`, `software`, `system`, and `wan` sections. Their
+fields use Python names such as `software_version`, `gateway_ip_address`, and
+`ip_prefix_length`, while the client handles the router API's camelCase keys.
+
+## Errors
+
+All library errors inherit from `GoogleWifiException`:
+
+- `GoogleWifiClientError` indicates a request, connection, timeout, or JSON
+  decoding failure.
+- `GoogleWifiDataValidationError` indicates that the response does not match
+  the expected status schema.
+
+## Development
+
+Install the test dependencies and run the test suite with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --group test
+uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.txt](LICENSE.txt).
+
+## Disclaimer
+
+This is an independent, community-developed project and is not affiliated with
+or endorsed by Google LLC. It relies on a local API that Google may change or
+remove without notice.

googlewifiapi-0.1.0/googlewifiapi/__init__.py

@@ -0,0 +1,5 @@
+from .api import GoogleWifiAPI
+from .const import LOGGER
+from .status import GoogleWifiStatus
+
+__all__ = ["GoogleWifiAPI", "GoogleWifiStatus", "LOGGER"]

googlewifiapi-0.1.0/googlewifiapi/api.py

@@ -0,0 +1,57 @@
+"""Google Wifi API wrapper."""
+
+from typing import Any
+
+import aiohttp
+from yarl import URL
+
+from .const import DEFAULT_HOST, ENDPOINT
+from .exception import (
+    GoogleWifiClientError,
+    GoogleWifiDataValidationError,
+    GoogleWifiException,
+)
+from .status import GoogleWifiStatus
+
+
+class GoogleWifiAPI:
+    """Get the latest data and update the states."""
+
+    raw_data: dict[str, Any] | None = None
+    available: bool = True
+    _resource: URL
+    data: GoogleWifiStatus | None = None
+    sess: aiohttp.ClientSession
+
+    def __init__(
+        self, host: str = DEFAULT_HOST, sess: aiohttp.ClientSession | None = None
+    ) -> None:
+        """Initialize the API wrapper."""
+        self._resource = URL(f"http://{host}{ENDPOINT}")
+        self.sess = sess or aiohttp.ClientSession()
+
+    async def async_update(self) -> GoogleWifiStatus:
+        """Get the latest data from the router."""
+        try:
+            resp = await self.sess.get(self._resource)
+            raw_data = await resp.json()
+        except (aiohttp.ClientError, ValueError) as err:
+            raise GoogleWifiClientError() from err
+
+        if not isinstance(raw_data, dict):
+            raise GoogleWifiDataValidationError(
+                f"The router provided data that could not be validated. "
+                f"Raw data: {raw_data}"
+            )
+
+        self.raw_data = raw_data
+        try:
+            self.data = GoogleWifiStatus.from_dict(raw_data)
+            return self.data
+        except (LookupError, TypeError, ValueError) as err:
+            raise GoogleWifiDataValidationError(
+                f"The router provided data that could not be validated. "
+                f"Raw data: {raw_data}"
+            ) from err
+        except Exception as err:
+            raise GoogleWifiException() from err

googlewifiapi-0.1.0/googlewifiapi/const.py

@@ -0,0 +1,7 @@
+"""Constants for the Google Wifi API wrapper."""
+
+import logging
+
+DEFAULT_HOST = "192.168.86.1"
+ENDPOINT = "/api/v1/status"
+LOGGER = logging.getLogger(__package__)

googlewifiapi-0.1.0/googlewifiapi/exception.py

@@ -0,0 +1,13 @@
+"""Exceptions for the Google Wifi API Wrapper."""
+
+
+class GoogleWifiException(Exception):
+    """Raised when there is a generic exception while wrapping the API."""
+
+
+class GoogleWifiDataValidationError(GoogleWifiException):
+    """Raised when the data cannot be validated."""
+
+
+class GoogleWifiClientError(GoogleWifiException):
+    """Raised when the connection fails in some way."""

googlewifiapi-0.1.0/googlewifiapi/status.py

@@ -0,0 +1,93 @@
+"""Google Wifi Status using mashumaro dataclasses."""
+
+import ipaddress
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Literal, Union
+
+from mashumaro import DataClassDictMixin
+from mashumaro.config import BaseConfig
+
+
+IPAddress = Union[ipaddress.IPv4Address, ipaddress.IPv6Address]
+
+
+@dataclass(frozen=True)
+class GoogleWifiStatus(DataClassDictMixin):
+    """Google Wifi status."""
+
+    dns: "GoogleWifiStatus.DNS"
+    software: "GoogleWifiStatus.Software"
+    system: "GoogleWifiStatus.System"
+    wan: "GoogleWifiStatus.WAN"
+
+    class Config(BaseConfig):
+        serialize_by_alias = True
+        deserialize_by_alias = True
+
+    @dataclass(frozen=True)
+    class DNS(DataClassDictMixin):
+        mode: Literal["automatic", "custom"]
+        servers: list[IPAddress]
+
+    @dataclass(frozen=True)
+    class Software(DataClassDictMixin):
+        software_version: str
+        update_status: str
+        update_required: bool
+        update_progress: float
+
+        class Config(BaseConfig):
+            serialize_by_alias = True
+            deserialize_by_alias = True
+            aliases = {
+                "software_version": "softwareVersion",
+                "update_status": "updateStatus",
+                "update_required": "updateRequired",
+                "update_progress": "updateProgress",
+            }
+
+    @dataclass(frozen=True)
+    class System(DataClassDictMixin):
+        country_code: str
+        model_id: str
+        uptime: int
+        last_restart: datetime = field(init=False)
+
+        class Config(BaseConfig):
+            serialize_by_alias = True
+            deserialize_by_alias = True
+            aliases = {
+                "country_code": "countryCode",
+                "model_id": "modelId",
+            }
+
+        def __post_init__(self):
+            """Compute last_restart from uptime."""
+            object.__setattr__(
+                self,
+                "last_restart",
+                datetime.now() - timedelta(seconds=self.uptime),
+            )
+
+    @dataclass(frozen=True)
+    class WAN(DataClassDictMixin):
+        online: bool
+        ethernet_link: bool
+        gateway_ip_address: IPAddress
+        local_ip_address: IPAddress
+        ip_method: str
+        ip_prefix_length: int
+        name_servers: list[IPAddress]
+
+        class Config(BaseConfig):
+            serialize_by_alias = True
+            deserialize_by_alias = True
+            aliases = {
+                "ethernet_link": "ethernetLink",
+                "gateway_ip_address": "gatewayIpAddress",
+                "local_ip_address": "localIpAddress",
+                "ip_method": "ipMethod",
+                "ip_prefix_length": "ipPrefixLength",
+                "name_servers": "nameServers",
+            }

googlewifiapi-0.1.0/googlewifiapi.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: googlewifiapi
+Version: 0.1.0
+Summary: Asynchronous Python wrapper for the local Google Wifi JSON API
+Author-email: Eddie Reasoner <eddie.reasoner@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EReaso/GoogleWifiApi
+Project-URL: Bug Tracker, https://github.com/EReaso/GoogleWifiApi/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiohttp<3.14.0,>=3.11.0
+Requires-Dist: mashumaro>=3.22
+Requires-Dist: yarl>=1.24.5
+Dynamic: license-file
+
+# googlewifiapi
+
+An asynchronous Python client for reading status from the local JSON API exposed
+by Google Wifi routers.
+The package is designed for integrations such as Home Assistant, but can be used by any Python application that needs router status data.
+
+## About this README
+
+This README was generated by AI with human review.
+All code is either written by a human or is thoroughly reviewed.
+I'll try to keep the README updated, but sometimes I might forget.
+
+## Requirements
+
+- Python 3.13 or newer
+- A Google Wifi router reachable on the local network
+
+## Installation
+
+```bash
+pip install googlewifiapi
+```
+
+## Usage
+
+Pass an `aiohttp.ClientSession` to the client so your application controls the
+session lifecycle:
+
+```python
+import asyncio
+
+import aiohttp
+
+from googlewifiapi import GoogleWifiAPI
+
+
+async def main() -> None:
+    async with aiohttp.ClientSession() as session:
+        router = GoogleWifiAPI(host="192.168.86.1", sess=session)
+        await router.async_update()
+
+        if router.data is not None:
+            print(router.data.wan.online)
+            print(router.data.software.software_version)
+            print(router.data.system.last_restart)
+
+
+asyncio.run(main())
+```
+
+The host defaults to `192.168.86.1`. After a successful update:
+
+- `router.raw_data` contains the raw JSON response.
+- `router.data` contains a validated, typed `GoogleWifiStatus`.
+- IP address fields are parsed as `IPv4Address` or `IPv6Address` objects.
+- `system.last_restart` is calculated from the router's uptime.
+
+The status object exposes `dns`, `software`, `system`, and `wan` sections. Their
+fields use Python names such as `software_version`, `gateway_ip_address`, and
+`ip_prefix_length`, while the client handles the router API's camelCase keys.
+
+## Errors
+
+All library errors inherit from `GoogleWifiException`:
+
+- `GoogleWifiClientError` indicates a request, connection, timeout, or JSON
+  decoding failure.
+- `GoogleWifiDataValidationError` indicates that the response does not match
+  the expected status schema.
+
+## Development
+
+Install the test dependencies and run the test suite with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --group test
+uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE.txt](LICENSE.txt).
+
+## Disclaimer
+
+This is an independent, community-developed project and is not affiliated with
+or endorsed by Google LLC. It relies on a local API that Google may change or
+remove without notice.

googlewifiapi-0.1.0/googlewifiapi.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.txt
+README.md
+pyproject.toml
+googlewifiapi/__init__.py
+googlewifiapi/api.py
+googlewifiapi/const.py
+googlewifiapi/exception.py
+googlewifiapi/status.py
+googlewifiapi.egg-info/PKG-INFO
+googlewifiapi.egg-info/SOURCES.txt
+googlewifiapi.egg-info/dependency_links.txt
+googlewifiapi.egg-info/requires.txt
+googlewifiapi.egg-info/top_level.txt
+tests/test_status.py

googlewifiapi-0.1.0/googlewifiapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

googlewifiapi-0.1.0/googlewifiapi.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp<3.14.0,>=3.11.0
+mashumaro>=3.22
+yarl>=1.24.5

googlewifiapi-0.1.0/googlewifiapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+googlewifiapi

googlewifiapi-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "googlewifiapi"
+version = "0.1.0"
+description = "Asynchronous Python wrapper for the local Google Wifi JSON API"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+  { name = "Eddie Reasoner", email = "eddie.reasoner@gmail.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "aiohttp>=3.11.0,<3.14.0",
+    "mashumaro>=3.22",
+    "yarl>=1.24.5",
+]
+
+[dependency-groups]
+test = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "aioresponses>=0.7.9",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/EReaso/GoogleWifiApi"
+"Bug Tracker" = "https://github.com/EReaso/GoogleWifiApi/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "D",
+    "E",
+    "F",
+    "I",
+    "SIM",
+    "W",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.mypy]
+python_version = "3.13"
+show_error_codes = true
+follow_imports = "silent"
+ignore_missing_imports = true
+strict = true
+warn_incomplete_stub = true
+warn_redundant_casts = true
+warn_unused_configs = true
+warn_unused_ignores = true

googlewifiapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

googlewifiapi-0.1.0/tests/test_status.py

@@ -0,0 +1,145 @@
+"""Test that the API wrapper can fetch and interpret the router status."""
+
+from ipaddress import IPv4Address
+from typing import Any
+from unittest.mock import patch
+
+import aiohttp
+import pytest
+from aioresponses import aioresponses
+
+from googlewifiapi.api import GoogleWifiAPI
+from googlewifiapi.exception import (
+    GoogleWifiClientError,
+    GoogleWifiDataValidationError,
+    GoogleWifiException,
+)
+from googlewifiapi.status import GoogleWifiStatus
+
+from .conftest import RESOURCE_URL
+
+
+def test_schema_validation(normal_response: dict[str, Any]) -> None:
+    """Test that the GoogleWifiStatus schema validates sample data from a normal response correctly."""
+    status = GoogleWifiStatus.from_dict(normal_response)
+
+    assert status.dns.mode == "automatic"
+    assert status.dns.servers == [
+        IPv4Address("75.75.75.75"),
+        IPv4Address("75.75.76.76"),
+    ]
+
+    assert status.software.software_version == "softwareVersion"
+    assert status.software.update_status == "idle"
+    assert status.software.update_required is False
+    assert status.software.update_progress == 0.0
+
+    assert status.system.country_code == "us"
+    assert isinstance(status.system.country_code, str)
+    assert status.system.model_id == "modelId"
+    assert status.system.uptime == 3600
+    assert status.system.last_restart is not None
+
+    assert status.wan.online is True
+    assert status.wan.ethernet_link is True
+    assert status.wan.gateway_ip_address == IPv4Address("10.0.0.1")
+    assert status.wan.local_ip_address == IPv4Address("10.0.0.10")
+    assert status.wan.ip_method == "dhcp"
+    assert status.wan.ip_prefix_length == 24
+    assert status.wan.name_servers == [
+        IPv4Address("75.75.75.75"),
+        IPv4Address("75.75.76.76"),
+    ]
+
+
+class TestApiUpdate:
+    """Tests whether the API wrapper can update with different conditions."""
+
+    @pytest.mark.asyncio
+    async def test_async_update_success(
+        self,
+        mock_success: aioresponses,
+        client: GoogleWifiAPI,
+        normal_response: dict[str, Any],
+    ) -> None:
+        """Test that a normal response updates the client's data correctly."""
+        await client.async_update()
+
+        assert client.raw_data == normal_response
+        assert isinstance(client.data, GoogleWifiStatus)
+
+    @pytest.mark.asyncio
+    async def test_async_update_invalid_data_raises_validation_error(
+        self,
+        mock_aioresponse: aioresponses,
+        client: GoogleWifiAPI,
+        normal_response: dict[str, Any],
+    ) -> None:
+        """Test that a response missing required fields raises a validation error."""
+        broken_response = {k: v for k, v in normal_response.items() if k != "wan"}
+        mock_aioresponse.get(RESOURCE_URL, status=200, payload=broken_response)
+
+        with pytest.raises(GoogleWifiDataValidationError):
+            await client.async_update()
+
+    @pytest.mark.asyncio
+    async def test_async_update_empty_response_raises_validation_error(
+        self, mock_aioresponse: aioresponses, client: GoogleWifiAPI
+    ) -> None:
+        """Test that an empty/null response body raises a validation error."""
+        mock_aioresponse.get(RESOURCE_URL, status=200, payload=None)
+
+        with pytest.raises(GoogleWifiDataValidationError):
+            await client.async_update()
+
+    @pytest.mark.asyncio
+    async def test_async_update_invalid_json_raises_client_error(
+        self, mock_aioresponse: aioresponses, client: "GoogleWifiAPI"
+    ) -> None:
+        """Test that a non-JSON response body raises a client error."""
+        mock_aioresponse.get(
+            RESOURCE_URL,
+            status=200,
+            body="not valid json{{{",
+            content_type="application/json",
+        )
+
+        with pytest.raises(GoogleWifiClientError):
+            await client.async_update()
+
+    @pytest.mark.asyncio
+    async def test_async_update_connection_error_raises_client_error(
+        self, mock_unreachable: aioresponses, client: "GoogleWifiAPI"
+    ) -> None:
+        """Test that a connection failure raises a client error."""
+        with pytest.raises(GoogleWifiClientError):
+            await client.async_update()
+
+    @pytest.mark.asyncio
+    async def test_async_update_timeout_raises_client_error(
+        self, mock_aioresponse: aioresponses, client: "GoogleWifiAPI"
+    ) -> None:
+        """Test that a request timeout raises a client error."""
+        mock_aioresponse.get(
+            RESOURCE_URL,
+            exception=aiohttp.ServerTimeoutError("request timed out"),
+        )
+
+        with pytest.raises(GoogleWifiClientError):
+            await client.async_update()
+
+    @pytest.mark.asyncio
+    async def test_async_update_unexpected_error_raises_generic_exception(
+        self,
+        mock_success: aioresponses,
+        client: GoogleWifiAPI,
+    ) -> None:
+        """Test that an unexpected failure in schema parsing raises the generic exception."""
+        with (
+            patch(
+                "googlewifiapi.status.GoogleWifiStatus.from_dict",
+                side_effect=RuntimeError("boom"),
+            ),
+            pytest.raises(GoogleWifiException),
+        ):
+            await client.async_update()