Improving docs, adding with_shutdown

README.md

@@ -166,7 +166,7 @@ and run
 This script will generate a file at `src/plugins/my_cool_plugin.py` containing (approximately)
 
 ```python
-from command_system import as_plugin
+from rollbot import as_plugin
 
 
 @as_plugin
@@ -194,19 +194,58 @@ the plugin is handled by the `as_plugin` decorator, which performs all of the fo
  it to the `my_cool_plugin` variable *instead* of your plugin function, which is what allows your
  plugin to be found dynamically after just importing the plugin module
 
-#### Command Naming
-
-TODO
-
-#### Plugin Arguments
-
-TODO
+#### Other Decorators
+
+The `rollbot.plugins.decorators` module exports decorators that can be used for specific additional
+functionality on functional commands. `as_plugin` and `with_help` are re-exported by `rollbot` for
+convenience, but other tools are left in this decorators submodule. All of these decorators should be
+applied *after* `as_plugin`.
+
+ - `with_startup` - attach a function to a command to override the `RollbotPlugin.on_start` function
+ - `with_shutdown` - the same as `with_startup`, but for the `RollbotPlugin.on_shutdown` function
+ - `require_min_args` - enforce a minimum number of arguments in the message
+ - `require_args` - enforce an exact number of arguments in the message
+
+#### Plugin Dependency Injection
+
+The `rollbot.plugins.injection` module exports many dependency injection tools for your
+plugins. If you are using the `as_plugin` decorator, you can annotate the arguments of your
+function to have these values injected at runtime. 
+
+ - `Message` - will receive the `RollbotMessage` triggering the command
+ - `Bot` - the `Rollbot` instance executing the command
+ - `Logger` - the logger the command should use
+ - `ArgList` - the argument list, resulting from calling `RollbotMessage.arg_list`
+    - `Arg(n, conversion=c, fail_msg=m)` - will receive the argument at index `n`, converted by
+      `c` (which can be omitted if a string is desired), and will fail the command if the
+      conversion fails with a `ValueError` and instead use the failure message `m` in the response (which itself will be formatted with the actual value of the argument)
+ - `Config(key=k)` - will receive the configuration associated with `k`, or the root confiuration
+   dictionary if `k` is not provided or is `None`
+ - `Database` - will receive the SQLAlchemy database session scope, but it is preferred to
+    use one of the other database-lookup types when possible
+    - `Singleton(cls)` - will receive the proper singleton for this execution of the given
+      `cls`, which itself must be annotated with either `as_group_singleton` or `as_sender_singleton`.
+      - `Singleton(cls).by(fn)` - will execute `fn` (a function with its own dependencies)
+        to perform the query
+      - `Singletone(cls).by_all(fn)` - works same as `Singleton.by` but `fn` is instead
+        expected to return an iterable of keys, and all singletons will be looked up
+    - `Query(cls)` - will receive the contents of the table of the SQLAlchemy model class `cls`
+      - `Query(cls).filter(fn)` - filters the `Query` by the filter returned by `fn` (a function
+        with its own dependencies), which can be chained as `Query.filter().filter()...`
+ - `Lazy(a)` - will receive an object that, when `Lazy.get` is called, will return the result of the
+   injection `a`, delaying computation until this point, and only calculating the value on the first
+   call to `get`
+
+Additionally, as a legacy feature, plugin arguments can use specific names to request
+specific dependencies. New plugins should not use this system, but the argument names
+and name patterns are:
 
  - `msg` is the RollbotMessage triggering the command
  - `db` is the SQLAlchemy database session scope
  - `log` is the command's logger
  - `bot` is the Rollbot instance running the command
  - `data.*` is supplied the group singleton of the annotated data type
+ - `.*cfg` is supplied the configuration associated with the annotated key (as a string)
 
 #### RollbotResponse
 

lib/rollbot/plugins/decorators/__init__.py

@@ -1,3 +1,3 @@
 from .as_plugin import as_plugin
-from .attachers import with_help, with_startup
+from .attachers import with_help, with_startup, with_shutdown
 from .requires import require_min_args, require_args

lib/rollbot/plugins/decorators/attachers.py

@@ -18,3 +18,14 @@ def with_startup(startup):
         return cls
 
     return decorator
+
+
+def with_shutdown(shutdown):
+    def new_shutdown(self, db):
+        return shutdown(self, db)
+    
+    def decorator(cls):
+        setattr(cls, "on_shutdown", new_shutdown)
+        return cls
+
+    return decorator