python-tado 0.19.0__tar.gz → 0.19.1__tar.gz

{python_tado-0.19.0 → python_tado-0.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-tado
-Version: 0.19.0
+Version: 0.19.1
 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
 Keywords: tado
@@ -21,7 +21,7 @@ Provides-Extra: all
 Provides-Extra: dev
 Provides-Extra: lint
 Provides-Extra: test
-Requires-Dist: black (>=24.3) ; extra == "lint" or extra == "all"
+Requires-Dist: black (>=24.10) ; extra == "lint" or extra == "all"
 Requires-Dist: pre-commit ; extra == "dev" or extra == "all"
 Requires-Dist: pylint ; extra == "lint" or extra == "all"
 Requires-Dist: pytest ; extra == "test" or extra == "all"
@@ -69,6 +69,7 @@ the GNU Public Licence version 3, and should therefore not be used where it may
 cause discomfort and inconvenience to others.
 
 ## Usage
+
 As of the 15th of March 2025, Tado has updated their OAuth2 authentication flow. It will now use the device flow, instead of a username/password flow. This means that the user will have to authenticate the device using a browser, and then enter the code that is displayed on the browser into the terminal.
 
 PyTado handles this as following:
@@ -81,11 +82,45 @@ PyTado handles this as following:
 The `device_verification_url()` will be reset to `None` and the `device_activation_status()` will return `COMPLETED`.
 
 ### Screenshots of the device flow
+
 ![Tado device flow: invoking](/screenshots/tado-device-flow-0.png)
 ![Tado device flow: browser](/screenshots/tado-device-flow-1.png)
 ![Tado device flow: complete](/screenshots/tado-device-flow-2.png)
 
+### How to not authenticate the device again
+
+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.
+
+```python
+import webbrowser   # only needed for direct web browser access
+
+from PyTado.interface.interface import Tado
+
+tado = Tado(token_file_path="/var/tado/refresh_token")
+
+status = tado.device_activation_status()
+
+if status == "PENDING":
+    url = tado.device_verification_url()
+
+    webbrowser.open_new_tab(url)
+
+    tado.device_activation()
+
+    status = tado.device_activation_status()
+
+if status == "COMPLETED":
+    print("Login successful")
+else:
+    print(f"Login status is {status}")
+```
+
 ## Example code
+
 ```python
 """Example client for PyTado"""
 

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/__main__.py

@@ -9,37 +9,78 @@ import sys
 from PyTado.interface import Tado
 
 
-def log_in(email, password):
-    t = Tado(email, password)
+def log_in(args):
+    """
+    Log in to the Tado API by activating the current device.
+
+    Add --token_file_path to the command line arguments to store the
+    refresh token in a file.
+
+    Args:
+        args (argparse.Namespace): The parsed command-line arguments.
+
+    Returns:
+        Tado: An instance of the Tado interface.
+    """
+    t = Tado(token_file_path=args.token_file_path)
+    t.device_activation()
     return t
 
 
 def get_me(args):
-    t = Tado(args.email, args.password)
+    """
+    Retrieve and print home information from the Tado API.
+
+    Args:
+        args (argparse.Namespace): The parsed command-line arguments.
+    """
+    t = log_in(args)
     me = t.get_me()
     print(me)
 
 
 def get_state(args):
-    t = Tado(args.email, args.password)
+    """
+    Retrieve and print the state of a specific zone from the Tado API.
+
+    Args:
+        args (argparse.Namespace): The parsed command-line arguments.
+    """
+    t = log_in(args)
     zone = t.get_state(int(args.zone))
     print(zone)
 
 
 def get_states(args):
-    t = Tado(args.email, args.password)
-    zone = t.get_zone_states()
-    print(zone)
+    """
+    Retrieve and print the states of all zones from the Tado API.
+
+    Args:
+        args (argparse.Namespace): The parsed command-line arguments.
+    """
+    t = log_in(args)
+    zones = t.get_zone_states()
+    print(zones)
 
 
 def get_capabilities(args):
-    t = Tado(args.email, args.password)
+    """
+    Retrieve and print the capabilities of a specific zone from the Tado API.
+
+    Args:
+        args (argparse.Namespace): The parsed command-line arguments.
+    """
+    t = log_in(args)
     capabilities = t.get_capabilities(int(args.zone))
     print(capabilities)
 
 
 def main():
-    """Main method for the script."""
+    """
+    Main method for the script.
+
+    Sets up the argument parser, handles subcommands, and executes the appropriate function.
+    """
     parser = argparse.ArgumentParser(
         description="Pytado - Tado thermostat device control",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
@@ -49,11 +90,10 @@ def main():
 
     # Required flags go here.
     required_flags.add_argument(
-        "--email",
+        "--token_file_path",
         required=True,
-        help=("Tado username in the form of an email address."),
+        help="Path to the file where the refresh token should be stored.",
     )
-    required_flags.add_argument("--password", required=True, help="Tado password.")
 
     # Flags with default values go here.
     log_levels = {logging.getLevelName(level): level for level in [10, 20, 30, 40, 50]}

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/const.py

@@ -96,4 +96,4 @@ DEFAULT_TADO_PRECISION = 0.1
 DEFAULT_TADOX_PRECISION = 0.01
 
 HOME_DOMAIN = "homes"
-DEVICE_DOMAIN = "devices"
+DEVICE_DOMAIN = "devices"

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/http.py

@@ -5,9 +5,13 @@ Do all the API HTTP heavy lifting in this file
 import enum
 import json
 import logging
+import os
 import pprint
 import time
 from datetime import datetime, timedelta
+from json import dump as json_dump
+from json import load as json_load
+from pathlib import Path
 from typing import Any
 from urllib.parse import urlencode
 
@@ -57,8 +61,9 @@ class Mode(enum.Enum):
     PLAIN = 2
 
 
-class DeviceActivationStatus(enum.Enum):
-    """Device Activation Status Enum"""	
+class DeviceActivationStatus(enum.StrEnum):
+    """Device Activation Status Enum"""
+
     NOT_STARTED = "NOT_STARTED"
     PENDING = "PENDING"
     COMPLETED = "COMPLETED"
@@ -143,16 +148,34 @@ class Http:
 
     def __init__(
         self,
+        token_file_path: str | None = None,
+        saved_refresh_token: str | None = None,
         http_session: requests.Session | None = None,
         debug: bool = False,
     ) -> None:
+        """
+        Initialize the HTTP client for interacting with the Tado API.
+
+        Args:
+            token_file_path (str | None): Path to the file where the token is stored.
+                If None, the token will not be saved to a file.
+            saved_refresh_token (str | None): A previously saved refresh token to use for
+                authentication. If None, a new token will be requested.
+            http_session (requests.Session | None): An optional pre-configured HTTP session.
+                If None, a new session will be created.
+            debug (bool): If True, enables debug logging. Defaults to False.
+
+        Returns:
+            None
+        """
+
         if debug:
             _LOGGER.setLevel(logging.DEBUG)
         else:
             _LOGGER.setLevel(logging.WARNING)
 
         self._refresh_at = datetime.now() + timedelta(minutes=10)
-        self._session = http_session or requests.Session()
+        self._session = http_session or self._create_session()
         self._session.hooks["response"].append(self._log_response)
         self._headers = {"Referer": "https://app.tado.com/"}
 
@@ -164,24 +187,71 @@ class Http:
         self._id: int | None = None
         self._token_refresh: str | None = None
         self._x_api: bool | None = None
-        self._device_activation_status = self._login_device_flow()
+        self._token_file_path = token_file_path
+
+        if saved_refresh_token or self._load_token():
+            if self._refresh_token(refresh_token=saved_refresh_token, force_refresh=True):
+                self._device_ready()
+        else:
+            self._device_activation_status = self._login_device_flow()
 
     @property
     def is_x_line(self) -> bool | None:
+        """
+        Check if the current line is an X line.
+
+        Returns:
+            bool | None: True if the current line is an X line, False otherwise.
+                         None if the api is not ready yet.
+        """
         return self._x_api
 
     @property
     def user_code(self) -> str | None:
+        """
+        Retrieve the user code.
+
+        Returns:
+            str | None: The user code if available, otherwise None.
+        """
         return self._user_code
 
     @property
     def device_activation_status(self) -> DeviceActivationStatus:
+        """
+        Retrieve the activation status of the device.
+
+        Returns:
+            DeviceActivationStatus: The current activation status of the device.
+        """
         return self._device_activation_status
 
     @property
     def device_verification_url(self) -> str | None:
+        """
+        Retrieve the url to activate the device.
+
+        Returns:
+            str | None: The current url for device activation or none if
+                        authentication is not started.
+        """
         return self._device_verification_url
 
+    @property
+    def refresh_token(self) -> str | None:
+        """
+        Retrieve the current refresh token for the tado api connection.
+
+        Returns:
+            str | None: The current refresh token, or None if not available.
+        """
+        return self._token_refresh
+
+    def _create_session(self) -> requests.Session:
+        session = requests.Session()
+        session.hooks["response"].append(self._log_response)
+        return session
+
     def _log_response(self, response: requests.Response, *args, **kwargs) -> None:
         og_request_method = response.request.method
         og_request_url = response.request.url
@@ -226,8 +296,7 @@ class Http:
                 if retries > 0:
                     _LOGGER.warning("Connection error: %s", e)
                     self._session.close()
-                    self._session = requests.Session()
-                    self._session.hooks["response"].append(self._log_response)
+                    self._session = self._create_session()
                     retries -= 1
                 else:
                     _LOGGER.error(
@@ -284,22 +353,60 @@ class Http:
         self._refresh_at = self._refresh_at - timedelta(seconds=30)
 
         self._headers["Authorization"] = f"Bearer {access_token}"
+
+        self._save_token()
+
         return refresh_token
 
-    def _refresh_token(self) -> None:
-        """Refresh the token if it is about to expire"""
-        if self._refresh_at >= datetime.now():
-            return
+    def _load_token(self) -> bool:
+        """Load the refresh token from a file."""
+
+        if not self._token_file_path or not os.path.exists(self._token_file_path):
+            return False
+
+        try:
+            with open(self._token_file_path, encoding="utf-8") as f:
+                data = json_load(f)
+                self._token_refresh = data.get("refresh_token")
+
+            _LOGGER.debug("Refresh token loaded from %s", self._token_file_path)
+
+            return True
+        except (OSError, json.JSONDecodeError) as e:
+            _LOGGER.error("Failed to load refresh token: %s", e)
+            raise TadoException(e) from e
+
+    def _refresh_token(self, refresh_token: str | None = None, force_refresh: bool = False) -> bool:
+        """
+        Refresh the OAuth token if it is about to expire or if forced.
+
+        Args:
+            refresh_token (str | None, optional): The refresh token to use for obtaining a new
+                access token.
+            force_refresh (bool, optional): If True, forces a token refresh regardless of
+                expiration. Defaults to False.
+
+        Returns:
+            bool: True if the token was successfully refreshed, False if the refresh failed due
+                  to invalid credentials.
+
+        Raises:
+            TadoException: If a connection error occurs during the token refresh process.
+            TadoWrongCredentialsException: If the token refresh fails due to invalid credentials
+                and force_refresh is False.
+        """
+
+        if self._refresh_at >= datetime.now() and not force_refresh:
+            return True
 
         url = "https://login.tado.com/oauth2/token"
         data = {
             "client_id": CLIENT_ID_DEVICE,
             "grant_type": "refresh_token",
-            "refresh_token": self._token_refresh,
+            "refresh_token": refresh_token or self._token_refresh,
         }
         self._session.close()
-        self._session = requests.Session()
-        self._session.hooks["response"].append(self._log_response)
+        self._session = self._create_session()
 
         try:
             response = self._session.request(
@@ -313,17 +420,49 @@ class Http:
                     "Referer": "https://app.tado.com/",
                 },
             )
+
         except requests.exceptions.ConnectionError as e:
             _LOGGER.error("Connection error: %s", e)
-            raise TadoException(e)
+            raise TadoException(e) from e
 
         if response.status_code != 200:
+            if force_refresh:
+                _LOGGER.error(
+                    "Failed to refresh token, probably wrong credentials. Status code: %s",
+                    response.status_code,
+                )
+                return False
+
             raise TadoWrongCredentialsException(
-                "Failed to refresh token, probably wrong credentials. " f"Status code: {response.status_code}"
+                "Failed to refresh token, probably wrong credentials. "
+                f"Status code: {response.status_code}"
             )
 
         self._set_oauth_header(response.json())
 
+        return True
+
+    def _save_token(self):
+        """Save the refresh token to a file."""
+        if not self._token_file_path or not self._token_refresh:
+            return
+
+        try:
+            token_dir = os.path.dirname(self._token_file_path)
+            if token_dir and not os.path.exists(token_dir):
+                Path(token_dir).mkdir(parents=True, exist_ok=True)
+
+            with open(self._token_file_path, "w", encoding="utf-8") as f:
+                json_dump(
+                    {"refresh_token": self._token_refresh},
+                    f,
+                )
+
+            _LOGGER.debug("Refresh token saved to %s", self._token_file_path)
+        except Exception as e:
+            _LOGGER.error("Failed to save refresh token: %s", e)
+            raise TadoException(e) from e
+
     def _login_device_flow(self) -> DeviceActivationStatus:
         """Start the login to the API using the device flow"""
 
@@ -352,7 +491,9 @@ class Http:
             raise TadoException(e) from e
 
         if response.status_code != 200:
-            raise TadoException(f"Login failed. Status code: {response.status_code} and reason: {response.reason}")
+            raise TadoException(
+                f"Login failed. Status code: {response.status_code} and reason: {response.reason}"
+            )
 
         self._device_flow_data = response.json()
         _LOGGER.debug("Device flow response: %s", self._device_flow_data)
@@ -375,7 +516,9 @@ class Http:
         return DeviceActivationStatus.PENDING
 
     def _check_device_activation(self) -> bool:
-        if self._expires_at is not None and datetime.timestamp(datetime.now()) > datetime.timestamp(self._expires_at):
+        if self._expires_at is not None and datetime.timestamp(datetime.now()) > datetime.timestamp(
+            self._expires_at
+        ):
             raise TadoException("User took too long to enter key")
 
         # Await the desired interval, before polling the API again
@@ -399,7 +542,10 @@ class Http:
             return True
 
         # The user has not yet authorized the device, let's continue
-        if token_response.status_code == 400 and token_response.json()["error"] == "authorization_pending":
+        if (
+            token_response.status_code == 400
+            and token_response.json()["error"] == "authorization_pending"
+        ):
             _LOGGER.info("Authorization pending, waiting for user to authorize. Continue polling.")
             return False
 
@@ -415,6 +561,10 @@ class Http:
             if self._check_device_activation():
                 break
 
+        self._device_ready()
+
+    def _device_ready(self):
+        """after device refresh code has been obtained"""
         self._id = self._get_id()
         self._x_api = self._check_x_line_generation()
         self._user_code = None
@@ -439,4 +589,4 @@ class Http:
 
         home_ = self.request(request)
 
-        return "generation" in home_ and home_["generation"] == "LINE_X"
+        return "generation" in home_ and home_["generation"] == "LINE_X"

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/interface/api/hops_tado.py

@@ -30,7 +30,8 @@ _LOGGER = Logger(__name__)
 class TadoX(Tado):
     """Interacts with a Tado thermostat via hops.tado.com (Tado X) API.
 
-    Example usage: http = Http('me@somewhere.com', 'mypasswd')
+    Example usage: http = Http()
+                   http.device_activation() # Activate the device
                    t = TadoX(http)
                    t.get_climate(1) # Get climate, room 1.
     """

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/interface/api/my_tado.py

@@ -34,7 +34,8 @@ _LOGGER = Logger(__name__)
 class Tado:
     """Interacts with a Tado thermostat via public my.tado.com API.
 
-    Example usage: http = Http('me@somewhere.com', 'mypasswd')
+    Example usage: http = Http()
+                   http.device_activation() # Activate the device
                    t = Tado(http)
                    t.get_climate(1) # Get climate, zone 1.
     """
@@ -619,4 +620,4 @@ class Tado:
         request.endpoint = Endpoint.MINDER
         request.params = {"from": date}
 
-        return self._http.request(request)
+        return self._http.request(request)

{python_tado-0.19.0 → python_tado-0.19.1}/PyTado/interface/interface.py

@@ -6,12 +6,25 @@ import datetime
 import functools
 import warnings
 
+import requests
+
 import PyTado.interface.api as API
 from PyTado.exceptions import TadoException
 from PyTado.http import DeviceActivationStatus, Http
 
 
 def deprecated(new_func_name):
+    """
+    A decorator to mark functions as deprecated. It will result in a warning being emitted
+    when the function is used, advising the user to use the new function instead.
+
+    Args:
+        new_func_name (str): The name of the new function that should be used instead.
+
+    Returns:
+        function: A decorator that wraps the deprecated function and emits a warning.
+    """
+
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
@@ -31,18 +44,34 @@ def deprecated(new_func_name):
 class Tado:
     """Interacts with a Tado thermostat via public API.
 
-    Example usage: t = Tado('me@somewhere.com', 'mypasswd')
+    Example usage: t = Tado()
+                   t.device_activation() # Activate device
                    t.get_climate(1) # Get climate, zone 1.
     """
 
     def __init__(
         self,
-        http_session=None,
+        token_file_path: str | None = None,
+        saved_refresh_token: str | None = None,
+        http_session: requests.Session | None = None,
         debug: bool = False,
     ):
-        """Class Constructor"""
+        """
+        Initializes the interface class.
+
+        Args:
+            token_file_path (str | None, optional): Path to a file which will be used to persist
+                the refresh_token token. Defaults to None.
+            saved_refresh_token (str | None, optional): A previously saved refresh token.
+                Defaults to None.
+            http_session (requests.Session | None, optional): An optional HTTP session to use for
+                requests (can be used in unit tests). Defaults to None.
+            debug (bool, optional): Flag to enable or disable debug mode. Defaults to False.
+        """
 
         self._http = Http(
+            token_file_path=token_file_path,
+            saved_refresh_token=saved_refresh_token,
             http_session=http_session,
             debug=debug,
         )
@@ -50,16 +79,12 @@ class Tado:
         self._debug = debug
 
     def __getattr__(self, name):
-        """Delegiert den Aufruf von Methoden an die richtige API-Client-Implementierung."""
+        """Delegate the called method to api implementation (hops_tado.py or my_tado.py)."""
 
-        if self._api is None:
-            raise TadoException("API is not initialized. Please complete device authentication first.")
+        self._ensure_api_initialized()
 
         return getattr(self._api, name)
 
-    # region Deprecated Methods
-    # pylint: disable=invalid-name
-
     def device_verification_url(self) -> str | None:
         """Returns the URL for device verification."""
         return self._http.device_verification_url
@@ -71,12 +96,32 @@ class Tado:
     def device_activation(self) -> None:
         """Activates the device."""
         self._http.device_activation()
+        self._ensure_api_initialized()
+
+    def get_refresh_token(self) -> str | None:
+        """
+        Retrieve the refresh token from the current api connection.
+
+        Returns:
+            str | None: The current refresh token, or None if not available.
+        """
+        return self._http.refresh_token
 
-        if self._http.device_activation_status == DeviceActivationStatus.COMPLETED:
-            if self._http.is_x_line:
-                self._api = API.TadoX(http=self._http, debug=self._debug)
+    def _ensure_api_initialized(self):
+        """Ensures the API client is initialized."""
+        if self._api is None:
+            if self._http.device_activation_status == DeviceActivationStatus.COMPLETED:
+                if self._http.is_x_line:
+                    self._api = API.TadoX(http=self._http, debug=self._debug)
+                else:
+                    self._api = API.Tado(http=self._http, debug=self._debug)
             else:
-                self._api = API.Tado(http=self._http, debug=self._debug)
+                raise TadoException(
+                    "API is not initialized. Please complete device authentication first."
+                )
+
+    # region Deprecated Methods
+    # pylint: disable=invalid-name
 
     @deprecated("get_me")
     def getMe(self):
@@ -317,4 +362,4 @@ class Tado:
         )
 
     # pylint: enable=invalid-name
-    # endregion
+    # endregion

{python_tado-0.19.0 → python_tado-0.19.1}/README.md

@@ -30,6 +30,7 @@ the GNU Public Licence version 3, and should therefore not be used where it may
 cause discomfort and inconvenience to others.
 
 ## Usage
+
 As of the 15th of March 2025, Tado has updated their OAuth2 authentication flow. It will now use the device flow, instead of a username/password flow. This means that the user will have to authenticate the device using a browser, and then enter the code that is displayed on the browser into the terminal.
 
 PyTado handles this as following:
@@ -42,11 +43,45 @@ PyTado handles this as following:
 The `device_verification_url()` will be reset to `None` and the `device_activation_status()` will return `COMPLETED`.
 
 ### Screenshots of the device flow
+
 ![Tado device flow: invoking](/screenshots/tado-device-flow-0.png)
 ![Tado device flow: browser](/screenshots/tado-device-flow-1.png)
 ![Tado device flow: complete](/screenshots/tado-device-flow-2.png)
 
+### How to not authenticate the device again
+
+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.
+
+```python
+import webbrowser   # only needed for direct web browser access
+
+from PyTado.interface.interface import Tado
+
+tado = Tado(token_file_path="/var/tado/refresh_token")
+
+status = tado.device_activation_status()
+
+if status == "PENDING":
+    url = tado.device_verification_url()
+
+    webbrowser.open_new_tab(url)
+
+    tado.device_activation()
+
+    status = tado.device_activation_status()
+
+if status == "COMPLETED":
+    print("Login successful")
+else:
+    print(f"Login status is {status}")
+```
+
 ## Example code
+
 ```python
 """Example client for PyTado"""
 

{python_tado-0.19.0 → python_tado-0.19.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "python-tado"
-version = "0.19.0"
+version = "0.19.1"
 description = "PyTado from chrism0dwk, modified by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem"
 authors = [
   "Chris Jewell <chrism0dwk@gmail.com>",
@@ -32,7 +32,7 @@ repository = "https://github.com/wmalgadey/PyTado"
 [tool.poetry.dependencies]
 python = ">=3.11"
 requests = "*"
-black = ">=24.3"
+black = ">=24.10"
 pylint = "*"
 pre-commit = "*"
 pytype = "*"
@@ -66,7 +66,7 @@ source = ["PyTado"]
 [tool.black]
 line-length = 100
 target-version = ["py311"]
-required-version = "24.3.0"
+required-version = "24.10.0"
 
 [tool.bandit]
 exclude_dirs = ["tests"]