diff --git a/doc/conf.py b/doc/conf.py index a2fb194..971e3d5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,7 +22,8 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', + 'sphinx.ext.intersphinx'] # If this is True, '.. todo::' and '.. todolist::' produce output, else they produce # nothing. The default is False. @@ -91,6 +92,9 @@ pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] +# Intersphinx references +intersphinx_mapping = {'http://docs.python.org/': None} + # -- Options for HTML output --------------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index 4dc6882..46ec216 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -45,6 +45,7 @@ Contents basic_usage chat_server_example + ssl threading testing history @@ -66,9 +67,8 @@ Areas That Need Work -------------------- * Not enough test coverage -- the goal is 100%, but we are not there yet. -* Not well-tested on Windows - * The eventlet.processes module is known to not work on Windows. - +* Not well-tested on Windows, though it is a supported platform and bug reports are encouraged. +* The :mod:`eventlet.processes` module is known to not work on Windows. License --------- diff --git a/doc/modules/api.rst b/doc/modules/api.rst index ec4969c..6e329ae 100644 --- a/doc/modules/api.rst +++ b/doc/modules/api.rst @@ -1,5 +1,5 @@ :mod:`api` -- General purpose functions -================== +========================================== .. automodule:: eventlet.api :members: diff --git a/doc/modules/backdoor.rst b/doc/modules/backdoor.rst index 82c88f5..b2bbc04 100644 --- a/doc/modules/backdoor.rst +++ b/doc/modules/backdoor.rst @@ -1,5 +1,5 @@ -:mod:`backdoor` -- Python interactive interpreter within an eventlet instance -================== +:mod:`backdoor` -- Python interactive interpreter within a running process +=============================================================================== .. automodule:: eventlet.backdoor :members: diff --git a/doc/modules/corolocal.rst b/doc/modules/corolocal.rst index 31bdfdd..f4caa33 100644 --- a/doc/modules/corolocal.rst +++ b/doc/modules/corolocal.rst @@ -1,5 +1,5 @@ :mod:`corolocal` -- Coroutine local storage -================== +============================================= .. automodule:: eventlet.corolocal :members: diff --git a/doc/modules/coros.rst b/doc/modules/coros.rst index 7aa44a6..0778279 100644 --- a/doc/modules/coros.rst +++ b/doc/modules/coros.rst @@ -1,5 +1,5 @@ :mod:`coros` -- Coroutine communication patterns -================== +================================================== .. automodule:: eventlet.coros :members: diff --git a/doc/modules/db_pool.rst b/doc/modules/db_pool.rst index 123013e..7a9d887 100644 --- a/doc/modules/db_pool.rst +++ b/doc/modules/db_pool.rst @@ -1,5 +1,5 @@ :mod:`db_pool` -- DBAPI 2 database connection pooling -================== +======================================================== The db_pool module is useful for managing database connections. It provides three primary benefits: cooperative yielding during database operations, concurrency limiting to a database host, and connection reuse. db_pool is intended to be database-agnostic, compatible with any DB-API 2.0 database module. diff --git a/doc/modules/greenio.rst b/doc/modules/greenio.rst index 66b0751..6591964 100644 --- a/doc/modules/greenio.rst +++ b/doc/modules/greenio.rst @@ -1,5 +1,5 @@ :mod:`greenio` -- Greenlet file objects -================== +======================================== .. automodule:: eventlet.greenio :members: diff --git a/doc/modules/pool.rst b/doc/modules/pool.rst index 8e3c980..19ad6aa 100644 --- a/doc/modules/pool.rst +++ b/doc/modules/pool.rst @@ -1,5 +1,5 @@ :mod:`pool` -- Concurrent execution from a pool of coroutines -================== +============================================================== .. automodule:: eventlet.pool :members: diff --git a/doc/modules/proc.rst b/doc/modules/proc.rst index 2b3a9bf..f20433d 100644 --- a/doc/modules/proc.rst +++ b/doc/modules/proc.rst @@ -1,5 +1,5 @@ :mod:`proc` -- Advanced coroutine control -================== +========================================== .. automodule:: eventlet.proc :members: diff --git a/doc/modules/processes.rst b/doc/modules/processes.rst index 02cbb76..3669080 100644 --- a/doc/modules/processes.rst +++ b/doc/modules/processes.rst @@ -1,5 +1,5 @@ :mod:`processes` -- Running child processes -================== +============================================= .. automodule:: eventlet.processes :members: diff --git a/doc/modules/saranwrap.rst b/doc/modules/saranwrap.rst index 1e00369..c9f1802 100644 --- a/doc/modules/saranwrap.rst +++ b/doc/modules/saranwrap.rst @@ -1,5 +1,5 @@ :mod:`saranwrap` -- Running code in separate processes -================== +======================================================= This is a convenient way of bundling code off into a separate process. If you are using Python 2.6, the multiprocessing module probably suits your needs better than saranwrap will. diff --git a/doc/modules/tpool.rst b/doc/modules/tpool.rst index 2423c9c..7aa2863 100644 --- a/doc/modules/tpool.rst +++ b/doc/modules/tpool.rst @@ -1,5 +1,5 @@ :mod:`tpool` -- Thread pooling -================== +================================ .. automodule:: eventlet.tpool :members: diff --git a/doc/modules/util.rst b/doc/modules/util.rst index 76d3c52..d573682 100644 --- a/doc/modules/util.rst +++ b/doc/modules/util.rst @@ -1,5 +1,5 @@ :mod:`util` -- Stdlib wrapping and compatibility functions -================== +=========================================================== .. automodule:: eventlet.util :members: diff --git a/doc/modules/wsgi.rst b/doc/modules/wsgi.rst index 33ecba4..8993dd4 100644 --- a/doc/modules/wsgi.rst +++ b/doc/modules/wsgi.rst @@ -1,5 +1,5 @@ :mod:`wsgi` -- WSGI server -================== +=========================== .. automodule:: eventlet.wsgi :members: diff --git a/doc/ssl.rst b/doc/ssl.rst new file mode 100644 index 0000000..50d7750 --- /dev/null +++ b/doc/ssl.rst @@ -0,0 +1,58 @@ +Using SSL With Eventlet +======================== + +Eventlet makes it easy to use non-blocking SSL sockets. If you're using Python 2.6 or later, you're all set, eventlet wraps the built-in ssl module. If on Python 2.5 or 2.4, you have to install pyOpenSSL_ to use eventlet. + +In either case, the the ``green`` modules handle SSL sockets transparently, just like their standard counterparts. As an example, :mod:`eventlet.green.urllib2` can be used to fetch https urls in as non-blocking a fashion as you please:: + + from eventlet.green import urllib2 + from eventlet import coros + bodies = [coros.execute(urllib2.urlopen, url) + for url in ("https://secondlife.com","https://google.com")] + for b in bodies: + print b.wait().read() + + +With Python 2.6 +---------------- + +To use ssl sockets directly in Python 2.6, use :mod:`eventlet.green.ssl`, which is a non-blocking wrapper around the standard Python :mod:`ssl` module, and which has the same interface. See the standard documentation for instructions on use. + +With Python 2.5 or Earlier +--------------------------- + +Prior to Python 2.6, there is no :mod:`ssl`, so SSL support is much weaker. Eventlet relies on pyOpenSSL to implement its SSL support on these older versions, so be sure to install pyOpenSSL, or you'll get an ImportError whenever your system tries to make an SSL connection. + +Once pyOpenSSL is installed, you can then use the ``eventlet.green`` modules, like :mod:`eventlet.green.httplib` to fetch https urls. You can also use :func:`eventlet.green.socket.ssl`, which is a nonblocking wrapper for :func:`socket.ssl`. + +PyOpenSSL +---------- + +:mod:`eventlet.green.OpenSSL` has exactly the same interface as pyOpenSSL_ '(docs) `_, and works in all versions of Python. This module is much more powerful than :func:`socket.ssl`, and may have some advantages over :mod:`ssl`, depending on your needs. + +Here's an example of a server:: + + from eventlet.green import socket + from eventlet.green.OpenSSL import SSL + + # insecure context, only for example purposes + context = SSL.Context(SSL.SSLv23_METHOD) + context.set_verify(SSL.VERIFY_NONE, lambda *x: True)) + + # create underlying green socket and wrap it in ssl + sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + connection = SSL.Connection(context, sock) + + # configure as server + connection.set_accept_state() + connection.bind(('127.0.0.1', 80443)) + connection.listen(50) + + # accept one client connection then close up shop + client_conn, addr = connection.accept() + print client_conn.read(100) + client_conn.shutdown() + client_conn.close() + connection.close() + +.. _pyOpenSSL: https://launchpad.net/pyopenssl \ No newline at end of file