aiomoulinex 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,126 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # OSX useful to ignore
7
+ *.DS_Store
8
+ .AppleDouble
9
+ .LSOverride
10
+
11
+ # Thumbnails
12
+ ._*
13
+
14
+ # Files that might appear in the root of a volume
15
+ .DocumentRevisions-V100
16
+ .fseventsd
17
+ .Spotlight-V100
18
+ .TemporaryItems
19
+ .Trashes
20
+ .VolumeIcon.icns
21
+ .com.apple.timemachine.donotpresent
22
+
23
+ # Directories potentially created on remote AFP share
24
+ .AppleDB
25
+ .AppleDesktop
26
+ Network Trash Folder
27
+ Temporary Items
28
+ .apdisk
29
+
30
+ # C extensions
31
+ *.so
32
+
33
+ # Distribution / packaging
34
+ .Python
35
+ env/
36
+ build/
37
+ develop-eggs/
38
+ dist/
39
+ downloads/
40
+ eggs/
41
+ .eggs/
42
+ lib/
43
+ lib64/
44
+ parts/
45
+ sdist/
46
+ var/
47
+ *.egg-info/
48
+ .installed.cfg
49
+ *.egg
50
+
51
+ # PyInstaller
52
+ # Usually these files are written by a python script from a template
53
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
54
+ *.manifest
55
+ *.spec
56
+
57
+ # Installer logs
58
+ pip-log.txt
59
+ pip-delete-this-directory.txt
60
+
61
+ # Unit test / coverage reports
62
+ htmlcov/
63
+ .tox/
64
+ .coverage
65
+ .coverage.*
66
+ .cache
67
+ nosetests.xml
68
+ coverage.xml
69
+ *,cover
70
+ .hypothesis/
71
+ .pytest_cache/
72
+
73
+ # Translations
74
+ *.mo
75
+ *.pot
76
+
77
+ # Django stuff:
78
+ *.log
79
+
80
+ # Sphinx documentation
81
+ docs/_build/
82
+
83
+ # pyenv
84
+ .python-version
85
+
86
+ # virtualenv
87
+ .venv
88
+ venv/
89
+ ENV/
90
+
91
+ # mypy
92
+ .mypy_cache/
93
+
94
+ # ruff
95
+ .ruff_cache
96
+
97
+ # Visual Studio Code
98
+ .vscode
99
+
100
+ # IntelliJ Idea family of suites
101
+ .idea
102
+ *.iml
103
+
104
+ ## File-based project format:
105
+ *.ipr
106
+ *.iws
107
+
108
+ ## mpeltonen/sbt-idea plugin
109
+ .idea_modules/
110
+
111
+ # PyBuilder
112
+ target/
113
+
114
+ # Cookiecutter
115
+ output/
116
+ python_boilerplate/
117
+
118
+ # Node
119
+ node_modules/
120
+
121
+ # Deepcode AI
122
+ .dccache
123
+
124
+ # Login token and captures of scripts/debug.py
125
+ .env
126
+ *.jsonl
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paul Bottein
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,236 @@
1
+ Metadata-Version: 2.5
2
+ Name: aiomoulinex
3
+ Version: 0.1.0
4
+ Summary: Asynchronous Python client for the Moulinex Cookeo and Companion connected through the Groupe SEB cloud
5
+ Project-URL: Homepage, https://github.com/piitaya/python-moulinex
6
+ Project-URL: Repository, https://github.com/piitaya/python-moulinex
7
+ Project-URL: Documentation, https://github.com/piitaya/python-moulinex
8
+ Project-URL: Bug Tracker, https://github.com/piitaya/python-moulinex/issues
9
+ Project-URL: Changelog, https://github.com/piitaya/python-moulinex/releases
10
+ Author-email: Paul Bottein <paul.bottein@gmail.com>
11
+ Maintainer-email: Paul Bottein <paul.bottein@gmail.com>
12
+ License-Expression: MIT
13
+ License-File: LICENSE.md
14
+ Keywords: asyncio,companion,cookeo,groupe seb,moulinex,mqtt,tefal
15
+ Classifier: Development Status :: 4 - Beta
16
+ Classifier: Framework :: AsyncIO
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Natural Language :: English
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Home Automation
23
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: <4,>=3.13
26
+ Requires-Dist: aiohttp>=3.11.0
27
+ Requires-Dist: aiomqtt>=2.5.0
28
+ Requires-Dist: yarl>=1.18.0
29
+ Description-Content-Type: text/markdown
30
+
31
+ # Python: Moulinex
32
+
33
+ [![GitHub Release][releases-shield]][releases]
34
+ [![Python Versions][python-versions-shield]][pypi]
35
+ [![License][license-shield]](LICENSE.md)
36
+ [![Build Status][build-shield]][build]
37
+
38
+ Asynchronous Python client for the Moulinex Cookeo multicookers and Companion cooking robots connected to Wi-Fi.
39
+
40
+ ## About
41
+
42
+ The client goes through the same Groupe SEB cloud as the Moulinex app, so the appliance must already be set up in that app. It logs in with the account of the app, then follows what each appliance reports: the cooking state, the program, the remaining time, the recipe in progress, and whether the appliance is turned on.
43
+
44
+ - Fully asynchronous, built on [aiohttp](https://github.com/aio-libs/aiohttp) and [aiomqtt](https://github.com/empicano/aiomqtt). No AWS SDK.
45
+ - Push based: the appliances tell the cloud what changed, and the client tells you.
46
+ - One connection per account, for all its appliances.
47
+ - Renews the tokens and connects again by itself.
48
+ - Typed models and typed errors.
49
+
50
+ The library is read-only. The cloud offers no way to control an appliance, so programs can only be started or stopped on the appliance itself.
51
+
52
+ ## Supported appliances
53
+
54
+ | Model | Tested |
55
+ | ---------------------- | ------ |
56
+ | Cookeo Touch WiFi | ✓ |
57
+ | Cookeo Touch Pro WiFi | ✓ |
58
+ | Cookeo Touch Mini WiFi | ✓ |
59
+ | Cookeo Wi-Fi 8-in-1 | |
60
+ | Cookeo Wi-Fi 9-in-1 | |
61
+ | Cookeo Wi-Fi 10-in-1 | |
62
+ | Cookeo Infinity | ✓ |
63
+ | i-Companion Touch XL | |
64
+
65
+ The untested models use the same cloud and should work. Bluetooth-only models such as the Cookeo Connect are not supported, and neither are other Groupe SEB appliances such as the OptiGrill.
66
+
67
+ ## Installation
68
+
69
+ ```bash
70
+ pip install aiomoulinex
71
+ ```
72
+
73
+ ## Usage
74
+
75
+ ### Logging in
76
+
77
+ ```python
78
+ import aiohttp
79
+
80
+ from aiomoulinex import LoginError, Region, login
81
+
82
+ async with aiohttp.ClientSession() as session:
83
+ try:
84
+ tokens = await login(
85
+ session, "jane@example.com", "password", Region.MOULINEX_FR
86
+ )
87
+ except LoginError as err:
88
+ print(err.reason) # invalid_auth, email_not_verified, account_locked, ...
89
+ ```
90
+
91
+ `Region` is the brand and country of the account, the one picked in the Moulinex app. The library only uses the connections of the session it is given: the cookies of the cloud stay out of it, so it is safe to pass a session that is shared with other code.
92
+
93
+ Store `tokens.to_dict()` and the region, not the password. `Tokens.from_dict()` reads them back, and `tokens.user_id` identifies the account: it stays the same when the email changes.
94
+
95
+ ### Following the appliances
96
+
97
+ ```python
98
+ import asyncio
99
+
100
+ import aiohttp
101
+
102
+ from aiomoulinex import ApplianceUpdated, Event, MoulinexClient, Region, Tokens
103
+
104
+
105
+ async def main(tokens: Tokens) -> None:
106
+ async with aiohttp.ClientSession() as session:
107
+ client = MoulinexClient(session, tokens, Region.MOULINEX_FR)
108
+
109
+ def on_event(event: Event) -> None:
110
+ if isinstance(event, ApplianceUpdated):
111
+ status = event.state.status
112
+ print(
113
+ event.appliance.name,
114
+ status.state if status else None,
115
+ event.appliance.program(status),
116
+ )
117
+
118
+ client.add_listener(on_event)
119
+ await client.connect()
120
+ print(client.appliances)
121
+ await asyncio.sleep(3600)
122
+ await client.disconnect()
123
+ ```
124
+
125
+ `connect()` refreshes the tokens, reads the appliances of the account, connects to the cloud and asks each appliance for its state. It returns once that state is known: the shadow of each appliance, and the cooking status of those that are turned on. An appliance that does not answer within 3 seconds is not waited for any longer. From then on:
126
+
127
+ - `client.appliances` holds the appliances of the account, by `thing_uuid`.
128
+ - `client.states` holds the last known `ApplianceState` of each appliance. Its `status` is what the appliance is cooking, its `shadow` tells whether it is turned on and which firmware it runs.
129
+ - `client.connected` is `False` while the connection is lost. The client keeps trying to connect again, and `client.states` keeps the last known state.
130
+ - `client.error` is why the client is not connected, if that is known.
131
+ - `client.tokens` holds the tokens as last refreshed.
132
+
133
+ Instead of a listener, the events can be read with `async for event in client.events()`. It ends when the client disconnects.
134
+
135
+ An appliance that is turned on needs a few seconds before it answers. The client asks for its status again 4, 10 and 20 seconds after it turned on, until it answers.
136
+
137
+ ### Events
138
+
139
+ | Event | Meaning |
140
+ | ---------------------- | ---------------------------------------------------------------------- |
141
+ | `ApplianceUpdated` | The cooking status or the shadow of an appliance changed. |
142
+ | `ApplianceAdded` | An appliance was linked to the account after the client connected. |
143
+ | `ApplianceRemoved` | An appliance is no longer linked to the account. |
144
+ | `ConnectionLost` | The connection is lost. The client keeps trying to connect again. |
145
+ | `ConnectionRestored` | The connection is back. |
146
+ | `AuthenticationFailed` | The cloud refused the refresh token. The client stopped: log in again. |
147
+ | `TokensUpdated` | The refresh token changed. Store the tokens to connect the next time. |
148
+
149
+ The client reads the appliances of the account again each time it renews its credentials, a little less than once an hour. That is when added and removed appliances are noticed.
150
+
151
+ ### Cooking status
152
+
153
+ `ApplianceState.status` is a `CookingStatus`, for a Companion as well. Each message of an appliance holds its whole status, so a status is never mixed with the one before: a value that is `None` does not apply at that moment.
154
+
155
+ The status itself is `None` until the appliance reports one, and again each time it turns off. What it was cooking is not shown again when it is turned back on.
156
+
157
+ - `state`: a `CookingState`. `idle` is defined by this library, for an appliance that is turned on and reports no state. The other values are those of the appliance: `stopped`, `ready`, `paused`, `warming`, `cooking`, `depressurization`, `keep_warm`, `done`, `delayed` and `alert`. It is `None` for a value this library does not know, which `raw_state` then holds.
158
+ - `mode`: a `CookingMode`: `manual`, `program`, `recipe` or `ingredient_cooking`.
159
+ - `appliance.program(status)`: the program in use, such as `cooking_high_pressure`. `appliance.programs` lists the programs that kind of appliance can run.
160
+ - `phase_progress`: a percentage, while the appliance warms up or releases pressure. `None` in every other state, like in the Moulinex app. `progress` holds what the appliance sent.
161
+ - `elapsed_time` and `remaining_time`: in seconds. The appliance does not send them every second: count from `received_at`, the time the message came in.
162
+ - `duration` and `temperature`: what the program is set to, in seconds and degrees Celsius.
163
+ - `recipe` and `step`: the recipe in progress and its current step. For an ingredient cooking, the recipe holds the ingredient.
164
+ - `notification`: the code of a message the appliance shows on its screen.
165
+ - `error` and `alert_description`: what the appliance reports when something is wrong.
166
+ - `event_date` and `operation_start`: the dates the appliance sends, read as UTC.
167
+
168
+ `ApplianceState.shadow.connected` tells whether the appliance is turned on and connected to the cloud.
169
+
170
+ ### Errors
171
+
172
+ All errors are subclasses of `MoulinexError`:
173
+
174
+ | Error | Meaning |
175
+ | ----------------------------- | -------------------------------------------------------------- |
176
+ | `MoulinexConnectionError` | The cloud could not be reached, or it did not answer in time. |
177
+ | `MoulinexAuthenticationError` | The cloud refused the tokens. The account has to log in again. |
178
+ | `LoginError` | The cloud refused the email and password. `reason` tells why. |
179
+
180
+ `LoginError` is a `MoulinexAuthenticationError`, so catch it first. A plain `MoulinexError` means the cloud answered something this library does not understand.
181
+
182
+ ### TLS
183
+
184
+ Creating a TLS context reads files from disk. The client does that in an executor. To reuse a context of your own, pass it as `ssl_context`.
185
+
186
+ ## Changelog & Releases
187
+
188
+ This repository keeps a change log using [GitHub's releases][releases] functionality.
189
+
190
+ Releases are based on [Semantic Versioning][semver], and use the format of `MAJOR.MINOR.PATCH`.
191
+
192
+ ## Setting up a development environment
193
+
194
+ This Python project is managed with [uv][uv]. You need at least Python 3.13.
195
+
196
+ ```bash
197
+ uv sync
198
+ uv run pytest
199
+ uv run ruff check .
200
+ uv run mypy src tests
201
+ ```
202
+
203
+ The checks also run as hooks with `uv run prek run --all-files`. The Prettier hook needs Node.js and `npm install`.
204
+
205
+ The tests run against a fake cloud that is part of the test suite, and need no account. `tests/fixtures/README.md` tells which payloads come from a real account.
206
+
207
+ ## Capturing what an appliance sends
208
+
209
+ Some models have not been tested, the Companion among them. To help with yours, capture what it sends:
210
+
211
+ ```bash
212
+ uv run python scripts/debug.py capture --seconds 600
213
+ uv run python scripts/debug.py check capture.jsonl
214
+ ```
215
+
216
+ `capture` logs in, then writes every message of the appliances of the account to `capture.jsonl`. Start a program on the appliance while it runs. The identifiers of the appliances and of the recipes are replaced, so the file can be shared in an issue. The first run asks for the email and password of the account and keeps a login token in a `.env` file, which git ignores. The password is not stored.
217
+
218
+ `check` prints what the library does not understand in a capture: fields it does not read, and states, modes and programs it does not know.
219
+
220
+ ## Disclaimer
221
+
222
+ This library is not affiliated with Groupe SEB, Moulinex or Tefal. It relies on an undocumented cloud API that can change at any time.
223
+
224
+ ## License
225
+
226
+ MIT License, see [LICENSE.md](LICENSE.md).
227
+
228
+ [build-shield]: https://github.com/piitaya/python-moulinex/actions/workflows/tests.yaml/badge.svg
229
+ [build]: https://github.com/piitaya/python-moulinex/actions
230
+ [license-shield]: https://img.shields.io/github/license/piitaya/python-moulinex.svg
231
+ [pypi]: https://pypi.org/project/aiomoulinex/
232
+ [python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomoulinex
233
+ [releases-shield]: https://img.shields.io/github/release/piitaya/python-moulinex.svg
234
+ [releases]: https://github.com/piitaya/python-moulinex/releases
235
+ [semver]: http://semver.org/spec/v2.0.0.html
236
+ [uv]: https://docs.astral.sh/uv/
@@ -0,0 +1,206 @@
1
+ # Python: Moulinex
2
+
3
+ [![GitHub Release][releases-shield]][releases]
4
+ [![Python Versions][python-versions-shield]][pypi]
5
+ [![License][license-shield]](LICENSE.md)
6
+ [![Build Status][build-shield]][build]
7
+
8
+ Asynchronous Python client for the Moulinex Cookeo multicookers and Companion cooking robots connected to Wi-Fi.
9
+
10
+ ## About
11
+
12
+ The client goes through the same Groupe SEB cloud as the Moulinex app, so the appliance must already be set up in that app. It logs in with the account of the app, then follows what each appliance reports: the cooking state, the program, the remaining time, the recipe in progress, and whether the appliance is turned on.
13
+
14
+ - Fully asynchronous, built on [aiohttp](https://github.com/aio-libs/aiohttp) and [aiomqtt](https://github.com/empicano/aiomqtt). No AWS SDK.
15
+ - Push based: the appliances tell the cloud what changed, and the client tells you.
16
+ - One connection per account, for all its appliances.
17
+ - Renews the tokens and connects again by itself.
18
+ - Typed models and typed errors.
19
+
20
+ The library is read-only. The cloud offers no way to control an appliance, so programs can only be started or stopped on the appliance itself.
21
+
22
+ ## Supported appliances
23
+
24
+ | Model | Tested |
25
+ | ---------------------- | ------ |
26
+ | Cookeo Touch WiFi | ✓ |
27
+ | Cookeo Touch Pro WiFi | ✓ |
28
+ | Cookeo Touch Mini WiFi | ✓ |
29
+ | Cookeo Wi-Fi 8-in-1 | |
30
+ | Cookeo Wi-Fi 9-in-1 | |
31
+ | Cookeo Wi-Fi 10-in-1 | |
32
+ | Cookeo Infinity | ✓ |
33
+ | i-Companion Touch XL | |
34
+
35
+ The untested models use the same cloud and should work. Bluetooth-only models such as the Cookeo Connect are not supported, and neither are other Groupe SEB appliances such as the OptiGrill.
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ pip install aiomoulinex
41
+ ```
42
+
43
+ ## Usage
44
+
45
+ ### Logging in
46
+
47
+ ```python
48
+ import aiohttp
49
+
50
+ from aiomoulinex import LoginError, Region, login
51
+
52
+ async with aiohttp.ClientSession() as session:
53
+ try:
54
+ tokens = await login(
55
+ session, "jane@example.com", "password", Region.MOULINEX_FR
56
+ )
57
+ except LoginError as err:
58
+ print(err.reason) # invalid_auth, email_not_verified, account_locked, ...
59
+ ```
60
+
61
+ `Region` is the brand and country of the account, the one picked in the Moulinex app. The library only uses the connections of the session it is given: the cookies of the cloud stay out of it, so it is safe to pass a session that is shared with other code.
62
+
63
+ Store `tokens.to_dict()` and the region, not the password. `Tokens.from_dict()` reads them back, and `tokens.user_id` identifies the account: it stays the same when the email changes.
64
+
65
+ ### Following the appliances
66
+
67
+ ```python
68
+ import asyncio
69
+
70
+ import aiohttp
71
+
72
+ from aiomoulinex import ApplianceUpdated, Event, MoulinexClient, Region, Tokens
73
+
74
+
75
+ async def main(tokens: Tokens) -> None:
76
+ async with aiohttp.ClientSession() as session:
77
+ client = MoulinexClient(session, tokens, Region.MOULINEX_FR)
78
+
79
+ def on_event(event: Event) -> None:
80
+ if isinstance(event, ApplianceUpdated):
81
+ status = event.state.status
82
+ print(
83
+ event.appliance.name,
84
+ status.state if status else None,
85
+ event.appliance.program(status),
86
+ )
87
+
88
+ client.add_listener(on_event)
89
+ await client.connect()
90
+ print(client.appliances)
91
+ await asyncio.sleep(3600)
92
+ await client.disconnect()
93
+ ```
94
+
95
+ `connect()` refreshes the tokens, reads the appliances of the account, connects to the cloud and asks each appliance for its state. It returns once that state is known: the shadow of each appliance, and the cooking status of those that are turned on. An appliance that does not answer within 3 seconds is not waited for any longer. From then on:
96
+
97
+ - `client.appliances` holds the appliances of the account, by `thing_uuid`.
98
+ - `client.states` holds the last known `ApplianceState` of each appliance. Its `status` is what the appliance is cooking, its `shadow` tells whether it is turned on and which firmware it runs.
99
+ - `client.connected` is `False` while the connection is lost. The client keeps trying to connect again, and `client.states` keeps the last known state.
100
+ - `client.error` is why the client is not connected, if that is known.
101
+ - `client.tokens` holds the tokens as last refreshed.
102
+
103
+ Instead of a listener, the events can be read with `async for event in client.events()`. It ends when the client disconnects.
104
+
105
+ An appliance that is turned on needs a few seconds before it answers. The client asks for its status again 4, 10 and 20 seconds after it turned on, until it answers.
106
+
107
+ ### Events
108
+
109
+ | Event | Meaning |
110
+ | ---------------------- | ---------------------------------------------------------------------- |
111
+ | `ApplianceUpdated` | The cooking status or the shadow of an appliance changed. |
112
+ | `ApplianceAdded` | An appliance was linked to the account after the client connected. |
113
+ | `ApplianceRemoved` | An appliance is no longer linked to the account. |
114
+ | `ConnectionLost` | The connection is lost. The client keeps trying to connect again. |
115
+ | `ConnectionRestored` | The connection is back. |
116
+ | `AuthenticationFailed` | The cloud refused the refresh token. The client stopped: log in again. |
117
+ | `TokensUpdated` | The refresh token changed. Store the tokens to connect the next time. |
118
+
119
+ The client reads the appliances of the account again each time it renews its credentials, a little less than once an hour. That is when added and removed appliances are noticed.
120
+
121
+ ### Cooking status
122
+
123
+ `ApplianceState.status` is a `CookingStatus`, for a Companion as well. Each message of an appliance holds its whole status, so a status is never mixed with the one before: a value that is `None` does not apply at that moment.
124
+
125
+ The status itself is `None` until the appliance reports one, and again each time it turns off. What it was cooking is not shown again when it is turned back on.
126
+
127
+ - `state`: a `CookingState`. `idle` is defined by this library, for an appliance that is turned on and reports no state. The other values are those of the appliance: `stopped`, `ready`, `paused`, `warming`, `cooking`, `depressurization`, `keep_warm`, `done`, `delayed` and `alert`. It is `None` for a value this library does not know, which `raw_state` then holds.
128
+ - `mode`: a `CookingMode`: `manual`, `program`, `recipe` or `ingredient_cooking`.
129
+ - `appliance.program(status)`: the program in use, such as `cooking_high_pressure`. `appliance.programs` lists the programs that kind of appliance can run.
130
+ - `phase_progress`: a percentage, while the appliance warms up or releases pressure. `None` in every other state, like in the Moulinex app. `progress` holds what the appliance sent.
131
+ - `elapsed_time` and `remaining_time`: in seconds. The appliance does not send them every second: count from `received_at`, the time the message came in.
132
+ - `duration` and `temperature`: what the program is set to, in seconds and degrees Celsius.
133
+ - `recipe` and `step`: the recipe in progress and its current step. For an ingredient cooking, the recipe holds the ingredient.
134
+ - `notification`: the code of a message the appliance shows on its screen.
135
+ - `error` and `alert_description`: what the appliance reports when something is wrong.
136
+ - `event_date` and `operation_start`: the dates the appliance sends, read as UTC.
137
+
138
+ `ApplianceState.shadow.connected` tells whether the appliance is turned on and connected to the cloud.
139
+
140
+ ### Errors
141
+
142
+ All errors are subclasses of `MoulinexError`:
143
+
144
+ | Error | Meaning |
145
+ | ----------------------------- | -------------------------------------------------------------- |
146
+ | `MoulinexConnectionError` | The cloud could not be reached, or it did not answer in time. |
147
+ | `MoulinexAuthenticationError` | The cloud refused the tokens. The account has to log in again. |
148
+ | `LoginError` | The cloud refused the email and password. `reason` tells why. |
149
+
150
+ `LoginError` is a `MoulinexAuthenticationError`, so catch it first. A plain `MoulinexError` means the cloud answered something this library does not understand.
151
+
152
+ ### TLS
153
+
154
+ Creating a TLS context reads files from disk. The client does that in an executor. To reuse a context of your own, pass it as `ssl_context`.
155
+
156
+ ## Changelog & Releases
157
+
158
+ This repository keeps a change log using [GitHub's releases][releases] functionality.
159
+
160
+ Releases are based on [Semantic Versioning][semver], and use the format of `MAJOR.MINOR.PATCH`.
161
+
162
+ ## Setting up a development environment
163
+
164
+ This Python project is managed with [uv][uv]. You need at least Python 3.13.
165
+
166
+ ```bash
167
+ uv sync
168
+ uv run pytest
169
+ uv run ruff check .
170
+ uv run mypy src tests
171
+ ```
172
+
173
+ The checks also run as hooks with `uv run prek run --all-files`. The Prettier hook needs Node.js and `npm install`.
174
+
175
+ The tests run against a fake cloud that is part of the test suite, and need no account. `tests/fixtures/README.md` tells which payloads come from a real account.
176
+
177
+ ## Capturing what an appliance sends
178
+
179
+ Some models have not been tested, the Companion among them. To help with yours, capture what it sends:
180
+
181
+ ```bash
182
+ uv run python scripts/debug.py capture --seconds 600
183
+ uv run python scripts/debug.py check capture.jsonl
184
+ ```
185
+
186
+ `capture` logs in, then writes every message of the appliances of the account to `capture.jsonl`. Start a program on the appliance while it runs. The identifiers of the appliances and of the recipes are replaced, so the file can be shared in an issue. The first run asks for the email and password of the account and keeps a login token in a `.env` file, which git ignores. The password is not stored.
187
+
188
+ `check` prints what the library does not understand in a capture: fields it does not read, and states, modes and programs it does not know.
189
+
190
+ ## Disclaimer
191
+
192
+ This library is not affiliated with Groupe SEB, Moulinex or Tefal. It relies on an undocumented cloud API that can change at any time.
193
+
194
+ ## License
195
+
196
+ MIT License, see [LICENSE.md](LICENSE.md).
197
+
198
+ [build-shield]: https://github.com/piitaya/python-moulinex/actions/workflows/tests.yaml/badge.svg
199
+ [build]: https://github.com/piitaya/python-moulinex/actions
200
+ [license-shield]: https://img.shields.io/github/license/piitaya/python-moulinex.svg
201
+ [pypi]: https://pypi.org/project/aiomoulinex/
202
+ [python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomoulinex
203
+ [releases-shield]: https://img.shields.io/github/release/piitaya/python-moulinex.svg
204
+ [releases]: https://github.com/piitaya/python-moulinex/releases
205
+ [semver]: http://semver.org/spec/v2.0.0.html
206
+ [uv]: https://docs.astral.sh/uv/