reworked environments; updated docs; added features; changed version;

README.md

@@ -25,48 +25,40 @@ python -m pip install kutana
 ```
 
 ### Usage
-- Create `Kutana` engine and add controllers. You can use shortcuts like `VKKutana` for adding and registering controllers, callbacks and other usefull functions.
-- You can set settings in `Kutana.settings`.
-- Add or create plugins other files and register them in executor. You can import plugin from files with function `load_plugins`. Files should be a valid python modules with available `plugin` field with your plugin (`Plugin`).
+- Create `Kutana` engine and add controllers.
+- Register your plugins in the executor. You can import plugin from folders with function `load_plugins`. Files should be a valid python modules with available `plugin` field with your plugin (`Plugin`).
 - Start engine.
 
 Example `run.py`
 ```py
-from kutana import Kutana, VKKutana, load_plugins
+from Kutana import *
 
-# Creation
-kutana = VKKutana(configuration="configuration.json")
+# Create engine
+kutana = Kutana()
 
-# Settings
-kutana.settings["MOTD_MESSAGE"] = "Greetings, traveler."
+# Add VKController to engine
+kutana.add_controller(
+    VKController(load_configuration("vk_token", "configuration.json"))
+)
+# configuration.json:
+# {"vk_token": "API token here"}
 
-# Create simple plugin
-plugin = Plugin()
-
-@self.plugin.on_text("hi", "hi!")
-async def greet(message, attachments, env, extenv):
-    await env.reply("Hello!")
-
-kutana.executor.register_plugins(plugin)
-
-# Load plugins from folder
+# Load and register plugins
 kutana.executor.register_plugins(*load_plugins("plugins/"))
 
-# Start kutana
+# Run engine
 kutana.run()
 ```
 
 Example `plugins/echo.py`
 ```py
 from kutana import Plugin
 
-plugin = Plugin()
-
-plugin.name = "Echo"
+plugin = Plugin(name="Echo")
 
 @plugin.on_startswith_text("echo")
-async def on_message(message, attachments, env, extenv):
-    await env.reply("{}!".format(env.body))
+async def on_echo(message, attachments, env):
+    await env.reply("{}".format(env.body))
 ```
 
 ### Available controllers
@@ -77,9 +69,6 @@ Task|Priority
 ---|---
 Find and fix all current bugs | high
 Find and fix grammar and semantic errors | high
-Create proper documentation | medium
-Adding tests | medium
-Add module to PyPi | low
 Developing plugins | very low
 
 ### Authors

configuration.json.example

@@ -1,3 +1,3 @@
 {
-  "token": ""
+  "vk_token": ""
 }

configuration_test.json.example

@@ -1,4 +1,4 @@
 {
-    "token": "",
-    "utoken": ""
-}
+    "vk_token": "",
+    "vk_utoken": ""
+}

docs/controller.rst

@@ -0,0 +1,32 @@
+Controller
+==========
+
+Description
+^^^^^^^^^^^
+
+Controllers are responsible for receiving updates and sending responses.
+Often adding new source (like vk.com) requires creation of two things:
+controller and normalizer.
+
+- Controller just exchanges messages, oversees over this exchange and
+  provides means to interact with service to callbacks throught environment.
+- Normalizer turns updates from raw data to instances of classes
+  :class:`.Message` and :class:`.Attachment` if possible. These objects are
+  then passed to plugins. They should only create instances of messages
+  without editing environment.
+
+These files are placed in folders "kutana/controllers" and
+"kutana/plugins/converters".
+
+Custom controller
+^^^^^^^^^^^^^^^^^
+
+You can simply fill required methods from :class:`kutana.BasicController`.
+Use :class:`.DumpingController` as example and it's files in folders
+"controllers" and "converters" with its names.
+
+.. autoclass:: kutana.BasicController
+    :members:
+
+.. note::
+  You don't have to create your own controllers if you don't want to.

docs/executor.rst

@@ -0,0 +1,46 @@
+Executor
+========
+
+Description
+^^^^^^^^^^^
+
+This class collects coroutines for updates processing and calls
+them with the appropriate data. These coroutines receive the update itself
+and the dictionary-like environment with data that could be written
+there by previous and read by next coroutine calls. You can register
+These callbacks with executor's :func:`subscribe` as method or decorator.
+Environment has "ctrl_type" set to the type of update's controller
+(VKontakte, Telegram, etc.).
+
+.. code-block:: python
+
+  @kutana.executor.subscribe()
+  async def prc(update, eenv):
+    # eenv stands for "executor's environment"
+    await eenv.reply("Ого, эхо!")
+
+Same as
+
+.. code-block:: python
+
+  async def prc(update, eenv):
+    await env.reply("Ого, эхо!")
+
+  kutana.executor.subscribe(prc)
+
+All coroutine callbacks will be called in order they were added until
+one of the coroutines returns **"DONE"** or none coroutines left.
+
+You can register callbacks on exceptions in normal callbacks like that.
+Exception accesible from eenv.exception in error callbacks.
+
+.. code-block:: python
+
+  async def prc(update, eenv):
+    await env.reply("Error happened c:")
+
+  kutana.executor.subscribe(prc, error=True)
+
+.. note::
+  You can't and shouldn't create or use your own executors. It's just
+  convenient collector and executor of callbacks.

docs/index.rst

@@ -1,28 +1,26 @@
 Welcome to Kutana!
-==================================
+==================
 
 .. image:: _static/kutana-logo-512.png
     :alt: Kutana
+    :scale: 65%
 
-The engine for developing bots for soc. networks, 
+The engine for developing bots for soc. networks,
 instant messengers and other systems.
 
 .. note::
-    We apologize in advance for errors and omissions in this documentation. 
+    We apologize in advance for errors and omissions in this documentation.
     If you can help improve the documentation corrections or modifications,
     we will be very grateful.
 
 Usage
 *****
 
-- Create :class:`.Kutana` engine and add controllers. You can use 
-  shortcuts like :class:`VKKutana <kutana.shortcuts.VKKutana>` for adding and registering controllers,
-  callbacks and other usefull functions.
-- You can set settings in `Kutana.settings`.
-- Add or create plugins other files and register them in executor. You 
-  can import plugin from files with function `load_plugins`. Files 
-  should be a valid python modules with available `plugin` field with 
-  your plugin (`Plugin`).
+- Create :class:`.Kutana` engine and add controllers.
+- Register your plugins in the executor. You can import
+  plugin from folders with function `load_plugins`. Files
+  should be a valid python modules with available `plugin`
+  field with your plugin (`Plugin`).
 - Start engine.
 
 Example
@@ -32,54 +30,53 @@ Example "run.py"
 
 .. code-block:: python
 
-    from kutana import Kutana, VKKutana, load_plugins
+    from kutana import Kutana, VKController, \
+        load_plugins, load_configuration
 
-    # Creation
-    kutana = VKKutana(configuration="configuration.json")
+    # Create engine
+    kutana = Kutana()
 
-    # Settings
-    kutana.settings["MOTD_MESSAGE"] = "Greetings, traveler." 
+    # Add VKController to engine
+    kutana.add_controller(
+        VKController(
+            load_configuration(
+                "vk_token", "configuration.json"
+            )
+        )
+    )
 
-    # Create simple plugin
-    plugin = Plugin()
+    # Load and register plugins
+    kutana.executor.register_plugins(
+        *load_plugins("example/plugins/")
+    )
 
-    @self.plugin.on_text("hi", "hi!")
-    async def greet(message, attachments, env, extenv):
-        await env.reply("Hello!")
-
-    kutana.executor.register_plugins(plugin)
-
-    # Load plugins from folder
-    kutana.executor.register_plugins(*load_plugins("plugins/"))
-
-    # Start kutana
+    # Run engine
     kutana.run()
 
+
 Example "plugins/echo.py"
 
 .. code-block:: python
 
     from kutana import Plugin
 
-    plugin = Plugin()
-
-    plugin.name = "Echo"
+    plugin = Plugin(name="Echo")
 
     @plugin.on_startswith_text("echo")
-    async def on_message(message, attachments, env, extenv):
-        await env.reply("{}!".format(env.body))
+    async def on_echo(message, attachments, env):
+        await env.reply("{}".format(env.body))
 
 .. toctree::
     :maxdepth: 2
-    :caption: Docs
+    :caption: Elements
 
-    plugins
-    controllers
+    plugin
+    controller
     special-updates
-    executors
+    executor
 
 .. toctree::
     :maxdepth: 1
-    :caption: Source
+    :caption: Reference
 
-    src/modules
+    src/modules