diff options
Diffstat (limited to 'doc/source/dev')
| -rw-r--r-- | doc/source/dev/events.rst | 52 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/dev/overview.rst | 54 | ||||
| -rw-r--r-- | doc/source/dev/slix.rst (renamed from doc/source/dev/sleek.rst) | 2 | ||||
| -rw-r--r-- | doc/source/dev/timed_events.rst | 4 |
5 files changed, 71 insertions, 43 deletions
diff --git a/doc/source/dev/events.rst b/doc/source/dev/events.rst index 770445a0..80397a6e 100644 --- a/doc/source/dev/events.rst +++ b/doc/source/dev/events.rst @@ -1,8 +1,8 @@ Event Index =========== -The following events are poezio-only events, for SleekXMPP events, check out -`their index <http://sleekxmpp.com/event_index.html>`_. +The following events are poezio-only events, for Slixmpp events, check out +`their index <http://slixmpp.com/event_index.html>`_. .. glossary:: :sorted: @@ -14,13 +14,13 @@ The following events are poezio-only events, for SleekXMPP events, check out Triggered whenever the user switches between tabs. muc_say - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.MucTab` source Triggered whenever the user sends a message to a :py:class:`~tabs.MucTab`. muc_say_after - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.MucTab` source Same thing than :term:`muc_say`, but after XHTML generation of the body, if needed. @@ -29,13 +29,13 @@ The following events are poezio-only events, for SleekXMPP events, check out you should probably not need it. private_say - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.PrivateTab` source Triggered whenever the user sends a message to a :py:class:`~tabs.PrivateTab`. private_say_after - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.PrivateTab` source Same thing than :term:`private_say`, but after XHTML generation of the body, if needed. @@ -44,13 +44,13 @@ The following events are poezio-only events, for SleekXMPP events, check out you should probably not need it. conversation_say - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.ConversationTab` source Triggered whenever the user sends a message to a :py:class:`~tabs.ConversationTab`. conversation_say_after: - - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **message:** :py:class:`~slixmpp.Message` that will be sent - **tab:** :py:class:`~tabs.ConversationTab` source Same thing than :term:`conversation_say`, but after XHTML generation @@ -60,101 +60,101 @@ The following events are poezio-only events, for SleekXMPP events, check out and you should probably not need it. muc_msg - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when a message is received in a :py:class:`~tabs.MucTab`. private_msg - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.PrivateTab` source Triggered when a message is received in a :py:class:`~tabs.PrivateTab`. conversation_msg - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.ConversationTab` source Triggered when a message is received in a :py:class:`~tabs.ConversationTab`. conversation_chatstate - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.ConversationTab` source Triggered when a chatstate is received in a :py:class:`~tabs.ConversationTab`. muc_chatstate - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when a chatstate is received in a :py:class:`~tabs.MucTab`. private_chatstate - - **message:** :py:class:`~sleekxmpp.Message` received + - **message:** :py:class:`~slixmpp.Message` received - **tab:** :py:class:`PrivateTab <tabs.PrivateTab>` source Triggered when a chatstate is received in a :py:class:`~tabs.PrivateTab`. normal_presence - - **presence:** :py:class:`~sleekxmpp.Presence` received - - **resource:** :py:class:`Resource <str>` that emitted the :py:class:`~sleekxmpp.Presence` + - **presence:** :py:class:`~slixmpp.Presence` received + - **resource:** :py:class:`Resource <str>` that emitted the :py:class:`~slixmpp.Presence` Triggered when a presence is received from a contact. muc_presence - - **presence:** :py:class:`~sleekxmpp.Presence` received + - **presence:** :py:class:`~slixmpp.Presence` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when a presence is received from someone in a :py:class:`~tabs.MucTab`. joining_muc - - **presence:** :py:class:`~~sleekxmpp.Presence` to be sent + - **presence:** :py:class:`~~slixmpp.Presence` to be sent Triggered when joining a MUC. The presence can thus be modified before being sent. changing_nick - - **presence:** :py:class:`~~sleekxmpp.Presence` to be sent + - **presence:** :py:class:`~~slixmpp.Presence` to be sent Triggered when the user changes his/her nickname on a MUC. The presence can thus be modified before being sent. send_normal_presence - - **presence:** :py:class:`~sleekxmpp.Presence` sent + - **presence:** :py:class:`~slixmpp.Presence` sent - Triggered when poezio sends a new :py:class:`~sleekxmpp.Presence` + Triggered when poezio sends a new :py:class:`~slixmpp.Presence` stanza. The presence can thus be modified before being sent. muc_join - - **presence:** :py:class:`~sleekxmpp.Presence` received + - **presence:** :py:class:`~slixmpp.Presence` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when an user joins a :py:class:`~tabs.MucTab` muc_ban - - **presence:** :py:class:`~sleekxmpp.Presence` received + - **presence:** :py:class:`~slixmpp.Presence` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when an user from a :py:class:`~tabs.MucTab` gets banned. muc_kicked - - **presence:** :py:class:`~sleekxmpp.Presence` received + - **presence:** :py:class:`~slixmpp.Presence` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when an user from a :py:class:`~tabs.MucTab` gets kicked. muc_nickchange - - **presence:** :py:class:`~sleekxmpp.Presence` received + - **presence:** :py:class:`~slixmpp.Presence` received - **tab:** :py:class:`~tabs.MucTab` source Triggered when an user in a :py:class:`~tabs.MucTab` changes his nickname. ignored_private - - **message**:py:class:`~sleekxmpp.Message` received + - **message**:py:class:`~slixmpp.Message` received - **tab:** :py:class:`~tabs.PrivateTab` source Triggered when a private message (that goes in a diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index aae0a6d0..21ea6253 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -15,7 +15,7 @@ About plugins plugin events - sleek + slix xep About Poezio diff --git a/doc/source/dev/overview.rst b/doc/source/dev/overview.rst index f0eef18a..3b27fe9e 100644 --- a/doc/source/dev/overview.rst +++ b/doc/source/dev/overview.rst @@ -26,8 +26,7 @@ dispatchs the I/O events (keypress) to the appropriate methods. But the main loop is not the most important thing in poezio; because it is an IM client, it is essentially event-driven. The event part is handled by -SleekXMPP, which is the library we chose after moving away from xmpppy. - +slixmpp, which is our fork of sleekxmpp to use asyncio instead of threads. **Tabs** are the second layer of poezio, but the first dealing with the UI: each **Tab** is a layout of several **windows**, it contains tab-specific commands, @@ -49,9 +48,9 @@ Event handlers -------------- The events handlers are registered right at the start of poezio, and then -when a matching stanza is received, the handler is called in a separate thread -from the main loop. The handlers are in **Core**, and then they call the -appropriate methods in the corresponding **tabs**. +when a matching stanza is received, the handler is called. The handlers are +in **Core**, and then they call the appropriate methods in the corresponding +**tabs**. Example scenario: if a message is received from a MUC, then the **Core** handler will identify the **Tab**, and call the relevant handler from this **Tab**, this tab @@ -86,14 +85,12 @@ There are utilities to deal with it (common.shell_split), but it is not always necessary. Commands are registered in the **commands** dictionnary of a tab structured as key (command name) -> tuple(command function, help string, completion). - Completions are a bit tricky, but it’s easy once you get used to it: They take an **Input** (a _windows_ class) as a parameter, named the_input everywhere in the sources. To effectively have a completion, you have to call -**the_input.auto_completion()** or **the_input.new_completion()** at the end -of the function. - +**the_input.auto_completion()** or **the_input.new_completion()** with the relevant +parameters before returning from the function. .. code-block:: python @@ -105,13 +102,48 @@ of the function. def new_completion(completion_list, argument_position, after='', quotify=True): # … -Set the input to iterate over _completion_list_ when the user hits tab, insert +Set the input to iterate over **completion_list** when the user hits tab, to insert **after** after the completed item, and surround the item with double quotes or not. To find the current completed argument, use the **input.get_argument_position()** -method. You can then use new_completion() to select the argument to be completed. +method. You can then use **new_completion()** to select the argument to be completed. You can look for examples in the sources, all the possible cases are covered (single-argument, complex arguments with spaces, several arguments, etc…). + +.. note:: + Only **new_completion()** used together with **get_argument_position()** allow + completing arguments that are not at the end of the command line, therefore it + is preferable to use that and not **auto_completion()**. + + +Dealing with the command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For convenience’s sake, poezio includes a **decorators** module containing a +**command_args_parser**, which can be used to filter the input easily. + +Examples: + +.. code-block:: python + + from decorators import command_args_parser + class MyClass(object): + + @command_args_parser.raw + def command_raw(self, raw): + # the "raw" parameter will be the raw input string + + @command_args_parser.ignored + def command_ignored(self): + # no argument is given to that function + + @command_args_parser.quoted(mandatory=1, optional=0) + def command_quoted_1(self, args): + # the "args" parameter will be a list containing one argument + +See the source of the CommandArgParser for more information. + +.. autoclass:: decorators.CommandArgParser diff --git a/doc/source/dev/sleek.rst b/doc/source/dev/slix.rst index 7baf5b29..3c06e349 100644 --- a/doc/source/dev/sleek.rst +++ b/doc/source/dev/slix.rst @@ -1,7 +1,7 @@ SleekXMPP classes ================= -.. module:: sleekxmpp +.. module:: slixmpp .. autoclass:: Message :members: diff --git a/doc/source/dev/timed_events.rst b/doc/source/dev/timed_events.rst index a2c96912..82f49232 100644 --- a/doc/source/dev/timed_events.rst +++ b/doc/source/dev/timed_events.rst @@ -6,10 +6,6 @@ Timed events documentation .. autoclass:: TimedEvent .. automethod:: __init__ - .. automethod:: has_timed_out - .. automethod:: change_date - .. automethod:: add_delay - .. autoclass:: DelayedEvent |