messages: Make module public

docs/api/index.rst

@@ -15,5 +15,6 @@ Pykka API
     futures
     registry
     exceptions
+    messages
     logging
     debug

docs/api/messages.rst

@@ -0,0 +1,8 @@
+========
+Messages
+========
+
+.. automodule:: pykka.messages
+    :members:
+
+    .. versionadded:: 2.0

pykka/_actor.py

@@ -5,7 +5,7 @@
 import threading
 import uuid
 
-from pykka import ActorDeadError, ActorRef, ActorRegistry, _messages
+from pykka import ActorDeadError, ActorRef, ActorRegistry, messages
 
 
 __all__ = ['Actor']
@@ -162,7 +162,7 @@ def stop(self):
 
         It's equivalent to calling :meth:`ActorRef.stop` with ``block=False``.
         """
-        self.actor_ref.tell(_messages.ActorStop())
+        self.actor_ref.tell(messages._ActorStop())
 
     def _stop(self):
         """
@@ -219,7 +219,7 @@ def _actor_loop(self):
         while not self.actor_inbox.empty():
             envelope = self.actor_inbox.get()
             if envelope.reply_to is not None:
-                if isinstance(envelope.message, _messages.ActorStop):
+                if isinstance(envelope.message, messages._ActorStop):
                     envelope.reply_to.set(None)
                 else:
                     envelope.reply_to.set_exception(
@@ -291,16 +291,16 @@ def on_failure(self, exception_type, exception_value, traceback):
 
     def _handle_receive(self, message):
         """Handles messages sent to the actor."""
-        message = _messages.upgrade_internal_message(message)
-        if isinstance(message, _messages.ActorStop):
+        message = messages._upgrade_internal_message(message)
+        if isinstance(message, messages._ActorStop):
             return self._stop()
-        if isinstance(message, _messages.ProxyCall):
+        if isinstance(message, messages.ProxyCall):
             callee = self._get_attribute_from_path(message.attr_path)
             return callee(*message.args, **message.kwargs)
-        if isinstance(message, _messages.ProxyGetAttr):
+        if isinstance(message, messages.ProxyGetAttr):
             attr = self._get_attribute_from_path(message.attr_path)
             return attr
-        if isinstance(message, _messages.ProxySetAttr):
+        if isinstance(message, messages.ProxySetAttr):
             parent_attr = self._get_attribute_from_path(message.attr_path[:-1])
             attr_name = message.attr_path[-1]
             return setattr(parent_attr, attr_name, message.value)

pykka/_proxy.py

@@ -2,7 +2,7 @@
 
 import logging
 
-from pykka import ActorDeadError, _compat, _messages
+from pykka import ActorDeadError, _compat, messages
 
 
 __all__ = ['ActorProxy']
@@ -228,7 +228,7 @@ def __getattr__(self, name):
                 )
             return self._actor_proxies[attr_path]
         else:
-            message = _messages.ProxyGetAttr(attr_path=attr_path)
+            message = messages.ProxyGetAttr(attr_path=attr_path)
             return self.actor_ref.ask(message, block=False)
 
     def __setattr__(self, name, value):
@@ -240,7 +240,7 @@ def __setattr__(self, name, value):
         if name == 'actor_ref' or name.startswith('_'):
             return super(ActorProxy, self).__setattr__(name, value)
         attr_path = self._attr_path + (name,)
-        message = _messages.ProxySetAttr(attr_path=attr_path, value=value)
+        message = messages.ProxySetAttr(attr_path=attr_path, value=value)
         return self.actor_ref.ask(message)
 
 
@@ -275,7 +275,7 @@ def __call__(self, *args, **kwargs):
         the exception will not be reraised. Either way, the exception will
         also be logged. See :ref:`logging` for details.
         """
-        message = _messages.ProxyCall(
+        message = messages.ProxyCall(
             attr_path=self._attr_path, args=args, kwargs=kwargs
         )
         return self.actor_ref.ask(message, block=False)
@@ -291,7 +291,7 @@ def defer(self, *args, **kwargs):
 
         .. versionadded:: 2.0
         """
-        message = _messages.ProxyCall(
+        message = messages.ProxyCall(
             attr_path=self._attr_path, args=args, kwargs=kwargs
         )
         return self.actor_ref.tell(message)

pykka/_ref.py

@@ -1,6 +1,6 @@
 from pykka import ActorDeadError, ActorProxy
 from pykka._envelope import Envelope
-from pykka._messages import ActorStop
+from pykka.messages import _ActorStop
 
 
 __all__ = ['ActorRef']
@@ -135,7 +135,7 @@ def stop(self, block=True, timeout=None):
 
         :return: :class:`pykka.Future`, or a boolean result if blocking
         """
-        ask_future = self.ask(ActorStop(), block=False)
+        ask_future = self.ask(_ActorStop(), block=False)
 
         def _stop_result_converter(timeout):
             try:

pykka/_messages.py → pykka/messages.py

@@ -1,17 +1,45 @@
+"""
+The :mod:`pykka.messages` module contains Pykka's own actor messages.
+
+In general, you should not need to use any of these classes. However, they have
+been made part of the public API so that certain optimizations can be done
+without touching Pykka's internals.
+
+An example is to combine :meth:`~pykka.ActorRef.ask` and :class:`ProxyCall`
+to call a method on an actor without having to spend any resources on creating
+a proxy object::
+
+    reply = actor_ref.ask(
+        ProxyCall(
+            attr_path=['my_method'],
+            args=['foo'],
+            kwargs={'bar': 'baz'}
+        )
+    )
+
+Another example is to use :meth:`~pykka.ActorRef.tell` instead of
+:meth:`~pykka.ActorRef.ask` for the proxy method call, and thus avoid the
+creation of a future for the return value if you don't need it.
+
+It should be noted that these optimizations should only be necessary in very
+special circumstances.
+"""
+
 import warnings
 from collections import namedtuple
 
 
 # Internal actor messages
-ActorStop = namedtuple('ActorStop', [])
+_ActorStop = namedtuple('ActorStop', [])
 
-# Internal proxy messages
+# Public proxy messages
+# TODO Add docstrings to classes and attributes once we drop Python 2.7 support
 ProxyCall = namedtuple('ProxyCall', ['attr_path', 'args', 'kwargs'])
 ProxyGetAttr = namedtuple('ProxyGetAttr', ['attr_path'])
 ProxySetAttr = namedtuple('ProxySetAttr', ['attr_path', 'value'])
 
 
-def upgrade_internal_message(message):
+def _upgrade_internal_message(message):
     """Filter that upgrades dict-based internal messages to the new format.
 
     This is needed for a transitional period because Mopidy < 3 uses
@@ -32,7 +60,7 @@ def upgrade_internal_message(message):
 
     command = message.get('command')
     if command == 'pykka_stop':
-        return ActorStop()
+        return _ActorStop()
     elif command == 'pykka_call':
         return ProxyCall(
             attr_path=message['attr_path'],

tests/test_messages.py

@@ -2,19 +2,19 @@
 
 import pytest
 
-from pykka._messages import (
-    ActorStop,
+from pykka.messages import (
     ProxyCall,
     ProxyGetAttr,
     ProxySetAttr,
-    upgrade_internal_message,
+    _ActorStop,
+    _upgrade_internal_message,
 )
 
 
 @pytest.mark.parametrize(
     'old_format, new_format',
     [
-        ({'command': 'pykka_stop'}, ActorStop()),
+        ({'command': 'pykka_stop'}, _ActorStop()),
         (
             {
                 'command': 'pykka_call',
@@ -42,7 +42,7 @@
 )
 def test_upgrade_internal_message(old_format, new_format):
     with warnings.catch_warnings(record=True) as w:
-        assert upgrade_internal_message(old_format) == new_format
+        assert _upgrade_internal_message(old_format) == new_format
 
         assert len(w) == 1
         assert issubclass(w[0].category, DeprecationWarning)