diff --git a/docs/api.rst b/docs/api.rst index 400cb818..d10f11f2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -27,7 +27,9 @@ 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 +.. currentmodule:: mitogen.core + +.. function:: takes_econtext Decorator that marks a function or class method to automatically receive a kwarg named `econtext`, referencing the @@ -38,7 +40,9 @@ bootstrap implementation sent to every new slave context. When the function is invoked directly, `econtext` must still be passed to it explicitly. -.. function:: mitogen.core.takes_router +.. currentmodule:: mitogen.core + +.. function:: takes_router Decorator that marks a function or class method to automatically receive a kwarg named `router`, referencing the :py:class:`econtext.core.Router` @@ -61,7 +65,9 @@ be sent to any context that will be used to establish additional child contexts. -.. class:: mitogen.master.Select (receivers=(), oneshot=True) +.. currentmodule:: mitogen.master + +.. class:: Select (receivers=(), oneshot=True) Support scatter/gather asynchronous calls and waiting on multiple receivers, channels, and sub-Selects. Accepts a sequence of @@ -171,14 +177,18 @@ mitogen.fakessh .. automodule:: mitogen.fakessh -.. autofunction:: mitogen.fakessh.run +.. currentmodule:: mitogen.fakessh + +.. autofunction:: run Router Class ============ -.. class:: mitogen.core.Router +.. currentmodule:: mitogen.core + +.. class:: Router Route messages between parent and child contexts, and invoke handlers defined on our parent context. Router.route() straddles the Broker and user @@ -257,7 +267,9 @@ Router Class This may be called from any thread. -.. class:: mitogen.master.Router +.. currentmodule:: mitogen.master + +.. class:: Router Extend :py:class:`mitogen.core.Router` with functionality useful to masters, and child contexts who later become masters. Currently when this @@ -393,7 +405,9 @@ Router Class Context Class ============= -.. class:: mitogen.core.Context +.. currentmodule:: mitogen.core + +.. class:: Context Represent a remote context regardless of connection method. @@ -441,7 +455,9 @@ Context Class No message was received and `deadline` passed. -.. class:: mitogen.master.Context +.. currentmodule:: mitogen.master + +.. class:: Context Extend :py:class:`mitogen.core.Router` with functionality useful to masters, and child contexts who later become masters. Currently when this @@ -519,7 +535,9 @@ Context Class Receiver Class -------------- -.. class:: mitogen.core.Receiver (router, handle=None, persist=True, respondent=None) +.. currentmodule:: mitogen.core + +.. class:: Receiver (router, handle=None, persist=True, respondent=None) Receivers are used to wait for pickled responses from another context to be sent to a handle registered in this context. A receiver may be single-use @@ -608,7 +626,9 @@ Receiver Class Sender Class ------------ -.. class:: mitogen.core.Sender (context, dst_handle) +.. currentmodule:: mitogen.core + +.. class:: Sender (context, dst_handle) Senders are used to send pickled messages to a handle in another context, it is the inverse of :py:class:`mitogen.core.Sender`. @@ -631,7 +651,9 @@ Sender Class Channel Class ------------- -.. class:: mitogen.core.Channel (router, context, dst_handle, handle=None) +.. currentmodule:: mitogen.core + +.. class:: Channel (router, context, dst_handle, handle=None) A channel inherits from :py:class:`mitogen.core.Sender` and `mitogen.core.Receiver` to provide bidirectional functionality. @@ -645,7 +667,9 @@ Channel Class Broker Class ============ -.. autoclass:: mitogen.master.Broker +.. currentmodule:: mitogen.master + +.. autoclass:: Broker :members: :inherited-members: @@ -660,24 +684,26 @@ Utility Functions Exceptions ========== -.. class:: mitogen.core.Error (fmt, \*args) +.. currentmodule:: mitogen.core + +.. class:: Error (fmt, \*args) Base for all exceptions raised by Mitogen. -.. class:: mitogen.core.CallError (e) +.. class:: 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) +.. class:: ChannelError (fmt, \*args) Raised when a channel dies or has been closed. -.. class:: mitogen.core.StreamError (fmt, \*args) +.. class:: StreamError (fmt, \*args) Raised when a stream cannot be established. -.. autoclass:: mitogen.core.TimeoutError (fmt, \*args) +.. class:: TimeoutError (fmt, \*args) Raised when a timeout occurs on a stream. diff --git a/docs/internals.rst b/docs/internals.rst index 675732a5..a2b160b7 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -10,33 +10,48 @@ mitogen.core Side Class ---------- -.. autoclass:: mitogen.core.Side +.. currentmodule:: mitogen.core + +.. autoclass:: Side :members: Stream Classes -------------- -.. autoclass:: mitogen.core.BasicStream +.. currentmodule:: mitogen.core + +.. autoclass:: BasicStream :members: -.. autoclass:: mitogen.core.Stream +.. autoclass:: Stream :members: -.. autoclass:: mitogen.master.Stream +.. currentmodule:: mitogen.master + +.. autoclass:: Stream :members: -.. autoclass:: mitogen.ssh.Stream +.. currentmodule:: mitogen.ssh + +.. autoclass:: Stream + :members: + +.. currentmodule:: mitogen.sudo + +.. autoclass:: Stream :members: Other Stream Subclasses ----------------------- -.. autoclass:: mitogen.core.IoLogger +.. currentmodule:: mitogen.core + +.. autoclass:: IoLogger :members: -.. autoclass:: mitogen.core.Waker +.. autoclass:: Waker :members: @@ -44,7 +59,9 @@ Other Stream Subclasses ExternalContext Class --------------------- -.. class:: mitogen.core.ExternalContext +.. currentmodule:: mitogen.core + +.. class:: ExternalContext External context implementation. @@ -81,7 +98,9 @@ ExternalContext Class mitogen.master ============== -.. class:: mitogen.master.ProcessMonitor +.. currentmodule:: mitogen.master + +.. class:: ProcessMonitor Install a :py:data:`signal.SIGCHLD` handler that generates callbacks when a specific child process has exitted. @@ -105,7 +124,9 @@ These functions exist to support the blocking phase of setting up a new context. They will eventually be replaced with asynchronous equivalents. -.. function:: mitogen.master.iter_read(fd, deadline=None) +.. currentmodule:: mitogen.master + +.. function:: iter_read(fd, deadline=None) Return a generator that arranges for up to 4096-byte chunks to be read at a time from the file descriptor `fd` until the generator is destroyed. @@ -124,7 +145,9 @@ context. They will eventually be replaced with asynchronous equivalents. Attempt to read past end of file. -.. function:: mitogen.master.write_all (fd, s, deadline=None) +.. currentmodule:: mitogen.master + +.. function:: write_all (fd, s, deadline=None) Arrange for all of bytestring `s` to be written to the file descriptor `fd`. @@ -149,7 +172,9 @@ context. They will eventually be replaced with asynchronous equivalents. Helper Functions ---------------- -.. function:: mitogen.core.io_op (func, \*args) +.. currentmodule:: mitogen.core + +.. function:: 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 @@ -160,13 +185,17 @@ Helper Functions ECONNRESET may be triggered by any read or write. -.. function:: mitogen.master.create_child (\*args) +.. currentmodule:: mitogen.master + +.. function:: create_child (\*args) Create a child process whose stdin/stdout is connected to a socket, returning `(pid, socket_obj)`. -.. function:: mitogen.master.tty_create_child (\*args) +.. currentmodule:: mitogen.master + +.. function:: tty_create_child (\*args) Return a file descriptor connected to the master end of a pseudo-terminal, whose slave end is connected to stdin/stdout/stderr of a new child process. @@ -181,7 +210,9 @@ Helper Functions `(pid, fd)` -.. function:: mitogen.master.get_child_modules (path, fullname) +.. currentmodule:: mitogen.master + +.. function:: get_child_modules (path, fullname) Return the canonical names of all submodules of a package `module`. @@ -198,7 +229,9 @@ Helper Functions List of canonical submodule names. -.. autofunction:: mitogen.master.minimize_source (source) +.. currentmodule:: mitogen.master + +.. autofunction:: minimize_source (source) Remove comments and docstrings from Python `source`, preserving line numbers and syntax of empty blocks.