docs: move mitogen.utils docs to Sphinx.

wip-fakessh-exit-status
David Wilson 7 years ago
parent 270b242ec5
commit 6a10ab605e

@ -675,8 +675,58 @@ Broker Class
Utility Functions Utility Functions
================= =================
.. automodule:: mitogen.utils .. module:: mitogen.utils
:members:
A random assortment of utility functions useful on masters and children.
.. currentmodule:: mitogen.utils
.. function:: disable_site_packages
Remove all entries mentioning ``site-packages`` or ``Extras`` from the
system path. Used primarily for testing on OS X within a virtualenv, where
OS X bundles some ancient version of the :py:mod:`six` module.
.. currentmodule:: mitogen.utils
.. function:: log_to_file (path=None, io=True, level='INFO')
Install a new :py:class:`logging.Handler` writing applications logs to the
filesystem. Useful when debugging slave IO problems.
:param str path:
If not ``None``, a filesystem path to write logs to. Otherwise, logs
are written to :py:data:`sys.stderr`.
:param bool io:
If ``True``, include extremely verbose IO logs in the output. Useful
for debugging hangs, less useful for debugging application code.
:param str level:
Name of the :py:mod:`logging` package constant that is the minimum
level to log at. Useful levels are ``DEBUG``, ``INFO``, ``WARNING``,
and ``ERROR``.
.. currentmodule:: mitogen.utils
.. function:: run_with_router(func, \*args, \**kwargs)
Arrange for `func(router, \*args, \**kwargs)` to run with a temporary
:py:class:`mitogen.master.Router`, ensuring the Router and Broker are
correctly shut down during normal or exceptional return.
:returns:
`func`'s return value.
.. currentmodule:: mitogen.utils
.. decorator:: with_router
Decorator version of :py:func:`run_with_router`. Example:
.. code-block:: python
@with_router
def do_stuff(router, arg):
pass
do_stuff(blah, 123)
Exceptions Exceptions

@ -1,6 +1,3 @@
"""
A random assortment of utility functions useful on masters and slaves.
"""
import logging import logging
import sys import sys
@ -14,17 +11,12 @@ LOG = logging.getLogger('mitogen')
def disable_site_packages(): def disable_site_packages():
"""Remove all entries mentioning site-packages or Extras from the system
path. Used primarily for testing on OS X within a virtualenv, where OS X
bundles some ancient version of the 'six' module."""
for entry in sys.path[:]: for entry in sys.path[:]:
if 'site-packages' in entry or 'Extras' in entry: if 'site-packages' in entry or 'Extras' in entry:
sys.path.remove(entry) sys.path.remove(entry)
def log_to_file(path=None, io=True, level='INFO'): def log_to_file(path=None, io=True, level='INFO'):
"""Install a new :py:class:`logging.Handler` writing applications logs to
the filesystem. Useful when debugging slave IO problems."""
log = logging.getLogger('') log = logging.getLogger('')
if path: if path:
fp = open(path, 'w', 1) fp = open(path, 'w', 1)
@ -45,9 +37,6 @@ def log_to_file(path=None, io=True, level='INFO'):
def run_with_router(func, *args, **kwargs): def run_with_router(func, *args, **kwargs):
"""Arrange for `func(router, *args, **kwargs)` to run with a temporary
:py:class:`mitogen.master.Router`, ensuring the Router and Broker are
correctly shut down during normal or exceptional return."""
broker = mitogen.master.Broker() broker = mitogen.master.Broker()
router = mitogen.master.Router(broker) router = mitogen.master.Router(broker)
try: try:
@ -58,16 +47,6 @@ def run_with_router(func, *args, **kwargs):
def with_router(func): def with_router(func):
"""Decorator version of :py:func:`run_with_router`. Example:
.. code-block:: python
@with_router
def do_stuff(router, arg):
pass
do_stuff(blah, 123)
"""
def wrapper(*args, **kwargs): def wrapper(*args, **kwargs):
return run_with_router(func, *args, **kwargs) return run_with_router(func, *args, **kwargs)
wrapper.func_name = func.func_name wrapper.func_name = func.func_name

Loading…
Cancel
Save