More docs

docs/dispatcher/filters/index.rst

@@ -19,8 +19,8 @@ Here is list of builtin filters:
     content_types
     text
     exception
-
-Or you can do :ref:`✨ some magic <magic-filters>`
+    magic_filters
+    magic_data
 
 Own filters specification
 =========================
@@ -35,7 +35,7 @@ Filters can be:
 
 - Any awaitable object
 
-- Subclass of :ref:`BaseFilter <filters-base>`
+- Subclass of :class:`aiogram.dispatcher.filters.base.BaseFilter`
 
 - Instances of :ref:`MagicFilter <magic-filters>`
 

docs/dispatcher/filters/magic_data.rst

@@ -0,0 +1,34 @@
+====
+MagicData
+====
+
+.. autoclass:: aiogram.dispatcher.filters.magic_data.MagicData
+    :members:
+    :member-order: bysource
+    :undoc-members: False
+
+Can be imported:
+
+- :code:`from aiogram.dispatcher.filters.magic_data import MagicData`
+- :code:`from aiogram.dispatcher.filters import MagicData`
+- :code:`from aiogram.filters import MagicData`
+
+Or used from filters factory by passing corresponding arguments to handler registration line
+
+Usage
+=====
+
+#. :code:`magic_data=F.event.from_user.id == F.config.admin_id`  (Note that :code:`config` should be passed from middleware)
+
+
+Allowed handlers
+================
+
+Allowed update types for this filter:
+
+- :code:`message`
+- :code:`edited_message`
+- :code:`channel_post`
+- :code:`edited_channel_post`
+- :code:`inline_query`
+- :code:`callback_query`

docs/dispatcher/filters/magic_filters.rst

@@ -24,7 +24,7 @@ and memorize the attributes chain and the action which should be checked on dema
 So that's mean you can chain attribute getters, describe simple data validations
 and then call the resulted object passing single object as argument,
 for example make attributes chain :code:`F.foo.bar.baz` then add
-action ':code:`F.foo.bar.baz == 'spam'` and then call the resulted object - :code:`(F.foo.bar.baz == 'spam')(obj)`
+action ':code:`F.foo.bar.baz == 'spam'` and then call the resulted object - :code:`(F.foo.bar.baz == 'spam').resolve(obj)`
 
 .. _magic-filter-possible-actions:
 
@@ -125,9 +125,9 @@ Can be used only with string attributes.
 
 .. code-block:: python
 
-    F.text__lower == 'test'  # lambda message: message.text.lower() == 'test'
-    F.text__upper.in_('FOO', 'BAR')  # lambda message: message.text.upper() in {'FOO', 'BAR'}
-    F.text__len == 5  # lambda message: len(message.text) == 5
+    F.text.lower() == 'test'  # lambda message: message.text.lower() == 'test'
+    F.text.upper().in_('FOO', 'BAR')  # lambda message: message.text.upper() in {'FOO', 'BAR'}
+    F.text.len() == 5  # lambda message: len(message.text) == 5
 
 
 Usage in *aiogram*

docs/dispatcher/finite_state_machine/index.rst

@@ -0,0 +1,119 @@
+====================
+Finite State Machine
+====================
+
+    A finite-state machine (FSM) or finite-state automaton (FSA, plural: automata), finite automaton,
+    or simply a state machine, is a mathematical model of computation.
+
+    It is an abstract machine that can be in exactly one of a finite number of states at any given time.
+    The FSM can change from one state to another in response to some inputs;
+    the change from one state to another is called a transition.
+
+    An FSM is defined by a list of its states, its initial state,
+    and the inputs that trigger each transition.
+
+    .. raw:: html
+
+        <hr>
+
+    Source: `WikiPedia <wiki>`_
+
+Usage example
+=============
+
+Not all functionality of the bot can be implemented as single handler,
+for example you will need to collect some data from user in separated steps you will need to use FSM.
+
+
+.. image:: ../../_static/fsm_example.png
+    :alt: FSM Example
+
+Let's see how to do that step-by-step
+
+Step by step
+------------
+
+Before handle any states you will need to specify what kind of states you want to handle
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 15
+    :lines: 15-18
+
+And then write handler for each state separately from the start of dialog
+
+Here is dialog can be started only via command :code:`/start`, so lets handle it and make transition user to state :code:`Form.name`
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 21
+    :lines: 21-27
+
+After that you will need to save some data to the storage and make transition to next step.
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 48
+    :lines: 48-63
+
+At the next steps user can make different answers, it can be `yes`, `no` or any other
+
+Handle :code:`yes` and soon we need to handle :code:`Form.language` state
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 77
+    :lines: 77-84
+
+Handle :code:`no`
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 66
+    :lines: 66-74
+
+And handle any other answers
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 87
+    :lines: 87-89
+
+All possible cases of `like_bots` step was covered, let's implement finally step
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 92
+    :lines: 92-102
+
+And now you have covered all steps from the image, but you can make possibility to cancel conversation, lets do that via command or text
+
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+    :lineno-start: 30
+    :lines: 30-45
+
+Complete example
+----------------
+.. literalinclude:: ../../../examples/finite_state_machine.py
+    :language: python
+    :linenos:
+
+
+Read more
+=========
+
+.. toctree::
+
+    storages
+
+
+.. _wiki: https://en.wikipedia.org/wiki/Finite-state_machine

docs/dispatcher/finite_state_machine/storages.rst

@@ -9,7 +9,7 @@ MemoryStorage
 -------------
 
 .. autoclass:: aiogram.dispatcher.fsm.storage.memory.MemoryStorage
-    :members: __init__, from_url
+    :members: __init__
     :member-order: bysource
 
 RedisStorage
@@ -19,5 +19,20 @@ RedisStorage
     :members: __init__, from_url
     :member-order: bysource
 
+Keys inside storage can be customized via key builders:
+
+.. autoclass:: aiogram.dispatcher.fsm.storage.redis.KeyBuilder
+    :members:
+    :member-order: bysource
+
+.. autoclass:: aiogram.dispatcher.fsm.storage.redis.DefaultKeyBuilder
+    :members:
+    :member-order: bysource
+
+
 Writing own storages
 ====================
+
+.. autoclass:: aiogram.dispatcher.fsm.storage.base.BaseStorage
+    :members:
+    :member-order: bysource

docs/dispatcher/index.rst

@@ -22,5 +22,5 @@ Dispatcher is subclass of router and should be always is root router.
     dispatcher
     class_based_handlers/index
     filters/index
-    filters/magic_filters
     middlewares
+    finite_state_machine/index