python-tado 0.18.7__tar.gz → 0.18.9__tar.gz

{python_tado-0.18.7/python_tado.egg-info → python_tado-0.18.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: python-tado
-Version: 0.18.7
+Version: 0.18.9
 Summary: PyTado from chrism0dwk, modfied by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem
 Author-email: Chris Jewell <chrism0dwk@gmail.com>, "w.malgadey" <w.malgadey@gmail.com>, FilBr <filippo.barba@protonmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -723,7 +723,7 @@ heating setups.
 
 ---
 
-Original author: Chris Jewell <chrism0dwk@gmail.com>  
+Original author: Chris Jewell <chrism0dwk@gmail.com>
 
 Licence: GPL v3
 
@@ -744,6 +744,58 @@ cause discomfort and inconvenience to others.
     >>> climate = t.get_climate(zone=1)
 
 ## 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:
+
+1. The `_login_device_flow()` will be invoked at the initialization of a PyTado object. This will start the device flow and will return a URL and a code that the user will have to enter in the browser. The URL can be obtained via the method `device_verification_url()`. Or, when in debug mode, the URL will be printed. Alternatively, you can use the `device_activation_status()` method to check if the device has been activated. It returns three statuses: `NOT_STARTED`, `PENDING`, and `COMPLETED`. Wait to invoke the `device_activation()` method until the status is `PENDING`.
+
+2. Once the URL is obtained, the user will have to enter the code that is displayed on the browser into the terminal. By default, the URL has the `user_code` attached, for the ease of going trough the flow. At this point, run the method `device_activation()`. It will poll every five seconds to see if the flow has been completed. If the flow has been completed, the method will return a token that will be used for all further requests. It will timeout after five minutes.
+
+3. Once the token has been obtained, the user can use the PyTado object to interact with the Tado API. The token will be stored in the `Tado` object, and will be used for all further requests. The token will be refreshed automatically when it expires.
+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.18.7 → python_tado-0.18.9}/PyTado/__main__.py

@@ -9,32 +9,32 @@ import sys
 from PyTado.interface import Tado
 
 
-def log_in(username, password):
+def log_in():
     t = Tado()
     t.device_activation()
     return t
 
 
-def get_me(args):
-    t = Tado(args.email, args.password)
+def get_me():
+    t = log_in()
     me = t.get_me()
     print(me)
 
 
 def get_state(args):
-    t = Tado(args.email, args.password)
+    t = log_in()
     zone = t.get_state(int(args.zone))
     print(zone)
 
 
 def get_states(args):
-    t = Tado(args.email, args.password)
+    t = log_in()
     zone = t.get_zone_states()
     print(zone)
 
 
 def get_capabilities(args):
-    t = Tado(args.email, args.password)
+    t = log_in()
     capabilities = t.get_capabilities(int(args.zone))
     print(capabilities)
 
@@ -46,16 +46,6 @@ def main():
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
 
-    required_flags = parser.add_argument_group("required arguments")
-
-    # Required flags go here.
-    required_flags.add_argument(
-        "--email",
-        required=True,
-        help=("Tado username in the form of an email address."),
-    )
-    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]}
     parser.add_argument(

{python_tado-0.18.7 → python_tado-0.18.9}/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
 
@@ -58,6 +62,8 @@ class Mode(enum.Enum):
 
 
 class DeviceActivationStatus(enum.StrEnum):
+    """Device Activation Status Enum"""
+
     NOT_STARTED = "NOT_STARTED"
     PENDING = "PENDING"
     COMPLETED = "COMPLETED"
@@ -142,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/"}
 
@@ -163,24 +187,72 @@ 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()) and 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
@@ -225,8 +297,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(
@@ -283,22 +354,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(
@@ -312,17 +421,48 @@ 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}"
+                f"Failed to refresh token, probably wrong credentials. 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"""
 
@@ -414,6 +554,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

{python_tado-0.18.7 → python_tado-0.18.9}/PyTado/interface/api/hops_tado.py

@@ -3,23 +3,13 @@ PyTado interface implementation for hops.tado.com (Tado X).
 """
 
 import logging
-
 from typing import Any
 
-from .my_tado import Tado, Timetable
-
-from ...logger import Logger
 from ...exceptions import TadoNotSupportedException
-from ...http import (
-    Action,
-    Domain,
-    Http,
-    Mode,
-    TadoRequest,
-    TadoXRequest,
-)
-from ...zone import TadoZone, TadoXZone
-
+from ...http import Action, Domain, Http, Mode, TadoRequest, TadoXRequest
+from ...logger import Logger
+from ...zone import TadoXZone, TadoZone
+from .my_tado import Tado, Timetable
 
 _LOGGER = Logger(__name__)
 
@@ -27,7 +17,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.
     """
@@ -42,9 +33,7 @@ class TadoX(Tado):
         super().__init__(http=http, debug=debug)
 
         if not http.is_x_line:
-            raise TadoNotSupportedException(
-                "TadoX is only usable with LINE_X Generation"
-            )
+            raise TadoNotSupportedException("TadoX is only usable with LINE_X Generation")
 
         if debug:
             _LOGGER.setLevel(logging.DEBUG)
@@ -124,9 +113,7 @@ class TadoX(Tado):
         Gets current capabilities of zone.
         """
 
-        raise TadoNotSupportedException(
-            "This method is not currently supported by the Tado X API"
-        )
+        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
 
     def get_climate(self, zone):
         """
@@ -147,13 +134,9 @@ class TadoX(Tado):
         id = 3 : SEVEN_DAY (MONDAY, TUESDAY, WEDNESDAY ...)
         """
 
-        raise TadoNotSupportedException(
-            "Tado X API only support seven days timetable"
-        )
+        raise TadoNotSupportedException("Tado X API only support seven days timetable")
 
-    def get_schedule(
-        self, zone: int, timetable: Timetable, day=None
-    ) -> dict[str, Any]:
+    def get_schedule(self, zone: int, timetable: Timetable, day=None) -> dict[str, Any]:
         """
         Get the JSON representation of the schedule for a zone.
         Zone has 3 different schedules, one for each timetable (see setTimetable)
@@ -271,9 +254,7 @@ class TadoX(Tado):
         Get current overlay default settings for zone.
         """
 
-        raise TadoNotSupportedException(
-            "Concept of zones is not available by Tado X API, they use rooms"
-        )
+        raise TadoNotSupportedException("Concept of zones is not available by Tado X API, they use rooms")
 
     def get_open_window_detected(self, zone):
         """
@@ -293,18 +274,14 @@ class TadoX(Tado):
         Note: This can only be set if an open window was detected in this zone
         """
 
-        raise TadoNotSupportedException(
-            "This method is not currently supported by the Tado X API"
-        )
+        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
 
     def reset_open_window(self, zone):
         """
         Sets the window in zone to closed
         """
 
-        raise TadoNotSupportedException(
-            "This method is not currently supported by the Tado X API"
-        )
+        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
 
     def get_device_info(self, device_id, cmd=""):
         """

{python_tado-0.18.7 → python_tado-0.18.9}/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.
     """

{python_tado-0.18.7 → python_tado-0.18.9}/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,35 @@ 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 +80,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 +97,30 @@ 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):

{python_tado-0.18.7 → python_tado-0.18.9}/README.md

@@ -13,7 +13,7 @@ heating setups.
 
 ---
 
-Original author: Chris Jewell <chrism0dwk@gmail.com>  
+Original author: Chris Jewell <chrism0dwk@gmail.com>
 
 Licence: GPL v3
 
@@ -34,6 +34,58 @@ cause discomfort and inconvenience to others.
     >>> climate = t.get_climate(zone=1)
 
 ## 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:
+
+1. The `_login_device_flow()` will be invoked at the initialization of a PyTado object. This will start the device flow and will return a URL and a code that the user will have to enter in the browser. The URL can be obtained via the method `device_verification_url()`. Or, when in debug mode, the URL will be printed. Alternatively, you can use the `device_activation_status()` method to check if the device has been activated. It returns three statuses: `NOT_STARTED`, `PENDING`, and `COMPLETED`. Wait to invoke the `device_activation()` method until the status is `PENDING`.
+
+2. Once the URL is obtained, the user will have to enter the code that is displayed on the browser into the terminal. By default, the URL has the `user_code` attached, for the ease of going trough the flow. At this point, run the method `device_activation()`. It will poll every five seconds to see if the flow has been completed. If the flow has been completed, the method will return a token that will be used for all further requests. It will timeout after five minutes.
+
+3. Once the token has been obtained, the user can use the PyTado object to interact with the Tado API. The token will be stored in the `Tado` object, and will be used for all further requests. The token will be refreshed automatically when it expires.
+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.18.7 → python_tado-0.18.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-tado"
-version = "0.18.7"
+version = "0.18.9"
 description = "PyTado from chrism0dwk, modfied by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem"
 authors = [
     { name = "Chris Jewell", email = "chrism0dwk@gmail.com" },
@@ -45,8 +45,8 @@ platforms = ["any"]
 zip-safe = false
 
 [tool.black]
-line-length = 80
-target-version = ['py311']
+line-length = 100
+target-version = ["py311"]
 
 [tool.pytype]
 python_version = '3.11'

{python_tado-0.18.7 → python_tado-0.18.9/python_tado.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: python-tado
-Version: 0.18.7
+Version: 0.18.9
 Summary: PyTado from chrism0dwk, modfied by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem
 Author-email: Chris Jewell <chrism0dwk@gmail.com>, "w.malgadey" <w.malgadey@gmail.com>, FilBr <filippo.barba@protonmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -723,7 +723,7 @@ heating setups.
 
 ---
 
-Original author: Chris Jewell <chrism0dwk@gmail.com>  
+Original author: Chris Jewell <chrism0dwk@gmail.com>
 
 Licence: GPL v3
 
@@ -744,6 +744,58 @@ cause discomfort and inconvenience to others.
     >>> climate = t.get_climate(zone=1)
 
 ## 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:
+
+1. The `_login_device_flow()` will be invoked at the initialization of a PyTado object. This will start the device flow and will return a URL and a code that the user will have to enter in the browser. The URL can be obtained via the method `device_verification_url()`. Or, when in debug mode, the URL will be printed. Alternatively, you can use the `device_activation_status()` method to check if the device has been activated. It returns three statuses: `NOT_STARTED`, `PENDING`, and `COMPLETED`. Wait to invoke the `device_activation()` method until the status is `PENDING`.
+
+2. Once the URL is obtained, the user will have to enter the code that is displayed on the browser into the terminal. By default, the URL has the `user_code` attached, for the ease of going trough the flow. At this point, run the method `device_activation()`. It will poll every five seconds to see if the flow has been completed. If the flow has been completed, the method will return a token that will be used for all further requests. It will timeout after five minutes.
+
+3. Once the token has been obtained, the user can use the PyTado object to interact with the Tado API. The token will be stored in the `Tado` object, and will be used for all further requests. The token will be refreshed automatically when it expires.
+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.18.7 → python_tado-0.18.9}/tests/test_http.py

@@ -1,36 +1,26 @@
 """Test the Http class."""
 
 from datetime import datetime, timedelta
+import io
 import json
-import responses
 import unittest
+from unittest import mock
+import responses
 
 from PyTado.const import CLIENT_ID_DEVICE
 from PyTado.exceptions import TadoException
+from PyTado.http import Domain, Endpoint, Http, TadoRequest
 
 from . import common
 
-from PyTado.http import Http
-
 
 class TestHttp(unittest.TestCase):
-    """Testcases for Http class."""
+    """Test cases for the Http class."""
 
     def setUp(self):
+        """Set up mock responses for HTTP requests."""
         super().setUp()
 
-        # Mock the login response
-        responses.add(
-            responses.POST,
-            "https://auth.tado.com/oauth/token",
-            json={
-                "access_token": "value",
-                "expires_in": 1000,
-                "refresh_token": "another_value",
-            },
-            status=200,
-        )
-
         responses.add(
             responses.POST,
             "https://login.tado.com/oauth2/device_authorize",
@@ -76,7 +66,7 @@ class TestHttp(unittest.TestCase):
 
     @responses.activate
     def test_login_successful(self):
-
+        """Test that login is successful and sets the correct properties."""
         instance = Http(debug=True)
         instance.device_activation()
 
@@ -86,7 +76,7 @@ class TestHttp(unittest.TestCase):
 
     @responses.activate
     def test_login_failed(self):
-
+        """Test that login fails with appropriate exceptions."""
         responses.replace(
             responses.POST,
             "https://login.tado.com/oauth2/token",
@@ -117,7 +107,7 @@ class TestHttp(unittest.TestCase):
 
     @responses.activate
     def test_line_x(self):
-
+        """Test that the we correctly identified new TadoX environments."""
         responses.replace(
             responses.GET,
             "https://my.tado.com/api/v2/homes/1234/",
@@ -136,6 +126,7 @@ class TestHttp(unittest.TestCase):
 
     @responses.activate
     def test_refresh_token_success(self):
+        """Test that the refresh token is successfully updated."""
         instance = Http(debug=True)
         instance.device_activation()
 
@@ -170,6 +161,7 @@ class TestHttp(unittest.TestCase):
 
     @responses.activate
     def test_refresh_token_failure(self):
+        """Test that refresh token failure raises an exception."""
         instance = Http(debug=True)
         instance.device_activation()
 
@@ -188,3 +180,106 @@ class TestHttp(unittest.TestCase):
             instance._refresh_token()
 
         assert refresh_token.call_count == 1
+
+    @responses.activate
+    def test_configure_url_endpoint_mobile(self):
+        """Test URL configuration for the MOBILE endpoint."""
+        http = Http()
+        request = TadoRequest(endpoint=Endpoint.MOBILE, command="test")
+        url = http._configure_url(request)
+        self.assertEqual(url, "https://my.tado.com/mobile/1.9/test")
+
+    @responses.activate
+    def test_configure_url_domain_device(self):
+        """Test URL configuration for the DEVICES domain."""
+        http = Http()
+        request = TadoRequest(command="test", domain=Domain.DEVICES, device="id1234")
+        url = http._configure_url(request)
+        self.assertEqual(url, "https://my.tado.com/api/v2/devices/id1234/test")
+
+    @responses.activate
+    def test_configure_url_domain_me(self):
+        """Test URL configuration for the ME domain."""
+        http = Http()
+        request = TadoRequest(command="test", domain=Domain.ME)
+        url = http._configure_url(request)
+        self.assertEqual(url, "https://my.tado.com/api/v2/me")
+
+    @responses.activate
+    def test_configure_url_domain_home_with_params(self):
+        """Test URL configuration for the ME domain."""
+        http = Http()
+        http._id = 123
+        request = TadoRequest(command="test", domain=Domain.HOME, params={"test": "value"})
+        url = http._configure_url(request)
+        self.assertEqual(url, "https://my.tado.com/api/v2/homes/123/test?test=value")
+
+    @responses.activate
+    @mock.patch("time.sleep", return_value=None)
+    def test_check_device_activation(self, mock_sleep):
+        """Test the device activation check process."""
+
+        http = Http()
+        http._device_flow_data = {"interval": 5, "device_code": "mock_code"}
+        http._expires_at = datetime.now() + timedelta(minutes=5)
+
+        result = http._check_device_activation()
+        self.assertTrue(result)
+        mock_sleep.assert_called_once_with(5)
+
+    @responses.activate
+    def test_save_refresh_token(self):
+        """Test if refresh token is saved."""
+
+        buffer = io.StringIO()
+
+        # We need to disable the `close` method, since we can't call
+        # getvalue() on a closed StringIO object.
+        buffer.close = lambda: None
+
+        mock_open = mock.mock_open()
+        mock_open.return_value = buffer
+
+        with mock.patch("builtins.open", mock_open) as mock_file:
+            http = Http(token_file_path="path/to/open")
+            http._check_device_activation()
+
+        mock_file.assert_called_with("path/to/open", 'w', encoding='utf-8')
+        assert mock_open.return_value.getvalue() == '{"refresh_token": "another_value"}'
+
+
+    @responses.activate
+    @mock.patch('os.path.exists')
+    @mock.patch('PyTado.http.Http._save_token')
+    def test_load_refresh_token(self, mock_save, mock_exists):
+        """Test if token is loaded."""
+        def side_effect(filename):
+            if filename == 'path/to/open':
+                return True
+            else:
+                return False
+        mock_exists.side_effect = side_effect
+
+        with mock.patch("builtins.open", mock.mock_open(read_data='{"refresh_token": "saved_value"}')) as mock_file:
+            http = Http(token_file_path="path/to/open")
+
+        mock_save.assert_called_once()
+        mock_file.assert_called_with("path/to/open", encoding='utf-8')
+        assert http._device_activation_status == "COMPLETED"
+
+    @mock.patch("PyTado.http.Http._refresh_token", return_value=True)
+    @mock.patch("PyTado.http.Http._device_ready")
+    @mock.patch("PyTado.http.Http._load_token")
+    @mock.patch("PyTado.http.Http._login_device_flow")
+    def test_constructor_with_valid_refresh_token(self, mock_load_token, mock_login_device_flow, mock_device_ready, mock_refresh_token):
+        """
+        Test that the Http constructor correctly uses a provided valid refresh token.
+        """
+        refresh_token = "mock_refresh_token"
+
+        Http(saved_refresh_token=refresh_token)
+
+        mock_refresh_token.assert_called_once_with(refresh_token=refresh_token, force_refresh=True)
+        mock_device_ready.assert_called_once()
+        mock_load_token.assert_not_called()
+        mock_login_device_flow.assert_not_called()

{python_tado-0.18.7 → python_tado-0.18.9}/tests/test_tado_interface.py

@@ -79,3 +79,8 @@ class TestTadoInterface(unittest.TestCase):
                 tado_interface.get_me()
 
                 self.assertIn("API Error", str(context.exception))
+
+    def test_get_refresh_token(self):
+        tado = Tado()
+        with mock.patch.object(tado._http, "_token_refresh", new="mock_refresh_token"):
+            self.assertEqual(tado.get_refresh_token(), "mock_refresh_token")