diff --git a/docs/api.rst b/docs/api.rst index 89b39f77..961b8790 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -20,7 +20,11 @@ mitogen Package mitogen.core ------------ -.. automodule:: mitogen.core +.. module:: mitogen.core + +This module implements most package functionality, but remains separate from +non-essential code in order to reduce its size, since it is also serves as the +bootstrap implementation sent to every new slave context. .. function:: mitogen.core.takes_econtext @@ -107,8 +111,24 @@ Utility Functions Exceptions ========== -.. autoclass:: mitogen.core.Error -.. autoclass:: mitogen.core.CallError -.. autoclass:: mitogen.core.ChannelError -.. autoclass:: mitogen.core.StreamError -.. autoclass:: mitogen.core.TimeoutError +.. class:: mitogen.core.Error (fmt, \*args) + + Base for all exceptions raised by Mitogen. + +.. class:: mitogen.core.CallError (e) + + Raised when :py:meth:`Context.call() ` fails. + A copy of the traceback from the external context is appended to the + exception message. + +.. class:: mitogen.core.ChannelError (fmt, \*args) + + Raised when a channel dies or has been closed. + +.. class:: mitogen.core.StreamError (fmt, \*args) + + Raised when a stream cannot be established. + +.. autoclass:: mitogen.core.TimeoutError (fmt, \*args) + + Raised when a timeout occurs on a stream. diff --git a/docs/internals.rst b/docs/internals.rst index aec3f775..5da4cce5 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -44,7 +44,38 @@ Other Stream Subclasses ExternalContext Class --------------------- -.. autoclass:: mitogen.core.ExternalContext +.. class:: mitogen.core.ExternalContext + + External context implementation. + + .. attribute:: broker + + The :py:class:`mitogen.core.Broker` instance. + + .. attribute:: context + + The :py:class:`mitogen.core.Context` instance. + + .. attribute:: channel + + The :py:class:`mitogen.core.Channel` over which + :py:data:`CALL_FUNCTION` requests are received. + + .. attribute:: stdout_log + + The :py:class:`mitogen.core.IoLogger` connected to ``stdout``. + + .. attribute:: importer + + The :py:class:`mitogen.core.Importer` instance. + + .. attribute:: stdout_log + + The :py:class:`IoLogger` connected to ``stdout``. + + .. attribute:: stderr_log + + The :py:class:`IoLogger` connected to ``stderr``. mitogen.master @@ -56,6 +87,17 @@ mitogen.master Helper Functions ---------------- +.. function:: mitogen.core.io_op (func, \*args) + + When connected over a TTY (i.e. sudo), disconnection of the remote end is + signalled by EIO, rather than an empty read like sockets or pipes. Ideally + this will be replaced later by a 'goodbye' message to avoid reading from a + disconnected endpoint, allowing for more robust error reporting. + + When connected over a socket (e.g. mitogen.master.create_child()), + ECONNRESET may be triggered by any read or write. + + .. autofunction:: mitogen.master.create_child .. autofunction:: mitogen.master.get_child_modules .. autofunction:: mitogen.master.minimize_source diff --git a/mitogen/core.py b/mitogen/core.py index 4cbf5ef3..a9fecf26 100644 --- a/mitogen/core.py +++ b/mitogen/core.py @@ -1,8 +1,3 @@ -""" -This module implements most package functionality, but remains separate from -non-essential code in order to reduce its size, since it is also serves as the -bootstrap implementation sent to every new slave context. -""" import Queue import cPickle @@ -47,7 +42,6 @@ else: class Error(Exception): - """Base for all exceptions raised by this module.""" def __init__(self, fmt, *args): if args: fmt %= args @@ -55,10 +49,6 @@ class Error(Exception): class CallError(Error): - """Raised when :py:meth:`Context.call() ` - fails. A copy of the traceback from the external context is appended to the - exception message. - """ def __init__(self, e): s = '%s.%s: %s' % (type(e).__module__, type(e).__name__, e) tb = sys.exc_info()[2] @@ -70,6 +60,7 @@ class CallError(Error): def __reduce__(self): return (_unpickle_call_error, (self[0],)) + def _unpickle_call_error(s): assert type(s) is str and len(s) < 10000 inst = CallError.__new__(CallError) @@ -78,15 +69,15 @@ def _unpickle_call_error(s): class ChannelError(Error): - """Raised when a channel dies or has been closed.""" + pass class StreamError(Error): - """Raised when a stream cannot be established.""" + pass class TimeoutError(StreamError): - """Raised when a timeout occurs on a stream.""" + pass class Dead(object): @@ -99,6 +90,7 @@ class Dead(object): def __repr__(self): return '' + def _unpickle_dead(): return _DEAD @@ -133,15 +125,6 @@ def set_cloexec(fd): def io_op(func, *args): - """ - When connected over a TTY (i.e. sudo), disconnection of the remote end is - signalled by EIO, rather than an empty read like sockets or pipes. Ideally - this will be replaced later by a 'goodbye' message to avoid reading from a - disconnected endpoint, allowing for more robust error reporting. - - When connected over a socket (e.g. mitogen.master.create_child()), - ECONNRESET may be triggered by any read or write. - """ try: return func(*args), False except OSError, e: @@ -1076,38 +1059,6 @@ class Broker(object): class ExternalContext(object): - """ - External context implementation. - - .. attribute:: broker - - The :py:class:`mitogen.core.Broker` instance. - - .. attribute:: context - - The :py:class:`mitogen.core.Context` instance. - - .. attribute:: channel - - The :py:class:`mitogen.core.Channel` over which - :py:data:`CALL_FUNCTION` requests are received. - - .. attribute:: stdout_log - - The :py:class:`mitogen.core.IoLogger` connected to ``stdout``. - - .. attribute:: importer - - The :py:class:`mitogen.core.Importer` instance. - - .. attribute:: stdout_log - - The :py:class:`IoLogger` connected to ``stdout``. - - .. attribute:: stderr_log - - The :py:class:`IoLogger` connected to ``stderr``. - """ def _on_broker_shutdown(self): self.channel.close()