python-tado 0.18.6__tar.gz → 0.18.8__tar.gz

{python_tado-0.18.6/python_tado.egg-info → python_tado-0.18.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: python-tado
-Version: 0.18.6
+Version: 0.18.8
 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.6 → python_tado-0.18.8}/PyTado/__main__.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 
 """Module for querying and controlling Tado smart thermostats."""
 
@@ -10,31 +9,32 @@ import sys
 from PyTado.interface import Tado
 
 
-def log_in(email, password):
-    t = Tado(email, 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,22 +46,8 @@ 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 = dict(
-        (logging.getLevelName(level), level) for level in [10, 20, 30, 40, 50]
-    )
+    log_levels = {logging.getLevelName(level): level for level in [10, 20, 30, 40, 50]}
     parser.add_argument(
         "--loglevel",
         default="INFO",
@@ -71,30 +57,18 @@ def main():
 
     subparsers = parser.add_subparsers()
 
-    show_config_parser = subparsers.add_parser(
-        "get_me", help="Get home information."
-    )
+    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.add_argument(
-        "--zone", help="Zone to get the state of."
-    )
+    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 = 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.set_defaults(func=get_capabilities)
 
     args = parser.parse_args()

{python_tado-0.18.6 → python_tado-0.18.8}/PyTado/const.py

@@ -1,10 +1,7 @@
 """Constant values for the Tado component."""
 
-# Api credentials
-CLIENT_ID = "tado-web-app"
-CLIENT_SECRET = (
-    "wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc"
-)
+# API client ID
+CLIENT_ID_DEVICE = "1bb50063-6b0c-4d11-bd99-387f4a91cc46"  # nosec B105
 
 # Types
 TYPE_AIR_CONDITIONING = "AIR_CONDITIONING"
@@ -49,12 +46,8 @@ CONST_HORIZONTAL_SWING_MID_RIGHT = "MID_RIGHT"
 CONST_HORIZONTAL_SWING_RIGHT = "RIGHT"
 
 # 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_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