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

python_tado-0.19.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.3
+Name: python-tado
+Version: 0.19.0
+Summary: PyTado from chrism0dwk, modified by w.malgadey, diplix, michaelarnauts, LenhartStephan, splifter, syssi, andersonshatch, Yippy, p0thi, Coffee2CodeNL, chiefdragon, FilBr, nikilase, albertomontesg, Moritz-Schmidt, palazzem
+License: GPL-3.0-or-later
+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.3) ; 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)
+
+## 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.6 → python_tado-0.19.0}/PyTado/__main__.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 
 """Module for querying and controlling Tado smart thermostats."""
 
@@ -54,14 +53,10 @@ def main():
         required=True,
         help=("Tado username in the form of an email address."),
     )
-    required_flags.add_argument(
-        "--password", required=True, help="Tado password."
-    )
+    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 +66,20 @@ 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.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.19.0}/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
@@ -103,4 +96,4 @@ DEFAULT_TADO_PRECISION = 0.1
 DEFAULT_TADOX_PRECISION = 0.01
 
 HOME_DOMAIN = "homes"
-DEVICE_DOMAIN = "devices"
+DEVICE_DOMAIN = "devices"