Renamed init_shared_memory to prepare_memory

This also renames add_shared_memory_initializer to add_memory_preparer.
The old method names are now deprecated, and they will continue to work
until botogram 1.0.

Author: Pietro Albini

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_memory_preparers()
         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()
@@ -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:
@@ -157,8 +163,8 @@ def use(self, *components, only_init=False):
 
             # Register initializers for the shared memory
             compid = component._component_id
-            inits = component._get_shared_memory_inits()
-            self._shared_memory.register_inits_list(compid, inits)
+            preparers = component._get_memory_preparers()
+            self._shared_memory.register_preparers_list(compid, preparers)
 
             # Register tasks
             self._scheduler.register_tasks_list(component._get_timers())

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"""
@@ -151,9 +157,9 @@ def _get_commands(self):
         """Get all the commands this component implements"""
         return self.__commands
 
-    def _get_shared_memory_inits(self):
+    def _get_memory_preparers(self):
         """Get a list of all the shared memory initializers"""
-        return self.__shared_inits
+        return self.__memory_preparers
 
     def _get_timers(self):
         """Get a list of all the timers"""

botogram/frozenbot.py

@@ -125,11 +125,17 @@ def timer(self, interval):
         """Register a new timer"""
         raise FrozenBotError("Can't add timers to a bot at runtime")
 
-    def init_shared_memory(self, func):
-        """Add a shared memory initializer"""
-        raise FrozenBotError("Can't register a shared memory initializer to a "
+    def prepare_memory(self, func):
+        """Add a shared memory preparer"""
+        raise FrozenBotError("Can't register a shared memory preparer to a "
                              "bot at runtime")
 
+    @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)
+
     # Those are shortcuts to send messages directly to someone
 
     def send(self, chat, message, preview=True, reply_to=None, syntax=None,

botogram/hooks.py

@@ -66,8 +66,8 @@ class ProcessMessageHook(Hook):
     pass
 
 
-class SharedMemoryInitializerHook(Hook):
-    """Underlying hook for @bot.init_shared_memory"""
+class MemoryPreparerHook(Hook):
+    """Underlying hook for @bot.prepare_memory"""
 
     def call(self, memory):
         return self.func(memory)

botogram/shared.py

@@ -102,7 +102,7 @@ def __init__(self, driver=None):
             driver = LocalDriver()
         self.driver = driver
 
-        self._inits = {}
+        self._preparers = {}
 
     def __reduce__(self):
         return rebuild, (self.driver,)
@@ -111,33 +111,33 @@ def _key_of(self, *parts):
         """Get the key for a shared item"""
         return ":".join(parts)
 
-    def register_inits_list(self, component, inits):
-        """Register a new list to pick initializers from"""
+    def register_preparers_list(self, component, inits):
+        """Register a new list to pick preparers from"""
         # Ignore the request if a list was already registered
-        if component in self._inits:
+        if component in self._preparers:
             return
 
-        self._inits[component] = inits
+        self._preparers[component] = inits
 
     def of(self, bot, component):
         """Get the shared memory of a specific component"""
         memory, is_new = self.driver.get(self._key_of(bot, component))
 
         # Be sure to initialize the shared memory if it's needed
         if is_new:
-            self.apply_inits(component, memory)
+            self.apply_preparers(component, memory)
 
         # Add the lock method to the object
         memory.lock = functools.partial(self.lock, bot, component)
         return memory
 
-    def apply_inits(self, component, memory):
-        """Apply all the inits of a component to a memory"""
-        if component not in self._inits:
+    def apply_preparers(self, component, memory):
+        """Apply all the preparers of a component to a memory"""
+        if component not in self._preparers:
             return
 
-        for init in self._inits[component]:
-            init.call(memory)
+        for preparer in self._preparers[component]:
+            preparer.call(memory)
 
     def switch_driver(self, driver=None):
         """Use another driver for this shared memory"""

docs/api/bot.rst

@@ -207,7 +207,7 @@ components.
 
       :param int interval: The execution interval, in seconds.
 
-   .. py:decoratormethod:: init_shared_memory
+   .. py:decoratormethod:: prepare_memory
 
       The function decorated with this decorator will be called the first time
       you access your bot's shared memory. This allows you to set the initial
@@ -218,11 +218,11 @@ components.
 
       The decorated function will be called providing as first argument a
       dict-like object representing your bot's shared memory. Use it to
-      initialize the things you want in the shared memory.
+      prepare the things you want in the shared memory.
 
       .. code-block:: python
 
-         @bot.init_shared_memory
+         @bot.prepare_memory
          def initialize(shared):
              shared["messages"] = 0
 
@@ -236,6 +236,18 @@ components.
          def count(shared, chat, message, args):
              chat.send("This bot received %s messages" % shared["messages"])
 
+      .. versionchanged:: 0.2
+
+         Before it was called ``init_shared_memory``.
+
+   .. py:decoratormethod:: init_shared_memory
+
+      This decorator was renamed to
+      :py:meth:`~botogram.Bot.prepare_memory` in botogram 0.2.
+      Please use that instead of this.
+
+      .. deprecated:: 0.2 it will be removed in botogram 1.0
+
    .. py:method:: use(component)
 
       Use the provided component in your bot, so the hooks the component

docs/api/components.rst

@@ -175,7 +175,7 @@ about how to create them in the ":ref:`custom-components`" chapter.
       :param int interval: The execution interval, in seconds.
       :param callable func: The function you want to use.
 
-   .. py:method:: add_shared_memory_initializer(func)
+   .. py:method:: add_memory_preparer(func)
 
       The function provided to this method will be called the first time you
       access your component's shared memory. This allows you to set the initial
@@ -196,7 +196,7 @@ about how to create them in the ":ref:`custom-components`" chapter.
              component_name = "counter"
 
              def __init__(self):
-                 self.add_shared_memory_initializer(self.initialize)
+                 self.add_memory_preparer(self.initialize)
                  self.add_process_message_hook(self.increment)
                  self.add_command("count", self.count)
 
@@ -210,3 +210,15 @@ about how to create them in the ":ref:`custom-components`" chapter.
 
              def count(self, shared, chat, message, args):
                  chat.send("This bot received %s messages" % shared["messages"])
+
+      .. versionchanged:: 0.2
+
+         Before it was called ``add_shared_memory_initializer``.
+
+   .. py:method:: add_shared_memory_initializer(func)
+
+      This method was renamed to
+      :py:meth:`~botogram.Component.add_memory_preparer` in botogram 0.2.
+      Please use that instead of this.
+
+      .. deprecated:: 0.2 it will be removed in botogram 1.0

docs/shared-memory.rst

@@ -68,24 +68,24 @@ command which displays the current messages count calculated by the hook above:
 
 .. _shared-memory-inits:
 
-Shared memory initializers
-==========================
+Shared memory preparers
+=======================
 
 In the example above, a big part of the code is just to handle the case when
 the shared memory doesn't contain the ``count`` key, and that's possible only
 at startup. In order to solve this problem, you can use the
-:py:meth:`botogram.Bot.init_shared_memory` decorator.
+:py:meth:`~botogram.Bot.prepare_memory` decorator.
 
 Functions decorated with that decorator will be called only the first time you
 require the shared memory. This means you can use them to set the initial value
 of all the keys you want to use in the shared memory.
 
-For example, let's refactor the code above to use an initializer:
+For example, let's refactor the code above to use a preparer:
 
 .. code-block:: python
 
-   @bot.init_shared_memory
-   def init_shared_memory(shared):
+   @bot.prepare_memory
+   def prepare_memory(shared):
        shared["messages"] = 0
 
    @bot.process_message
@@ -115,8 +115,8 @@ component is used by multiple bots.
 Using shared memory within a component is the same as using it in your bot's
 main code: just require the ``shared`` argument to your component's function
 and botogram will make sure it receives the component's shared memories. To
-add a shared memory initializer, you can instead provide the function to the
-:py:meth:`botogram.Component.add_shared_memory_initializer` method.
+add a shared memory preparer, you can instead provide the function to the
+:py:meth:`~botogram.Component.add_memory_preparer` method.
 
 .. _shared-memory-locks: