python-tado 0.19.2__tar.gz → 1.0.0__tar.gz

{python_tado-0.19.2 → python_tado-1.0.0}/PKG-INFO

@@ -1,8 +1,10 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-tado
-Version: 0.19.2
+Version: 1.0.0
 Summary: PyTado from chrism0dwk, modified by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem
 License: GPL-3.0-or-later
+License-File: AUTHORS
+License-File: LICENSE
 Keywords: tado
 Author: Chris Jewell
 Author-email: chrism0dwk@gmail.com
@@ -16,13 +18,15 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Provides-Extra: all
 Provides-Extra: dev
 Provides-Extra: lint
 Provides-Extra: test
-Requires-Dist: black (>=24.10) ; extra == "lint" or extra == "all"
 Requires-Dist: pre-commit ; extra == "dev" or extra == "all"
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: pydoc-markdown
 Requires-Dist: pylint ; extra == "lint" or extra == "all"
 Requires-Dist: pytest ; extra == "test" or extra == "all"
 Requires-Dist: pytest-cov ; extra == "test" or extra == "all"
@@ -49,14 +53,14 @@ PyTado is a Python module implementing an interface to the Tado web API. It allo
 Tado heating system for the purposes of monitoring or controlling their heating system, beyond what Tado themselves
 currently offer.
 
-It is hoped that this module might be used by those who wish to tweak their Tado systems, and further optimise their
+It is hoped that this module might be used by those who wish to tweak their Tado systems, and further optimize their
 heating setups.
 
 ---
 
 Original author: Chris Jewell <chrism0dwk@gmail.com>
 
-Licence: GPL v3
+License: GPL v3
 
 Copyright: Chris Jewell 2016-2018
 
@@ -65,7 +69,7 @@ Copyright: Chris Jewell 2016-2018
 Besides owning a Tado system, I have no connection with the Tado company themselves. PyTado was created for my own use,
 and for others who may wish to experiment with personal Internet of Things systems. I receive no help (financial or
 otherwise) from Tado, and have no business interest with them. This software is provided without warranty, according to
-the GNU Public Licence version 3, and should therefore not be used where it may endanger life, financial stakes, or
+the GNU Public License version 3, and should therefore not be used where it may endanger life, financial stakes, or
 cause discomfort and inconvenience to others.
 
 ## Usage
@@ -93,7 +97,7 @@ It is possible to save the refresh token and reuse to skip the next login.
 
 The following code will use the `refresh_token` file to save the refresh-token after login, and load the refresh-token if you create the Tado interface class again.
 
-If the file doesn't exists, the webbrowser is started and the device authentication url is automatically opened. You can activate the device in the browser. When you restart the program, the refresh-token is reused and no webbrowser will be opened.
+If the file doesn't exists, the web browser is started and the device authentication url is automatically opened. You can activate the device in the browser. When you restart the program, the refresh-token is reused and no web browser will be opened.
 
 ```python
 import webbrowser   # only needed for direct web browser access
@@ -150,7 +154,6 @@ if __name__ == "__main__":
 Note: For developers, there is an `example.py` script in `examples/` which is configured to fetch data from your account.
 You can then invoke `python examples/example.py`.
 
-
 ## Contributing
 
 We are very open to the community's contributions - be it a quick fix of a typo, or a completely new feature!
@@ -182,20 +185,7 @@ git clone https://github.com/yourusername/PyTado.git
 cd PyTado
 ```
 
-Then, to create your development environment and install the project with its dependencies, execute the following
-commands in your terminal:
-
-```bash
-# Create and activate a new virtual environment
-python3 -m venv venv
-source venv/bin/activate
-
-# install all dependencies
-poetry install
-
-# Install pre-commit hooks
-poetry run pre-commit install
-```
+Then, to create your development environment and install the project with its dependencies, execute the `./scripts/bootstrap` script.
 
 ### Coding Guidelines
 
@@ -234,7 +224,6 @@ A message from the original author:
 >
 > Chris Jewell
 
-
 [devcontainer-shield]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode
 [devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/wmalgadey/PyTado
 

python_tado-1.0.0/PyTado/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("python-tado")
+except PackageNotFoundError:
+    __version__ = "test"  # happens when running as pre-commit hook

{python_tado-0.19.2 → python_tado-1.0.0}/PyTado/__main__.py

@@ -9,7 +9,7 @@ import sys
 from PyTado.interface import Tado
 
 
-def log_in(args):
+def log_in(args: argparse.Namespace) -> Tado:
     """
     Log in to the Tado API by activating the current device.
 
@@ -27,7 +27,7 @@ def log_in(args):
     return t
 
 
-def get_me(args):
+def get_me(args: argparse.Namespace) -> None:
     """
     Retrieve and print home information from the Tado API.
 
@@ -39,7 +39,7 @@ def get_me(args):
     print(me)
 
 
-def get_state(args):
+def get_state(args: argparse.Namespace) -> None:
     """
     Retrieve and print the state of a specific zone from the Tado API.
 
@@ -51,7 +51,7 @@ def get_state(args):
     print(zone)
 
 
-def get_states(args):
+def get_states(args: argparse.Namespace) -> None:
     """
     Retrieve and print the states of all zones from the Tado API.
 
@@ -63,7 +63,7 @@ def get_states(args):
     print(zones)
 
 
-def get_capabilities(args):
+def get_capabilities(args: argparse.Namespace) -> None:
     """
     Retrieve and print the capabilities of a specific zone from the Tado API.
 
@@ -75,7 +75,7 @@ def get_capabilities(args):
     print(capabilities)
 
 
-def main():
+def main() -> None:
     """
     Main method for the script.
 
@@ -109,17 +109,23 @@ def main():
     show_config_parser = subparsers.add_parser("get_me", help="Get home information.")
     show_config_parser.set_defaults(func=get_me)
 
-    start_activity_parser = subparsers.add_parser("get_state", help="Get state of zone.")
+    start_activity_parser = subparsers.add_parser(
+        "get_state", help="Get state of zone."
+    )
     start_activity_parser.add_argument("--zone", help="Zone to get the state of.")
     start_activity_parser.set_defaults(func=get_state)
 
-    start_activity_parser = subparsers.add_parser("get_states", help="Get states of all zones.")
+    start_activity_parser = subparsers.add_parser(
+        "get_states", help="Get states of all zones."
+    )
     start_activity_parser.set_defaults(func=get_states)
 
     start_activity_parser = subparsers.add_parser(
         "get_capabilities", help="Get capabilities of zone."
     )
-    start_activity_parser.add_argument("--zone", help="Zone to get the capabilities of.")
+    start_activity_parser.add_argument(
+        "--zone", help="Zone to get the capabilities of."
+    )
     start_activity_parser.set_defaults(func=get_capabilities)
 
     args = parser.parse_args()

python_tado-1.0.0/PyTado/const.py

@@ -0,0 +1,72 @@
+"""Constant values for the Tado component."""
+
+from PyTado.types import FanLevel, FanSpeed, HvacAction, HvacMode
+
+# API client ID
+CLIENT_ID_DEVICE = "1bb50063-6b0c-4d11-bd99-387f4a91cc46"  # nosec B105
+
+
+CONST_LINK_OFFLINE = "OFFLINE"
+CONST_CONNECTION_OFFLINE = "OFFLINE"
+
+
+FAN_SPEED_TO_FAN_LEVEL = {
+    FanSpeed.OFF: FanLevel.OFF,
+    FanSpeed.AUTO: FanLevel.AUTO,
+    FanSpeed.LOW: FanLevel.LEVEL1,
+    FanSpeed.MIDDLE: FanLevel.LEVEL2,
+    FanSpeed.HIGH: FanLevel.LEVEL3,
+}
+
+# When we change the temperature setting, we need an overlay mode
+CONST_OVERLAY_TADO_MODE = (
+    "NEXT_TIME_BLOCK"  # wait until tado changes the mode automatic
+)
+CONST_OVERLAY_MANUAL = "MANUAL"  # the user has changed the temperature or mode manually
+CONST_OVERLAY_TIMER = "TIMER"  # the temperature will be reset after a timespan
+
+# Heat always comes first since we get the
+# min and max tempatures for the zone from
+# it.
+# Heat is preferred as it generally has a lower minimum temperature
+ORDERED_KNOWN_TADO_MODES = [
+    HvacMode.HEAT,
+    HvacMode.COOL,
+    HvacMode.AUTO,
+    HvacMode.DRY,
+    HvacMode.FAN,
+]
+
+TADO_MODES_TO_HVAC_ACTION: dict[HvacMode, HvacAction] = {
+    HvacMode.HEAT: HvacAction.HEATING,
+    HvacMode.DRY: HvacAction.DRYING,
+    HvacMode.FAN: HvacAction.FAN,
+    HvacMode.COOL: HvacAction.COOLING,
+}
+
+TADO_HVAC_ACTION_TO_MODES: dict[HvacAction, HvacMode | HvacAction] = {
+    HvacAction.HEATING: HvacMode.HEAT,
+    HvacAction.HOT_WATER: HvacAction.HEATING,
+    HvacAction.DRYING: HvacMode.DRY,
+    HvacAction.FAN: HvacMode.FAN,
+    HvacAction.COOLING: HvacMode.COOL,
+}
+
+# These modes will not allow a temp to be set
+TADO_MODES_WITH_NO_TEMP_SETTING = [
+    HvacMode.AUTO,
+    HvacMode.DRY,
+    HvacMode.FAN,
+]
+
+DEFAULT_TADO_PRECISION = 0.1
+DEFAULT_TADOX_PRECISION = 0.01
+DEFAULT_DATE_FORMAT = "%Y-%m-%d"
+
+DEFAULT_TADOX_MIN_TEMP = 5.0
+DEFAULT_TADOX_MAX_TEMP = 30.0
+
+HOME_DOMAIN = "homes"
+DEVICE_DOMAIN = "devices"
+
+HTTP_CODES_OK = [200, 201, 202, 204]

{python_tado-0.19.2 → python_tado-1.0.0}/PyTado/exceptions.py

@@ -19,3 +19,7 @@ class TadoNoCredentialsException(TadoCredentialsException):
 
 class TadoWrongCredentialsException(TadoCredentialsException):
     """Exception to indicate wrong credentials"""
+
+
+class TadoRateLimitException(TadoException):
+    """Exception to indicate API rate limit has been exceeded."""

python_tado-1.0.0/PyTado/factory/__init__.py

@@ -0,0 +1,7 @@
+"""Factory method for easy initialization."""
+
+from ..interface.api.hops_tado import TadoX
+from ..interface.api.my_tado import Tado
+from .initializer import TadoClientInitializer
+
+__all__ = ["Tado", "TadoX", "TadoClientInitializer"]

python_tado-1.0.0/PyTado/factory/initializer.py

@@ -0,0 +1,90 @@
+"""
+PyTado API factory to use app.tado.com or hops.tado.com
+"""
+
+from typing import Self
+
+import requests
+
+import PyTado.interface.api as API
+from PyTado.exceptions import TadoException
+from PyTado.http import DeviceActivationStatus, Http
+
+
+class TadoClientInitializer:
+    """Class to authenticate and get the Tado client."""
+
+    http: Http
+    debug: bool = False
+    token_file_path: str | None = None
+    saved_refresh_token: str | None = None
+    http_session: requests.Session | None = None
+
+    def __init__(
+        self,
+        token_file_path: str | None = None,
+        saved_refresh_token: str | None = None,
+        http_session: requests.Session | None = None,
+        debug: bool = False,
+    ):
+        self.token_file_path = token_file_path
+        self.saved_refresh_token = saved_refresh_token
+        self.http_session = http_session
+        self.debug = debug
+        self.http = Http(
+            token_file_path=token_file_path,
+            saved_refresh_token=saved_refresh_token,
+            http_session=http_session,
+            debug=debug,
+        )
+
+    def get_verification_url(self) -> str | None:
+        """Returns the URL for device verification."""
+        if self.http.device_activation_status == DeviceActivationStatus.NOT_STARTED:
+            self.device_activation()
+
+        return self.http.device_verification_url
+
+    def device_activation(self) -> Self:
+        """Activates the device.
+
+        Caution: this method will block until the device is activated or the timeout is reached.
+        """
+        self.http.device_activation()
+
+        return self
+
+    def get_client(self) -> API.TadoX | API.Tado:
+        """Returns the client instance after device activation."""
+        if self.http.device_activation_status == DeviceActivationStatus.COMPLETED:
+            if self.http.is_x_line:
+                return API.TadoX.from_http(http=self.http, debug=self.debug)
+
+            return API.Tado.from_http(http=self.http, debug=self.debug)
+
+        raise TadoException(
+            "Authentication failed. Please check the device verification URL and try again."
+        )
+
+    def authenticate_and_get_client(self) -> API.TadoX | API.Tado:
+        """Authenticate and get the client instance, prompting for device activation if needed."""
+        print("Starting device activation process...")
+        print("Device activation status: ", self.http.device_activation_status)
+
+        if self.http.device_activation_status != DeviceActivationStatus.COMPLETED:
+            print("Click on the link to log in to your Tado account.")
+            print("Device verification URL: ", self.get_verification_url())
+
+            self.device_activation()
+
+            if (
+                self.http.device_activation_status == DeviceActivationStatus.COMPLETED
+            ):  # pyright: ignore[reportUnnecessaryComparison]
+                print("Device activation completed successfully.")
+            else:
+                raise TadoException(
+                    "Device activation failed. "
+                    "Please check the device verification URL and try again."
+                )
+
+        return self.get_client()