feat: add 'aiomqtt' recipe. (#280)

* feat: add 'aiomqtt' recipe.
* [pre-commit.ci] auto fixes from pre-commit.com hooks

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.pre-commit-config.yaml

@@ -41,8 +41,8 @@ repos:
     rev: v1.9.0
     hooks:
       - id: mypy
-        exclude: (settings.py|manage.py|models.py|(migrations/)|admin.py)
-        additional_dependencies: [pydantic, types-redis]
+        exclude: (manage.py|models.py|(migrations/)|admin.py)
+        additional_dependencies: [pydantic, types-redis, aiomqtt]
         language_version: python3.11
   - repo: https://github.com/PyCQA/pylint
     rev: v3.1.0
@@ -58,6 +58,7 @@ repos:
             motor,
             redis,
             types-redis,
+            aiomqtt,
           ]
         exclude: django_project/
         language_version: python3.11

Pipfile

@@ -16,6 +16,7 @@ celery = {version = "*", extras = ["librabbitmq", "mongodb", "redis"]}
 #django = "~=4.2"
 #psycopg = {version = ">=3.2", extras = ["binary", "pool"]}
 motor = "*"
+aiomqtt = "*"
 
 [dev-packages]
 black = "*"

README.md

@@ -222,8 +222,8 @@
 
 ### Redis
 
-- [**`redis-py`**: Sync / Async](https://lucas-six.github.io/python-cookbook/cookbook/system_services/redis)
-- [`aioredis`: Async (Obsoleted by `redis-py`)](https://aioredis.readthedocs.io/en/latest/)
+- [**`redis-py`**: Sync + Async](https://lucas-six.github.io/python-cookbook/cookbook/system_services/redis)
+- [~~`aioredis`: Async (Obsoleted by `redis-py`)~~](https://aioredis.readthedocs.io/en/latest/)
 - `pyton-redis-orm`: ORM
 
 ### RabbitMQ
@@ -234,7 +234,7 @@
 
 ### MQTT
 
-- [**`asyncio-mqtt`**: Async](https://pypi.org/project/asyncio-mqtt/) ([中文](https://blog.alexsun.top/vuepress-python-notes/pypi-package/async/asyncio-mqtt.html))
+- [**`aiomqtt`**: Async](https://lucas-six.github.io/python-cookbook/cookbook/system_services/mqtt_aiomqtt)
 
 ## Recipes
 

cookbook/build/project.md

@@ -138,7 +138,6 @@ disable = [
     "locally-disabled",
     "file-ignored",
     "suppressed-message",
-    "useless-suppression",
     "deprecated-pragma",
     "use-symbolic-message-instead",
     "logging-fstring-interpolation",
@@ -148,6 +147,7 @@ disable = [
 ]
 enable = [
     "c-extension-no-member",
+    "useless-suppression",
 ]
 
 [tool.pylint.design]

cookbook/system_services/mqtt_aiomqtt.md

@@ -0,0 +1,58 @@
+# `aiomqtt` - Python Asyncio APIs for MQTT
+
+## Set Up
+
+```toml
+# pyproject.toml
+
+dependencies = [
+    "aiomqtt",
+]
+```
+
+```bash
+pipenv install aiomqtt
+```
+
+## Usage
+
+```python
+"""MQTT `aiomqtt` Usage.
+"""
+
+import asyncio
+import os
+import sys
+
+import aiomqtt
+
+MQTT_HOST = 'localhost'
+MQTT_TOPIC_PREFIX = 'python-cookbook'
+
+
+async def main():
+    async with aiomqtt.Client(MQTT_HOST, timeout=3.5) as client:
+
+        # Subscribe
+        await client.subscribe(f'{MQTT_TOPIC_PREFIX}/#')
+        async for message in client.messages:
+            if isinstance(message.payload, bytes):
+                print(message.payload.decode('utf-8'))
+
+        # Publish
+        # await client.publish(f'{MQTT_TOPIC_PREFIX}/example', payload={'msg': 'hello'})
+
+
+# Change to the "Selector" event loop if platform is Windows
+if sys.platform.lower() == "win32" or os.name.lower() == "nt":
+    from asyncio import WindowsSelectorEventLoopPolicy  # type: ignore
+    from asyncio import set_event_loop_policy
+
+    set_event_loop_policy(WindowsSelectorEventLoopPolicy())
+
+asyncio.run(main())
+```
+
+## References
+
+- [`aiomqtt` Documentation](https://sbtinstruments.github.io/aiomqtt/index.html)

cookbook/system_services/redis.md

@@ -13,6 +13,10 @@ dependencies = [
     #"redis[hiredis]",
     "types-redis",
 ]
+
+[[tool.mypy.overrides]]
+module = "redis.*"
+ignore_missing_imports = true
 ```
 
 ```bash

cookbook/web/fastapi.md

@@ -3,22 +3,12 @@
 ## Installation
 
 ```bash
-# HTTP Request
-pipenv install aiohttp
-
-# Cache: Redis
-pipenv install redis[hiredis]
-pipenv install types-redis
-
 # MQ: RabbitMQ/MongoDB/Redis
 pipenv install pika
 pipenv install types-pika
 
 # Task Queue: Celery
 pipenv install celery[librabbitmq, mongodb, redis]
-
-# MQTT
-pipenv install asyncio-mqtt
 ```
 
 ## MongoDB

cookbook/web/fastapi/fastapi_mongodb.md

@@ -151,7 +151,7 @@ async def redoc_html() -> HTMLResponse:
 
 @app.get('/api')
 async def root() -> dict[str, str]:
-    await app.state.mongodb_db['x'].find_one({''})
+    await DB_XXX['x'].find_one({'name': 'fastapi'})
     return {'Hello': 'World'}
 
 

cookbook/web/fastapi/fastapi_quickstart.md

@@ -15,6 +15,12 @@ pipenv install --dev pylint-pydantic
 # JWT
 pipenv install python-jose[cryptography]
 pipenv install types-python-jose
+
+# HTTP Request
+pipenv install aiohttp
+
+# MQTT
+pipenv install aiomqtt
 ```
 
 ## `pyproject.toml`
@@ -53,6 +59,9 @@ dependencies = [
 
     "python-jose[cryptography]",
     "types-python-jose",
+
+    #"aiohttp",
+    #"aio-mqtt",
 ]
 dynamic = ["version"]
 
@@ -121,7 +130,7 @@ follow_imports = "silent"
 warn_redundant_casts = true
 warn_unused_ignores = true
 warn_unused_configs = true
-disallow_any_generics = true
+disallow_any_generics = false
 check_untyped_defs = true
 no_implicit_reexport = true
 disallow_untyped_defs = true
@@ -158,14 +167,15 @@ disable = [
     "bad-inline-option",
     "locally-disabled",
     "file-ignored",
+    "suppressed-message",
     "deprecated-pragma",
     "use-symbolic-message-instead",
     "logging-fstring-interpolation",
     "missing-function-docstring",
+    "missing-class-docstring",
 ]
 enable = [
     "c-extension-no-member",
-    "suppressed-message",
     "useless-suppression",
 ]
 
@@ -357,7 +367,6 @@ async def redoc_html() -> HTMLResponse:
 
 @app.get('/api')
 async def root() -> dict[str, str]:
-    await app.state.mongodb_db['x'].find_one({''})
     return {'Hello': 'World'}
 
 
@@ -377,8 +386,9 @@ See [Uvicorn: ASGI, WebSockets - Python Cookbook](../uvicorn).
 
 - [Python Project - Python Cookbook](../../build/project)
 - [ASGI Web Server: **`Uvicorn`** - Python Cookbook](../uvicorn)
-- [Data Model: **`Pydantic`**](../pydantic)
-- [with MongoDB: **`motor`**](fastapi_mongodb)
+- [Data Model: **`Pydantic`** - Python Cookbook](../pydantic)
+- [with MongoDB: **`motor`** - Python Cookbook](fastapi_mongodb)
+- [with Redis: **`redis`** - Python Cookbook](../../system_services/redis)
 
 ## References
 

django_project/django_project/settings.py

@@ -26,7 +26,7 @@
 # SECURITY WARNING: don't run with debug turned on in production!
 DEBUG = True
 
-ALLOWED_HOSTS = []
+ALLOWED_HOSTS: list[str] = []
 
 
 # Application definition
@@ -53,7 +53,7 @@
 
 ROOT_URLCONF = 'django_project.urls'
 
-TEMPLATES = [  # type: ignore
+TEMPLATES = [
     {
         'BACKEND': 'django.template.backends.django.DjangoTemplates',
         'DIRS': [],

examples/system_services/mqtt_aiomqtt_usage.py

@@ -0,0 +1,34 @@
+"""MQTT `aiomqtt` Usage.
+"""
+
+import asyncio
+import os
+import sys
+
+import aiomqtt
+
+MQTT_HOST = 'localhost'
+MQTT_TOPIC_PREFIX = 'python-cookbook'
+
+
+async def main() -> None:
+    async with aiomqtt.Client(MQTT_HOST, timeout=3.5) as client:
+
+        # Subscribe
+        await client.subscribe(f'{MQTT_TOPIC_PREFIX}/#')
+        async for message in client.messages:
+            if isinstance(message.payload, bytes):
+                print(message.payload.decode('utf-8'))
+
+        # Publish
+        # await client.publish(f'{MQTT_TOPIC_PREFIX}/example', payload={'msg': 'hello'})
+
+
+# Change to the "Selector" event loop if platform is Windows
+if sys.platform.lower() == 'win32' or os.name.lower() == 'nt':
+    from asyncio import WindowsSelectorEventLoopPolicy  # type: ignore
+    from asyncio import set_event_loop_policy
+
+    set_event_loop_policy(WindowsSelectorEventLoopPolicy())
+
+asyncio.run(main())

examples/web/fastapi/main_mongodb.py

@@ -79,7 +79,7 @@ async def redoc_html() -> HTMLResponse:
 
 @app.get('/api')
 async def root() -> dict[str, str]:
-    await app.state.mongodb_db['x'].find_one({''})
+    await DB_XXX['x'].find_one({'name': 'fastapi'})
     return {'Hello': 'World'}
 
 

examples/web/fastapi/main_openapi_static.py

@@ -74,7 +74,6 @@ async def redoc_html() -> HTMLResponse:
 
 @app.get('/api')
 async def root() -> dict[str, str]:
-    await app.state.mongodb_db['x'].find_one({''})
     return {'Hello': 'World'}
 
 

pyproject.toml

@@ -37,6 +37,9 @@ dependencies = [
 
     "redis[hiredis]",
     "types-redis",
+
+    "aiomqtt",
+
     "celery[librabbitmq, mongodb, redis]",
     #"requests",
     #"types-requests",
@@ -129,11 +132,14 @@ init_typed = true
 warn_required_dynamic_aliases = true
 warn_untyped_fields = true
 
-# mypy for MongoDB motor
 [[tool.mypy.overrides]]
 module = "motor.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "redis.*"
+ignore_missing_imports = true
+
 [tool.pylint.main]
 recursive = true
 py-version = 3.11