Merge branch 'master' into release-next

Author: Pietro Albini

README.md

@@ -47,7 +47,7 @@ pip, virtualenv, setuptools and [invoke][3] installed:
     $ cd botogram
     $ invoke install
 
-On some Linux systems you might need to wrap the ``make install`` command with
+On some Linux systems you might need to wrap the ``invoke install`` command with
 ``sudo``, if you don't have root privileges.
 
 [1]: https://core.telegram.org/bots

botogram/api.py

@@ -36,7 +36,7 @@ def __init__(self, api_key, endpoint=None):
 
     def call(self, method, params=None, files=None, expect=None):
         """Call a method of the API"""
-        url = self._endpoint+"bot%s/%s" % (self._api_key, method)
+        url = self._endpoint + "bot%s/%s" % (self._api_key, method)
         response = requests.get(url, params=params, files=files)
         content = response.json()
 
@@ -55,7 +55,7 @@ def call(self, method, params=None, files=None, expect=None):
 
     def file_content(self, path):
         """Get the content of an user-submitted file"""
-        url = self._endpoint+"file/bot%s/%s" % (self._api_key, path)
+        url = self._endpoint + "file/bot%s/%s" % (self._api_key, path)
         response = requests.get(url)
 
         return response.content

botogram/bot.py

@@ -54,9 +54,9 @@ def __init__(self, api_connection):
         self._shared_memory = shared.SharedMemory()
 
         # Register bot's shared memory initializers
-        inits = self._main_component._get_shared_memory_inits()
+        inits = self._main_component._get_chains()["memory_preparers"][0]
         maincompid = self._main_component._component_id
-        self._shared_memory.register_inits_list(maincompid, inits)
+        self._shared_memory.register_preparers_list(maincompid, inits)
 
         # Setup the scheduler
         self._scheduler = tasks.Scheduler()
@@ -83,7 +83,7 @@ def __init__(self, api_connection):
 
         # This regex will match all commands pointed to this bot
         self._commands_re = re.compile(r'^\/([a-zA-Z0-9_]+)(@' +
-                                       self.itself.username+r')?( .*)?$')
+                                       self.itself.username + r')?( .*)?$')
 
     def __reduce__(self):
         # Use the standard __reduce__
@@ -142,11 +142,17 @@ def __(func):
             return func
         return __
 
-    def init_shared_memory(self, func):
-        """Register a shared memory's initializer"""
-        self._main_component.add_shared_memory_initializer(func)
+    def prepare_memory(self, func):
+        """Register a shared memory's preparer"""
+        self._main_component.add_memory_preparer(func)
         return func
 
+    @utils.deprecated("@bot.init_shared_memory", "1.0", "Rename the decorator "
+                      "to @bot.prepare_memory")
+    def init_shared_memory(self, func):
+        """This decorator is deprecated, and it calls @prepare_memory"""
+        return self.prepare_memory(func)
+
     def use(self, *components, only_init=False):
         """Use the provided components in the bot"""
         for component in components:
@@ -156,12 +162,13 @@ def use(self, *components, only_init=False):
                 self._components.append(component)
 
             # Register initializers for the shared memory
+            chains = component._get_chains()
             compid = component._component_id
-            inits = component._get_shared_memory_inits()
-            self._shared_memory.register_inits_list(compid, inits)
+            preparers = chains["memory_preparers"][0]
+            self._shared_memory.register_preparers_list(compid, preparers)
 
             # Register tasks
-            self._scheduler.register_tasks_list(component._get_timers())
+            self._scheduler.register_tasks_list(chains["tasks"][0])
 
     def process(self, update):
         """Process an update object"""
@@ -178,12 +185,20 @@ def run(self, workers=2):
 
     def freeze(self):
         """Return a frozen instance of the bot"""
+        chains = components.merge_chains(self._main_component,
+                                         *self._components)
+
+        # Get the list of commands for the bot
+        commands = self._components[-1]._get_commands()
+        for component in reversed(self._components[:-1]):
+            commands.update(component._get_commands())
+        commands.update(self._main_component._get_commands())
+
         return frozenbot.FrozenBot(self.api, self.about, self.owner,
                                    self.hide_commands, self.before_help,
                                    self.after_help, self.process_backlog,
                                    self.lang, self.itself, self._commands_re,
-                                   self._components+[self._main_component],
-                                   self._scheduler,
+                                   commands, chains, self._scheduler,
                                    self._main_component._component_id,
                                    self._bot_id, self._shared_memory)
 

botogram/components.py

@@ -27,7 +27,7 @@ def __new__(cls, *args, **kwargs):
         self.__processors = []
         self.__no_commands = []
         self.__before_processors = []
-        self.__shared_inits = []
+        self.__memory_preparers = []
         self.__timers = []
 
         self._component_id = str(uuid.uuid4())
@@ -122,13 +122,19 @@ def add_timer(self, interval, func):
 
         self.__timers.append(job)
 
-    def add_shared_memory_initializer(self, func):
+    def add_memory_preparer(self, func):
         """Add a new shared memory's initializer"""
         if not callable(func):
-            raise ValueError("A shared memory initializer must be callable")
+            raise ValueError("A memory preparer must be callable")
+
+        hook = hooks.MemoryPreparerHook(func, self)
+        self.__memory_preparers.append(hook)
 
-        hook = hooks.SharedMemoryInitializerHook(func, self)
-        self.__shared_inits.append(hook)
+    @utils.deprecated("Component.add_shared_memory_initializer", "1.0",
+                      "Rename the method to Component.add_memory_preparer")
+    def add_shared_memory_initializer(self, func):
+        """This method is deprecated, and it calls add_memory_preparer"""
+        self.add_memory_preparer(func)
 
     def _add_no_commands_hook(self, func):
         """Register an hook which will be executed when no commands matches"""
@@ -138,23 +144,49 @@ def _add_no_commands_hook(self, func):
         hook = hooks.NoCommandsHook(func, self)
         self.__no_commands.append(hook)
 
-    def _get_hooks_chain(self):
+    def _get_chains(self):
         """Get the full hooks chain for this component"""
-        return [
+        messages = [
             self.__before_processors[:],
             [self.__commands[name] for name in sorted(self.__commands.keys())],
             self.__no_commands[:],
             self.__processors[:],
         ]
+        return {
+            "messages": messages,
+            "memory_preparers": [self.__memory_preparers],
+            "tasks": [self.__timers],
+        }
 
     def _get_commands(self):
         """Get all the commands this component implements"""
         return self.__commands
 
-    def _get_shared_memory_inits(self):
-        """Get a list of all the shared memory initializers"""
-        return self.__shared_inits
 
-    def _get_timers(self):
-        """Get a list of all the timers"""
-        return self.__timers
+def merge_chains(main, *components):
+    """Merge multiple chains returned by the components"""
+    merged = {}
+    components = [main] + list(reversed(components))
+
+    # First of all, merge all the subchains of the different components
+    # together -- This is a separate step so the order is preserved
+    for component in components:
+        macrochains = component._get_chains()
+        for kind, chains in macrochains.items():
+            if kind not in merged:
+                merged[kind] = []
+
+            for i, chain in enumerate(chains):
+                try:
+                    merged[kind][i] += chain
+                except IndexError:
+                    merged[kind].append(chain[:])
+
+    # Then merge all the subchains together
+    result = {}
+    for kind, chains in merged.items():
+        result[kind] = []
+        for chain in chains:
+            result[kind] += chain
+
+    return result

botogram/defaults.py

@@ -28,6 +28,7 @@ def start_command(self, bot, chat):
         message = []
         if bot.about:
             message.append(bot.about)
+            message.append("")
         message.append(bot._("Use /help to get a list of all the commands."))
 
         chat.send("\n".join(message))
@@ -44,14 +45,15 @@ def _start_command_help(bot):
     def help_command(self, bot, chat, args):
         commands = bot._get_commands()
         if len(args) > 1:
-            message = [bot._("Error: the /help command allows up to one "
+            message = [bot._("*Error!* The `/help` command allows up to one "
                              "argument.")]
         elif len(args) == 1:
             if args[0] in commands:
                 message = self._help_command_message(bot, commands, args[0])
             else:
-                message = [bot._("Unknown command: /%(name)s.", name=args[0]),
-                           bot._("Use /help for a list of commands.")]
+                message = [bot._("*Unknown command:* `/%(name)s`",
+                                 name=args[0]),
+                           bot._("Use /help to get a list of the commands.")]
         else:
             message = self._help_generic_message(bot, commands)
 
@@ -72,19 +74,21 @@ def _help_generic_message(self, bot, commands):
 
         # Show help on commands
         if len(commands) > 0:
-            message.append(bot._("Available commands:"))
+            message.append(bot._("*This bot supports those commands:*"))
             for name in sorted(commands.keys()):
                 # Allow to hide commands in the help message
                 if name in bot.hide_commands:
                     continue
 
                 func = commands[name]
-                docstring = utils.docstring_of(func, bot).split("\n", 1)[0]
-                message.append("/%s - %s" % (name, docstring))
-            message.append(bot._("You can also use '/help <command>' to get "
+                docstring = utils.docstring_of(func, bot, format=True) \
+                                 .split("\n", 1)[0]
+                message.append("/%s `-` %s" % (name, docstring))
+            message.append("")
+            message.append(bot._("You can also use `/help <command>` to get "
                                  "help about a specific command."))
         else:
-            message.append(bot._("No commands available."))
+            message.append(bot._("_This bot has no commands._"))
 
         if len(bot.after_help):
             message.append("")
@@ -104,8 +108,8 @@ def _help_command_message(self, bot, commands, command):
         message = []
 
         func = commands[command]
-        docstring = utils.docstring_of(func, bot)
-        message.append("/%s - %s" % (command, docstring))
+        docstring = utils.docstring_of(func, bot, format=True)
+        message.append("/%s `-` %s" % (command, docstring))
 
         # Show the owner informations
         if bot.owner:
@@ -121,7 +125,7 @@ def _help_command_help(bot):
         """Get the help message of this command"""
         return "\n".join([
             bot._("Show this help message."),
-            bot._("You can also use '/help <command>' to get help about a "
+            bot._("You can also use `/help <command>` to get help about a "
                   "specific command."),
         ])
 
@@ -144,7 +148,7 @@ def no_commands_hook(self, bot, chat, message):
         single_user = chat.type == "private"
         if mentioned or single_user:
             chat.send("\n".join([
-                bot._("Unknown command: /%(name)s", name=command),
-                bot._("Use /help for a list of commands"),
+                bot._("*Unknown command:* `/%(name)s`", name=command),
+                bot._("Use /help to get a list of the commands."),
             ]))
             return True