Adds autodoc for celery.contrib.rdb

celery/contrib/rdb.py

@@ -1,6 +1,8 @@
 """
-Remote debugger for Celery tasks running in multiprocessing pool workers.
+celery.contrib.rdb
+==================
 
+Remote debugger for Celery tasks running in multiprocessing pool workers.
 Inspired by http://snippets.dzone.com/posts/show/7248
 
 **Usage**
@@ -24,13 +26,17 @@ Inspired by http://snippets.dzone.com/posts/show/7248
     Hostname to bind to.  Default is '127.0.01', which means the socket
     will only be accessible from the local host.
 
-.. envvar:: CELERY_RDB_PORt
+.. envvar:: CELERY_RDB_PORT
 
     Base port to bind to.  Default is 6899.
     The debugger will try to find an available port starting from the
     base port.  The selected port will be logged by celeryd.
 
+:copyright: (c) 2009 - 2010 by Ask Solem.
+:license: BSD, see LICENSE for more details.
+
 """
+
 import bdb
 import errno
 import os
@@ -136,6 +142,8 @@ class Rdb(Pdb):
 
 
 def debugger():
+    """Returns the current debugger instance (if any),
+    or creates a new one."""
     rdb = _current[0]
     if rdb is None or not rdb.active:
         rdb = _current[0] = Rdb()
@@ -143,4 +151,5 @@ def debugger():
 
 
 def set_trace():
+    """Set breakpoint at current location."""
     return debugger().set_trace(_frame().f_back)

docs/reference/celery.contrib.rdb.rst

@@ -0,0 +1,7 @@
+.. currentmodule:: celery.contrib.rdb
+
+.. automodule:: celery.contrib.rdb
+
+    .. autofunction:: set_trace
+    .. autofunction:: debugger
+    .. autoclass:: Rdb

docs/reference/index.rst

@@ -27,6 +27,7 @@
     celery.loaders.base
     celery.registry
     celery.states
+    celery.contrib.rdb
     celery.contrib.abortable
     celery.events
     celery.events.state

docs/tutorials/debugging.rst

@@ -0,0 +1,78 @@
+.. _tut-remote_debug:
+
+======================================
+ Debugging Tasks Remotely (using pdb)
+======================================
+
+:mod:`celery.contrib.rdb` is an extended version of :mod:`pdb` that
+enables remote debugging of processes that does not have terminal
+access.
+
+Example usage:
+
+.. code-block:: python
+
+    from celery.contrib import rdb
+    from celery.task import task
+
+    @task
+    def add(x, y):
+        result = x + y
+        rdb.set_trace()  # <- set breakpoint
+        return result
+
+
+:func:`~celery.contrib.rdb.set_trace` sets a breakpoint at the current
+location and creates a socket you can telnet into to remotely debug
+your task.
+
+The debugger may be started by multiple processes at the same time,
+so rather than using a fixed port the debugger will search for an
+available port, starting from the base port (6900 by default).
+The base port can be changed using the environment variable
+:envvar:`CELERY_RDB_PORT`.
+
+By default the debugger will only be available from the local host,
+to enable access from the outside you have to set the environment
+variable :envvar:`CELERY_RDB_HOST`.
+
+When `celeryd` encounters your breakpoint it will log the following
+information::
+
+    [INFO/MainProcess] Got task from broker:
+        tasks.add[d7261c71-4962-47e5-b342-2448bedd20e8]
+    [WARNING/PoolWorker-1] Remote Debugger:6900:
+        Please telnet 127.0.0.1 6900.  Type `exit` in session to continue.
+    [2011-01-18 14:25:44,119: WARNING/PoolWorker-1] Remote Debugger:6900:
+        Waiting for client...
+
+If you telnet the port specified you will be presented
+with a `pdb` shell::
+
+    $ telnet localhost 6900
+    Connected to localhost.
+    Escape character is '^]'.
+    > /opt/devel/demoapp/tasks.py(128)add()
+    -> return result
+    (Pdb)
+
+Enter ``help`` to get a list of available commands,
+It may be a good idea to read the `The Python Debugger`_ manual if
+you have never used `pdb` before.
+
+To demonstrate, we will read the value of the ``result`` variable,
+change it and continue execution of the task::
+
+    (Pdb) result
+    4
+    (Pdb) result = "hello from rdb"
+    (Pdb) continue
+    Connection closed by foreign host.
+
+The result of our vandalism can be seen in the worker logs::
+
+    [2011-01-18 14:35:36,599: INFO/MainProcess] Task
+        tasks.add[d7261c71-4962-47e5-b342-2448bedd20e8] succeeded
+        in 61.481s: 'hello from rdb'
+
+.. _`The Python Debugger`: http://docs.python.org/library/pdb.html