pytigo 0.3.0__tar.gz

pytigo-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blind Badger Studios
+
+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.

pytigo-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

pytigo-0.3.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pytigo
+Version: 0.3.0
+Summary: Python client for the documented Tigo REST API v3
+Author: Blind Badger Studios
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BlindBadgerStudios/PyTigo
+Project-URL: Repository, https://github.com/BlindBadgerStudios/PyTigo
+Project-URL: Issues, https://github.com/BlindBadgerStudios/PyTigo/issues
+Keywords: tigo,solar,energy,monitoring,photovoltaic,pv,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# pytigo
+
+pytigo is a Python client for the documented Tigo REST API v3.  It is focussed on near-real time monitoring (for time-series systems like Prometheus).
+
+It is centered on the official API described in Tigo-API-V3.pdf, using:
+- base URL: https://api2.tigoenergy.com/api/v3/
+- token auth from `users/login`
+- documented systems, objects, sources, and data endpoints
+
+Supported official API areas:
+- users/login
+- users/logout
+- users/get
+- systems/list
+- systems/view
+- systems/layout
+- objects/system
+- objects/types
+- sources/system
+- data/summary
+- data/aggregate
+- data/combined
+- alerts/system
+- alerts/types
+
+## Install
+
+```bash
+pip install pytigo
+```
+
+## Quick start
+
+```python
+from pytigo import TigoClient
+
+client = TigoClient(username="you@example.com", password="super-secret")
+auth = client.login()
+
+systems = client.list_systems()
+system = systems[0]
+
+layout = client.get_layout(system.system_id)
+objects = client.get_objects(system.system_id)
+sources = client.get_sources(system.system_id)
+summary = client.get_summary(system.system_id)
+aggregate = client.get_aggregate(
+    system.system_id,
+    start="2026-03-31T00:00:00",
+    end="2026-03-31T23:59:59",
+    level="day",
+    param="Pin",
+)
+combined = client.get_combined(
+    system.system_id,
+    start="2026-03-31T00:00:00",
+    end="2026-03-31T23:59:59",
+    agg="day",
+)
+alerts = client.get_alerts(system.system_id, limit=10)
+alert_types = client.get_alert_types()
+
+print(auth.user_id)
+print(system.name)
+print(layout.inverters[0].label if layout.inverters else None)
+print(len(objects))
+print(sources[0].serial if sources else None)
+print(summary.daily_energy_dc)
+print(aggregate.rows[0].values)
+print(combined.rows[0].values)
+print(alerts[0].title if alerts else None)
+print(alert_types[0].title if alert_types else None)
+```
+
+## Notes
+
+The library returns typed Python models for JSON endpoints and a parsed table model for CSV-style telemetry endpoints like `data/aggregate` and `data/combined`.
+
+`data/aggregate` and `data/combined` are especially useful for exporter/monitoring use cases because they preserve timestamped telemetry in a table-shaped format that is easy to flatten for Prometheus, Grafana, or ETL pipelines.
+
+

pytigo-0.3.0/README.md

@@ -0,0 +1,81 @@
+# pytigo
+
+pytigo is a Python client for the documented Tigo REST API v3.  It is focussed on near-real time monitoring (for time-series systems like Prometheus).
+
+It is centered on the official API described in Tigo-API-V3.pdf, using:
+- base URL: https://api2.tigoenergy.com/api/v3/
+- token auth from `users/login`
+- documented systems, objects, sources, and data endpoints
+
+Supported official API areas:
+- users/login
+- users/logout
+- users/get
+- systems/list
+- systems/view
+- systems/layout
+- objects/system
+- objects/types
+- sources/system
+- data/summary
+- data/aggregate
+- data/combined
+- alerts/system
+- alerts/types
+
+## Install
+
+```bash
+pip install pytigo
+```
+
+## Quick start
+
+```python
+from pytigo import TigoClient
+
+client = TigoClient(username="you@example.com", password="super-secret")
+auth = client.login()
+
+systems = client.list_systems()
+system = systems[0]
+
+layout = client.get_layout(system.system_id)
+objects = client.get_objects(system.system_id)
+sources = client.get_sources(system.system_id)
+summary = client.get_summary(system.system_id)
+aggregate = client.get_aggregate(
+    system.system_id,
+    start="2026-03-31T00:00:00",
+    end="2026-03-31T23:59:59",
+    level="day",
+    param="Pin",
+)
+combined = client.get_combined(
+    system.system_id,
+    start="2026-03-31T00:00:00",
+    end="2026-03-31T23:59:59",
+    agg="day",
+)
+alerts = client.get_alerts(system.system_id, limit=10)
+alert_types = client.get_alert_types()
+
+print(auth.user_id)
+print(system.name)
+print(layout.inverters[0].label if layout.inverters else None)
+print(len(objects))
+print(sources[0].serial if sources else None)
+print(summary.daily_energy_dc)
+print(aggregate.rows[0].values)
+print(combined.rows[0].values)
+print(alerts[0].title if alerts else None)
+print(alert_types[0].title if alert_types else None)
+```
+
+## Notes
+
+The library returns typed Python models for JSON endpoints and a parsed table model for CSV-style telemetry endpoints like `data/aggregate` and `data/combined`.
+
+`data/aggregate` and `data/combined` are especially useful for exporter/monitoring use cases because they preserve timestamped telemetry in a table-shaped format that is easy to flatten for Prometheus, Grafana, or ETL pipelines.
+
+

pytigo-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytigo"
+version = "0.3.0"
+description = "Python client for the documented Tigo REST API v3"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "Blind Badger Studios" },
+]
+keywords = ["tigo", "solar", "energy", "monitoring", "photovoltaic", "pv", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Home Automation",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/BlindBadgerStudios/PyTigo"
+Repository = "https://github.com/BlindBadgerStudios/PyTigo"
+Issues = "https://github.com/BlindBadgerStudios/PyTigo/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "build",
+  "twine",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

pytigo-0.3.0/setup.cfg

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

pytigo-0.3.0/src/pytigo/__init__.py

@@ -0,0 +1,6 @@
+from .client import TigoClient
+from .models import TigoPage
+
+__version__ = "0.3.0"
+
+__all__ = ["TigoClient", "TigoPage", "__version__"]

pytigo-0.3.0/src/pytigo/client.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from requests import Session
+
+from .models import (
+    TigoAlert,
+    TigoAlertType,
+    TigoAuth,
+    TigoCSVTable,
+    TigoObjectNode,
+    TigoObjectType,
+    TigoPage,
+    TigoSource,
+    TigoSummary,
+    TigoSystem,
+    TigoSystemLayout,
+    TigoUser,
+)
+from .parsing import (
+    parse_alert_types_response,
+    parse_alerts_response,
+    parse_csv_table,
+    parse_layout_response,
+    parse_login_response,
+    parse_object_types_response,
+    parse_objects_response,
+    parse_sources_response,
+    parse_summary_response,
+    parse_system_response,
+    parse_systems_response,
+    parse_user_response,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TigoClient:
+    api_root = "https://api2.tigoenergy.com/api/v3"
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        *,
+        session: Session | None = None,
+        timeout: int = 30,
+    ) -> None:
+        self.username = username
+        self.password = password
+        self.timeout = timeout
+        self.session = session or Session()
+        self.auth: TigoAuth | None = None
+
+    def _headers(self) -> dict[str, str]:
+        if not self.auth:
+            raise ValueError("Not authenticated. Call login() first.")
+        return {"Authorization": f"Bearer {self.auth.auth_token}"}
+
+    def __enter__(self) -> TigoClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.session.close()
+
+    def login(self) -> TigoAuth:
+        logger.debug("GET /users/login user=%s", self.username)
+        response = self.session.get(
+            f"{self.api_root}/users/login",
+            auth=(self.username, self.password),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        self.auth = parse_login_response(response.json())
+        logger.debug("login successful user_id=%s", self.auth.user_id)
+        return self.auth
+
+    def logout(self) -> dict:
+        logger.debug("GET /users/logout")
+        response = self.session.get(
+            f"{self.api_root}/users/logout",
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        self.auth = None
+        return payload
+
+    def get_current_user(self, user_id: int | None = None) -> TigoUser:
+        if user_id is None:
+            if not self.auth:
+                raise ValueError("user_id is required before login; after login it defaults to auth.user_id")
+            user_id = self.auth.user_id
+        logger.debug("GET /users/%s", user_id)
+        response = self.session.get(
+            f"{self.api_root}/users/{user_id}",
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_user_response(response.json())
+
+    def list_systems(self, *, page: int | None = None, limit: int | None = None, sort: str | None = None) -> TigoPage[TigoSystem]:
+        params: dict[str, int | str] = {}
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+        if sort is not None:
+            params["sort"] = sort
+        logger.debug("GET /systems params=%s", params)
+        response = self.session.get(
+            f"{self.api_root}/systems",
+            headers=self._headers(),
+            params=params or None,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_systems_response(response.json())
+
+    def get_system(self, system_id: int, *, include: list[str] | None = None) -> TigoSystem:
+        params: dict[str, str | int] = {"id": system_id}
+        if include:
+            params["include"] = ",".join(include)
+        logger.debug("GET /systems/view system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/systems/view",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_system_response(response.json())
+
+    def get_layout(self, system_id: int) -> TigoSystemLayout:
+        logger.debug("GET /systems/layout system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/systems/layout",
+            headers=self._headers(),
+            params={"id": system_id},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_layout_response(response.json())
+
+    def get_objects(self, system_id: int) -> list[TigoObjectNode]:
+        logger.debug("GET /objects/system system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/objects/system",
+            headers=self._headers(),
+            params={"system_id": system_id},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_objects_response(response.json())
+
+    def get_object_types(self) -> list[TigoObjectType]:
+        logger.debug("GET /objects/types")
+        response = self.session.get(
+            f"{self.api_root}/objects/types",
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_object_types_response(response.json())
+
+    def get_sources(self, system_id: int) -> list[TigoSource]:
+        logger.debug("GET /sources/system system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/sources/system",
+            headers=self._headers(),
+            params={"system_id": system_id},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_sources_response(response.json())
+
+    def get_summary(self, system_id: int) -> TigoSummary:
+        logger.debug("GET /data/summary system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/data/summary",
+            headers=self._headers(),
+            params={"system_id": system_id},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_summary_response(response.json())
+
+    def get_aggregate(
+        self,
+        system_id: int,
+        *,
+        start: str,
+        end: str,
+        level: Literal["min", "hour", "day"] = "min",
+        param: str = "Pin",
+        object_ids: list[int] | None = None,
+        header: str | None = None,
+        sensors: bool | None = None,
+    ) -> TigoCSVTable:
+        params: dict[str, str] = {
+            "system_id": str(system_id),
+            "start": start,
+            "end": end,
+            "level": level,
+            "param": param,
+        }
+        if object_ids:
+            params["object_ids"] = ",".join(str(i) for i in object_ids)
+        if header:
+            params["header"] = header
+        if sensors is not None:
+            params["sensors"] = "true" if sensors else "false"
+        logger.debug("GET /data/aggregate system_id=%s param=%s level=%s", system_id, param, level)
+        response = self.session.get(
+            f"{self.api_root}/data/aggregate",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_csv_table(response.text)
+
+    def get_combined(
+        self,
+        system_id: int,
+        *,
+        start: str,
+        end: str,
+        agg: Literal["min", "hour", "day"],
+        object_ids: list[int] | None = None,
+    ) -> TigoCSVTable:
+        params: dict[str, str] = {
+            "system_id": str(system_id),
+            "start": start,
+            "end": end,
+            "agg": agg,
+        }
+        if object_ids:
+            params["object_ids"] = ",".join(str(i) for i in object_ids)
+        logger.debug("GET /data/combined system_id=%s agg=%s", system_id, agg)
+        response = self.session.get(
+            f"{self.api_root}/data/combined",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_csv_table(response.text)
+
+    def get_alerts(
+        self,
+        system_id: int,
+        *,
+        language: str | None = None,
+        start_added: str | None = None,
+        end_added: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> TigoPage[TigoAlert]:
+        params: dict[str, str | int] = {"system_id": system_id}
+        if language:
+            params["language"] = language
+        if start_added:
+            params["start_added"] = start_added
+        if end_added:
+            params["end_added"] = end_added
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+        logger.debug("GET /alerts/system system_id=%s", system_id)
+        response = self.session.get(
+            f"{self.api_root}/alerts/system",
+            headers=self._headers(),
+            params=params,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_alerts_response(response.json())
+
+    def get_alert_types(self, *, language: str | None = None) -> list[TigoAlertType]:
+        params: dict[str, str] = {}
+        if language:
+            params["language"] = language
+        logger.debug("GET /alerts/types")
+        response = self.session.get(
+            f"{self.api_root}/alerts/types",
+            headers=self._headers(),
+            params=params or None,
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        return parse_alert_types_response(response.json())