diff --git a/amqtt/contrib/__init__.py b/amqtt/contrib/__init__.py new file mode 100644 index 0000000..ca5a2ea --- /dev/null +++ b/amqtt/contrib/__init__.py @@ -0,0 +1 @@ +"""Package for plugins contributed by community members.""" diff --git a/amqtt/plugins/persistence.py b/amqtt/contrib/persistence.py similarity index 100% rename from amqtt/plugins/persistence.py rename to amqtt/contrib/persistence.py diff --git a/docs/contrib_plugins.md b/docs/contrib_plugins.md new file mode 100644 index 0000000..e5390c1 --- /dev/null +++ b/docs/contrib_plugins.md @@ -0,0 +1,29 @@ +# Contributed Plugins + +Beyond the original set of plugins created for aMQTT, `amqtt.contrib` plugins have been +more recently developed and contributed to the amqtt code base. These plugins require extra +dependencies: + +`pip install amqtt[contrib]` + +### Session Persistence + +`amqtt.plugins.persistence.SessionDBPlugin` + +Plugin to store session information and retained topic messages in the event that the broker terminates abnormally. + +This plugin requires additional dependencies: + + + +**Configuration** + +- `file` - *(string)* path & filename to store the session db. default: `amqtt.db` +- `clear_on_shutdown` *(bool)* if the broker shutdowns down normally, don't retain any information. default: `True` + +```yaml +plugins: + amqtt.plugins.persistence.SessionDBPlugin: + file: 'amqtt.db' + clear_on_shutdown: True +``` diff --git a/docs/packaged_plugins.md b/docs/packaged_plugins.md index fd3e32d..70e1707 100644 --- a/docs/packaged_plugins.md +++ b/docs/packaged_plugins.md @@ -1,4 +1,4 @@ -# Existing Plugins +# Packaged Plugins With the aMQTT plugins framework, one can add additional functionality without having to rewrite core logic in the broker or client. Plugins can be loaded and configured using @@ -240,29 +240,3 @@ and `on_mqtt_packet_received`. plugins: amqtt.plugins.logging_amqtt.PacketLoggerPlugin: ``` - - -### Session Persistence - -`amqtt.plugins.persistence.SessionDBPlugin` - -Plugin to store session information and retained topic messages in the event that the broker terminates abnormally. - -This plugin requires additional dependencies: - -`pip install amqtt[db]` - -**Configuration** - -- `file` - *(string)* path & filename to store the session db. default: `amqtt.db` -- `clear_on_shutdown` *(bool)* if the broker shutdowns down normally, don't retain any information. default: `True` - -```yaml -plugins: - amqtt.plugins.persistence.SessionDBPlugin: - file: 'amqtt.db' - clear_on_shutdown: True -``` - - - diff --git a/mkdocs.rtd.yml b/mkdocs.rtd.yml index 7f248d9..6cc8b0e 100644 --- a/mkdocs.rtd.yml +++ b/mkdocs.rtd.yml @@ -40,6 +40,7 @@ nav: - Plugins: - Packaged: packaged_plugins.md - Custom: custom_plugins.md + - Contributed: contrib_plugins.md - Configuration: - Broker: references/broker_config.md - Client: references/client_config.md diff --git a/pyproject.toml b/pyproject.toml index 68a9ca5..c9bca33 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,7 +80,7 @@ docs = [ [project.optional-dependencies] ci = ["coveralls==4.0.1"] -db = [ +contrib = [ "aiosqlite>=0.21.0", "greenlet>=3.2.3", "sqlalchemy[asyncio]>=2.0.41", diff --git a/tests/plugins/test_persistence.py b/tests/contrib/test_persistence.py similarity index 100% rename from tests/plugins/test_persistence.py rename to tests/contrib/test_persistence.py diff --git a/uv.lock b/uv.lock index 2ebcedb..036147c 100644 --- a/uv.lock +++ b/uv.lock @@ -37,7 +37,7 @@ dependencies = [ ci = [ { name = "coveralls" }, ] -db = [ +contrib = [ { name = "aiosqlite" }, { name = "greenlet" }, { name = "sqlalchemy", extra = ["asyncio"] }, @@ -84,19 +84,19 @@ docs = [ [package.metadata] requires-dist = [ - { name = "aiosqlite", marker = "extra == 'db'", specifier = ">=0.21.0" }, + { name = "aiosqlite", marker = "extra == 'contrib'", specifier = ">=0.21.0" }, { name = "coveralls", marker = "extra == 'ci'", specifier = "==4.0.1" }, { name = "dacite", specifier = ">=1.9.2" }, - { name = "greenlet", marker = "extra == 'db'", specifier = ">=3.2.3" }, + { name = "greenlet", marker = "extra == 'contrib'", specifier = ">=3.2.3" }, { name = "passlib", specifier = "==1.7.4" }, { name = "psutil", specifier = ">=7.0.0" }, { name = "pyyaml", specifier = "==6.0.2" }, - { name = "sqlalchemy", extras = ["asyncio"], marker = "extra == 'db'", specifier = ">=2.0.41" }, + { name = "sqlalchemy", extras = ["asyncio"], marker = "extra == 'contrib'", specifier = ">=2.0.41" }, { name = "transitions", specifier = "==0.9.2" }, { name = "typer", specifier = "==0.15.4" }, { name = "websockets", specifier = "==15.0.1" }, ] -provides-extras = ["ci", "db"] +provides-extras = ["ci", "db", "contrib"] [package.metadata.requires-dev] dev = [