chore: Setup tox

.env.template

@@ -1,3 +1,3 @@
 TADO_USERNAME=""
 TADO_PASSWORD=""
-TADO_CLIENT_SECRET="wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc"
+TADO_CLIENT_SECRET="wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc"

.gitignore

@@ -92,4 +92,7 @@ ENV/
 # Custom
 test.py
 gitchangelog.py
-.pytest_cache
+.pytest_cache
+
+# Mkdocs
+output/

.readthedocs.yml

@@ -1,16 +1,11 @@
 ---
 version: 2
 
-sphinx:
-  builder: html
-  configuration: docs/source/conf.py
-
-formats:
-  - htmlzip
-  - pdf
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
 
 python:
   version: 3.8
   install:
-    - method: pip
-      path: .
+    - requirements: docs/requirements.txt

.yamllint

@@ -0,0 +1 @@
+

Pipfile

@@ -12,6 +12,7 @@ python-dotenv = "*"
 pytest = "*"
 pytest-dotenv = "*"
 python-dateutil = "*"
+mkdocs-material = "*"
 
 [packages]
 click = "*"

check.py

@@ -2,17 +2,21 @@
 import os
 from libtado.api import Tado
 
+from dotenv import load_dotenv
+load_dotenv()
 
-TADO_USERNAME = os.getenv("TADO_USERNAME")
-TADO_PASSWORD = os.getenv("TADO_PASSWORD")
-TADO_CLIENT_SECRET = os.getenv("TADO_CLIENT_SECRET")
+
+TADO_USERNAME = os.environ["TADO_USERNAME"]
+TADO_PASSWORD = os.environ["TADO_PASSWORD"]
+TADO_CLIENT_SECRET = os.environ["TADO_CLIENT_SECRET"]
 
 tado = Tado(TADO_USERNAME, TADO_PASSWORD, TADO_CLIENT_SECRET)
 
 # print(tado.get_me())
-# print(tado.get_home())
+print(tado.get_home())
+print(tado.get_invitations())
 # print(tado.get_zones())
 # print(tado.get_state(1))
 # print(tado.get_mobile_devices())
 # print(tado.get_energy_consumption("2022-09-01", "2022-09-30", "FRA", True))
-print(tado.get_energy_savings("2022-09", "FRA"))
+# print(tado.get_energy_savings("2022-09", "FRA"))

docs/api/reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: libtado.api.Tado

docs/api/usage.md

@@ -0,0 +1,9 @@
+# API Usage
+
+Usage:
+
+``` { .python .select .copy }
+import tado.api
+
+api = tado.api('Username', 'Password')
+```

docs/cli/configuration.md

@@ -0,0 +1,18 @@
+# CLI Configuration
+
+## Configuration File
+
+There is no configuration file. No need.
+
+## Environment Variables
+
+The following environment variables are supported:
+
+* `TADO_USERNAME` - Tado username
+* `TADO_PASSWORD` - Tado password
+* `TADO_CLIENT_SECRET` - Tado client secret
+
+Environment variables can be set up in multiples ways:
+
+* System environment variables
+* File `.env` in the current directory

docs/cli/reference.md

@@ -0,0 +1,8 @@
+# CLI Reference
+
+::: mkdocs-click
+    :module: libtado.__main__
+    :command: main
+    :prog_name: tado
+    :depth: 1
+    :list_subcommands: True

docs/source/cli.rst → docs/cli/usage.md

@@ -1,12 +1,15 @@
-.. _cli:
+# CLI Usage
 
-=======================
-Command Line Client
-=======================
+Usage:
 
-::
+``` {.bash .select .copy}
+tado --help
+```
 
-  Usage: tado [OPTIONS] COMMAND [ARGS]...
+Output:
+
+``` raw
+Usage: tado [OPTIONS] COMMAND [ARGS]...
 
     This script provides a command line client for the Tado API.
 
@@ -15,13 +18,13 @@ Command Line Client
 
     Call 'tado COMMAND --help' to see available options for subcommands.
 
-  Options:
+Options:
     -u, --username TEXT       Tado username  [required]
     -p, --password TEXT       Tado password  [required]
     -c, --client-secret TEXT  Tado password  [optional]
     -h, --help                Show this message and exit.
 
-  Commands:
+Commands:
     capabilities        Display the capabilities of a zone.
     devices             Display all devices.
     early_start         Display or change the early start feature of a zone.
@@ -33,3 +36,4 @@ Command Line Client
     whoami              Tell me who the Tado API thinks I am.
     zone                Get the current state of a zone.
     zones               Get configuration information about all zones.
+```

docs/contributing.md

@@ -0,0 +1,60 @@
+# Contributing
+
+You can download the library sources at
+<https://github.com/germainlefebvre4/libtado>:
+
+```bash
+git clone https://github.com/germainlefebvre4/libtado.git
+```
+
+## Requirements
+
+The library development requires at least python `3.7`.
+
+This library is tested with following python versions:
+
+- `3.7`
+- `3.8`
+
+## Setup
+
+Update your system and install a python version (at least the minimum required) and install the python virtualenv tool
+`pipenv` (or `poetry`).
+
+```bash
+sudo apt update
+sudo apt install python3.7 python3.7-pip
+sudo pip install pipenv
+# sudo pip install poetry
+```
+
+Initialize your `pipenv` (or `poetry`) setup and install all the development libraries.
+
+```bash
+pipenv update --dev
+# poetry install
+```
+
+## Improve the library
+
+The library is served through 2 sections:
+
+- API in `./libtado/api.py`
+- CLI in `./libtado/cli.py`
+
+## Write and run some tests
+
+Unit tests are important for the developement team because it adds strenghtness and confidence to the code.
+
+The tests are written in the following files:
+
+- Global Tado in `./tests/global/test_tado.py`
+- Library API in `./tests/api/test_api.py`
+- Library CLI in `./tests/cli/test_cli.py`
+
+Run the tests inside `pipenv` or `poetry`.
+
+```bash
+pipenv run pytest -sv tests/
+# poetry run pytest -sv tests/
+```

docs/source/faq.rst → docs/faq.md

@@ -1,32 +1,28 @@
-.. _faq:
+# FAQ
 
-==========================
-Frequently Asked Questions
-==========================
+## How to retrieve the client secret
 
-*********************************
-How to retrieve the client secret
-*********************************
-
-**Option #1: Do nothing**
+### Option #1: Do nothing
 
 The library wil automatically retrieve the client secret on following the steps at *Options #2*.
 
-**Option #2: From the application `env.js`**
+### Option #2: From the application `env.js`
 
-Retrieve the `CLIENT_SECRET` before running the script otherwise you will get a `401 Unauthorized Access`.
-The latest `CLIENT_SECRET` can be found at [https://my.tado.com/webapp/env.js](https://my.tado.com/webapp/env.js).  It will look something like this:
+Retrieve the `CLIENT_SECRET` before running the script otherwise you will get a `401 Unauthorized Access`. The latest `CLIENT_SECRET` can be found at \[<https://my.tado.com/webapp/env.js>\](<https://my.tado.com/webapp/env.js>). It will look something like this:
 
-**Option #3: From the developer mode**
+### Option #3: From the developer mode
 
-An alternative way to get your `CLIENT_SECRET` is to enable the Developper Mode when logging in and catch the Headers. You will find the form data like this :
-::
+An alternative way to get your `CLIENT_SECRET` is to enable the Developper Mode when logging in and catch the Headers. You will find the form data like this:
 
+```json
+{
     client_id: tado-web-app
     client_secret: fndskjnjzkefjNFRNkfKJRNFKRENkjnrek
     grant_type: password
     password: MyBeautifulPassword
     scope: home.user
     username: email@example.com
+}
+```
 
 Then you just have to get the value in the attribute `client_secret`. You will need it to connect to your account through Tado APIs. The `client_secret` never dies so you can base your script on it.

docs/getting-started/installation.md

@@ -0,0 +1,10 @@
+# Installation
+
+You can download the official library on Pypi using `pip` or `poetry`.
+
+```bash
+pip install libtado
+# poetry add libtado
+```
+
+It cannot be easier ;)

docs/getting-started/references.md

@@ -0,0 +1,8 @@
+# References
+
+You can interact with the librairy using the following approaches:
+
+* [Command Line Interface (CLI)](../cli/usage.md)
+    * [CLI Reference](../cli/reference.md)
+* [Python API](../api/usage.md)
+    * [API Reference](../api/reference.md)

docs/getting-started/usage.md

@@ -0,0 +1,17 @@
+# Usage
+
+After you installed libtado you can easily test it by using the included [`cli`](../cli/usage.md) like this:
+
+``` { shell .copy }
+tado --username USERNAME --password PASSWORD whoami
+```
+
+To use the library in your own code you can start with this:
+
+``` python
+import tado.api
+t = tado.api('Username', 'Password')
+print(t.get_me())
+```
+
+Check out `all available API methods <api>` to learn what you can to with libtado.

docs/index.md

@@ -0,0 +1,25 @@
+# Homepage
+
+![Image title](./logo.png){: .center width=600 }
+
+**libtado** is a simple Python library that provides methods to control the smart heating devices from the German company [tado GmbH](https://www.tado.com)[^1]. It uses the undocumented REST API of their website.
+
+The library is in NO way connected to tado GmbH and is not officially supported by them!
+
+The source code is hosted on [GitHub](https://github.com/germainlefebvre4/libtado)[^2]. Feel free to report issues or open pull requests.
+
+## License
+
+> Copyright © 2023 Germain Lefebvre, Max Rosin
+>
+> This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+>
+> This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+>
+> You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+## References
+
+[^1]: [https://www.tado.com](https://www.tado.com)
+
+[^2]: [https://github.com/germainlefebvre4/libtado](https://github.com/germainlefebvre4/libtado)

docs/requirements.txt

@@ -0,0 +1,10 @@
+requests
+click
+mkdocs
+mkdocs-autorefs
+mkdocs-click
+mkdocs-material
+mkdocs-material-extensions
+mkdocstrings
+mkdocstrings-python
+typing-extensions