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

python_tado-0.19.1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.3
+Name: python-tado
+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
+Author: Chris Jewell
+Author-email: chrism0dwk@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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: pylint ; extra == "lint" or extra == "all"
+Requires-Dist: pytest ; extra == "test" or extra == "all"
+Requires-Dist: pytest-cov ; extra == "test" or extra == "all"
+Requires-Dist: pytest-mock ; extra == "test" or extra == "all"
+Requires-Dist: pytest-socket ; extra == "test" or extra == "all"
+Requires-Dist: pytype ; extra == "dev" or extra == "all"
+Requires-Dist: requests
+Requires-Dist: responses ; extra == "test" or extra == "all"
+Requires-Dist: types-requests ; extra == "dev" or extra == "all"
+Project-URL: Documentation, https://wmalgadey.github.io/PyTado/
+Project-URL: Homepage, https://github.com/wmalgadey/PyTado
+Project-URL: Repository, https://github.com/wmalgadey/PyTado
+Description-Content-Type: text/markdown
+
+# PyTado -- Pythonize your central heating
+
+[![Linting and testing](https://github.com/wmalgadey/PyTado/actions/workflows/lint-and-test-matrix.yml/badge.svg)](https://github.com/wmalgadey/PyTado/actions/workflows/lint-and-test-matrix.yml)
+[![Build and deploy to pypi](https://github.com/wmalgadey/PyTado/actions/workflows/publish-to-pypi.yml/badge.svg?event=release)](https://github.com/wmalgadey/PyTado/actions/workflows/publish-to-pypi.yml)
+[![PyPI version](https://badge.fury.io/py/python-tado.svg)](https://badge.fury.io/py/python-tado)
+[![codecov](https://codecov.io/github/wmalgadey/PyTado/graph/badge.svg?token=14TT00IWJI)](https://codecov.io/github/wmalgadey/PyTado)
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+PyTado is a Python module implementing an interface to the Tado web API. It allows a user to interact with their
+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
+heating setups.
+
+---
+
+Original author: Chris Jewell <chrism0dwk@gmail.com>
+
+Licence: GPL v3
+
+Copyright: Chris Jewell 2016-2018
+
+## Disclaimer
+
+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
+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:
+
+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"""
+
+from PyTado.interface.interface import Tado
+
+
+def main() -> None:
+    """Retrieve all zones, once successfully logged in"""
+    tado = Tado()
+
+    print("Device activation status: ", tado.device_activation_status())
+    print("Device verification URL: ", tado.device_verification_url())
+
+    print("Starting device activation")
+    tado.device_activation()
+
+    print("Device activation status: ", tado.device_activation_status())
+
+    zones = tado.get_zones()
+    print(zones)
+
+
+if __name__ == "__main__":
+    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!
+
+You don't need to be a Python expert to provide meaningful improvements. To learn how to get started, check out our
+[Contributor Guidelines](https://github.com/wmalgadey/econnect-python/blob/main/CONTRIBUTING.md) first, and ask for help
+in [GitHub Discussions](https://github.com/wmalgadey/PyTado/discussions) if you have questions.
+
+## Development
+
+We welcome external contributions, even though the project was initially intended for personal use. If you think some
+parts could be exposed with a more generic interface, please open a [GitHub issue](https://github.com/wmalgadey/PyTado/issues)
+to discuss your suggestion.
+
+### Setting up a devcontainer
+
+The easiest way to start, is by opening a CodeSpace here on GitHub, or by using
+the [Dev Container][devcontainer] feature of Visual Studio Code.
+
+[![Open in Dev Containers][devcontainer-shield]][devcontainer]
+
+### Dev Environment
+
+To contribute to this repository, you should first clone your fork and then setup your development environment. Clone
+your repository as follows (replace yourusername with your GitHub account name):
+
+```bash
+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
+```
+
+### Coding Guidelines
+
+To maintain a consistent codebase, we utilize [black][1]. Consistency is crucial as it helps readability, reduces errors,
+and facilitates collaboration among developers.
+
+To ensure that every commit adheres to our coding standards, we've integrated [pre-commit hooks][2]. These hooks
+automatically run `black` before each commit, ensuring that all code changes are automatically checked and formatted.
+
+For details on how to set up your development environment to make use of these hooks, please refer to the
+[Development][3] section of our documentation.
+
+[1]: https://github.com/ambv/black
+[2]: https://pre-commit.com/
+[3]: https://github.com/wmalgadey/PyTado#development
+
+### Testing
+
+Ensuring the robustness and reliability of our code is paramount. Therefore, all contributions must include at least one
+test to verify the intended behavior.
+
+To run tests locally, execute the test suite using `pytest` with the following command:
+
+```bash
+pytest tests/ --cov --cov-branch -vv
+```
+
+---
+
+A message from the original author:
+
+> This software is at a purely experimental stage. If you're interested and can write Python, clone the Github repo,
+> drop me a line, and get involved!
+>
+> Best wishes and a warm winter to all!
+>
+> 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-0.18.9 → python_tado-0.19.1}/PyTado/__main__.py

@@ -9,43 +9,92 @@ import sys
 from PyTado.interface import Tado
 
 
-def log_in():
-    t = Tado()
+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():
-    t = log_in()
+def get_me(args):
+    """
+    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 = log_in()
+    """
+    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 = log_in()
-    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 = log_in()
+    """
+    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,
     )
 
+    required_flags = parser.add_argument_group("required arguments")
+
+    # Required flags go here.
+    required_flags.add_argument(
+        "--token_file_path",
+        required=True,
+        help="Path to the file where the refresh token should be stored.",
+    )
+
     # Flags with default values go here.
     log_levels = {logging.getLevelName(level): level for level in [10, 20, 30, 40, 50]}
     parser.add_argument(
@@ -67,7 +116,9 @@ def main():
     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 = 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)
 

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

@@ -159,8 +159,8 @@ class Http:
         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.
+            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.
@@ -189,10 +189,9 @@ class Http:
         self._x_api: bool | None = None
         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()
+        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()
 
@@ -383,9 +382,9 @@ class Http:
 
         Args:
             refresh_token (str | None, optional): The refresh token to use for obtaining a new
-                                                  access token.
+                access token.
             force_refresh (bool, optional): If True, forces a token refresh regardless of
-                                            expiration. Defaults to False.
+                expiration. Defaults to False.
 
         Returns:
             bool: True if the token was successfully refreshed, False if the refresh failed due
@@ -394,7 +393,7 @@ class Http:
         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.
+                and force_refresh is False.
         """
 
         if self._refresh_at >= datetime.now() and not force_refresh:
@@ -435,7 +434,8 @@ class Http:
                 return False
 
             raise TadoWrongCredentialsException(
-                f"Failed to refresh token, probably wrong credentials. Status code: {response.status_code}"
+                "Failed to refresh token, probably wrong credentials. "
+                f"Status code: {response.status_code}"
             )
 
         self._set_oauth_header(response.json())
@@ -491,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)
@@ -514,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
@@ -538,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
 

{python_tado-0.18.9 → python_tado-0.19.1}/PyTado/interface/__init__.py

@@ -1,3 +1,5 @@
 """Abstraction layer for API implementation."""
 
 from .interface import Tado
+
+__all__ = ["Tado"]

{python_tado-0.18.9 → python_tado-0.19.1}/PyTado/interface/api/__init__.py

@@ -2,3 +2,5 @@
 
 from .hops_tado import TadoX
 from .my_tado import Tado
+
+__all__ = ["Tado", "TadoX"]

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

@@ -2,6 +2,7 @@
 PyTado interface implementation for hops.tado.com (Tado X).
 """
 
+import functools
 import logging
 from typing import Any
 
@@ -11,6 +12,18 @@ from ...logger import Logger
 from ...zone import TadoXZone, TadoZone
 from .my_tado import Tado, Timetable
 
+
+def not_supported(reason):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            raise TadoNotSupportedException(f"{func.__name__} is not supported: {reason}")
+
+        return wrapper
+
+    return decorator
+
+
 _LOGGER = Logger(__name__)
 
 
@@ -60,9 +73,13 @@ class TadoX(Tado):
         devices = [device for room in rooms for device in room["devices"]]
 
         for device in devices:
+            serial_number = device.get("serialNo", device.get("serialNumber"))
+            if not serial_number:
+                continue
+
             request = TadoXRequest()
             request.domain = Domain.DEVICES
-            request.device = device["serialNo"]
+            request.device = serial_number
             device.update(self._http.request(request))
 
         if "otherDevices" in rooms_and_devices:
@@ -108,12 +125,12 @@ class TadoX(Tado):
 
         return data
 
+    @not_supported("This method is not currently supported by the Tado X API")
     def get_capabilities(self, zone):
         """
         Gets current capabilities of zone.
         """
-
-        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
+        pass
 
     def get_climate(self, zone):
         """
@@ -126,6 +143,7 @@ class TadoX(Tado):
             "humidity": data["humidity"]["percentage"],
         }
 
+    @not_supported("Tado X API only support seven days timetable")
     def set_timetable(self, zone: int, timetable: Timetable) -> None:
         """
         Set the Timetable type currently active
@@ -133,8 +151,7 @@ class TadoX(Tado):
         id = 1 : THREE_DAY (MONDAY_TO_FRIDAY, SATURDAY, SUNDAY)
         id = 3 : SEVEN_DAY (MONDAY, TUESDAY, WEDNESDAY ...)
         """
-
-        raise TadoNotSupportedException("Tado X API only support seven days timetable")
+        pass
 
     def get_schedule(self, zone: int, timetable: Timetable, day=None) -> dict[str, Any]:
         """
@@ -249,12 +266,12 @@ class TadoX(Tado):
 
         return self._http.request(request)
 
+    @not_supported("Concept of zones is not available by Tado X API, they use rooms")
     def get_zone_overlay_default(self, zone: int):
         """
         Get current overlay default settings for zone.
         """
-
-        raise TadoNotSupportedException("Concept of zones is not available by Tado X API, they use rooms")
+        pass
 
     def get_open_window_detected(self, zone):
         """
@@ -273,15 +290,21 @@ class TadoX(Tado):
         Sets the window in zone to open
         Note: This can only be set if an open window was detected in this zone
         """
+        request = TadoXRequest()
+        request.command = f"rooms/{zone}/openWindow"
+        request.action = Action.SET
 
-        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
+        return self._http.request(request)
 
     def reset_open_window(self, zone):
         """
         Sets the window in zone to closed
         """
+        request = TadoXRequest()
+        request.command = f"rooms/{zone}/openWindow"
+        request.action = Action.RESET
 
-        raise TadoNotSupportedException("This method is not currently supported by the Tado X API")
+        return self._http.request(request)
 
     def get_device_info(self, device_id, cmd=""):
         """
@@ -324,3 +347,30 @@ class TadoX(Tado):
         request.payload = {"childLockEnabled": child_lock}
 
         self._http.request(request)
+
+    def set_flow_temperature_optimization(self, max_flow_temperature: float):
+        """
+        Set the flow temperature optimization.
+
+        max_flow_temperature: float, the maximum flow temperature in Celsius
+        """
+
+        request = TadoXRequest()
+        request.action = Action.CHANGE
+        request.domain = Domain.HOME
+        request.command = "settings/flowTemperatureOptimization"
+        request.payload = {"maxFlowTemperature": max_flow_temperature}
+
+        return self._http.request(request)
+
+    def get_flow_temperature_optimization(self):
+        """
+        Get the current flow temperature optimization
+        """
+
+        request = TadoXRequest()
+        request.action = Action.GET
+        request.domain = Domain.HOME
+        request.command = "settings/flowTemperatureOptimization"
+
+        return self._http.request(request)

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

@@ -61,12 +61,11 @@ class Tado:
 
         Args:
             token_file_path (str | None, optional): Path to a file which will be used to persist
-                                                    the refresh_token token. Defaults to None.
+                the refresh_token token. Defaults to None.
             saved_refresh_token (str | None, optional): A previously saved refresh token.
-                                                        Defaults to None.
+                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.
+                requests (can be used in unit tests). Defaults to None.
             debug (bool, optional): Flag to enable or disable debug mode. Defaults to False.
         """
 
@@ -117,7 +116,9 @@ class Tado:
                 else:
                     self._api = API.Tado(http=self._http, debug=self._debug)
             else:
-                raise TadoException("API is not initialized. Please complete device authentication first.")
+                raise TadoException(
+                    "API is not initialized. Please complete device authentication first."
+                )
 
     # region Deprecated Methods
     # pylint: disable=invalid-name

python_tado-0.19.1/PyTado/logger.py

@@ -0,0 +1,24 @@
+"""
+This file contains anything related to logging
+"""
+
+import logging
+
+
+class Logger(logging.Logger):
+    """
+    This class provides a custom logger without masking sensitive information.
+    """
+
+    class SimpleFormatter(logging.Formatter):
+        """
+        Simple formatter that does not remove any information in logs.
+        """
+
+    def __init__(self, name: str, level=logging.NOTSET):
+        super().__init__(name)
+        log_sh = logging.StreamHandler()
+        log_fmt = self.SimpleFormatter(fmt="%(name)s :: %(levelname)-8s :: %(message)s")
+        log_sh.setFormatter(log_fmt)
+        self.addHandler(log_sh)
+        self.setLevel(level)

{python_tado-0.18.9 → python_tado-0.19.1}/PyTado/zone/__init__.py

@@ -2,3 +2,5 @@
 
 from .hops_zone import TadoXZone
 from .my_zone import TadoZone
+
+__all__ = ["TadoZone", "TadoXZone"]