Fill in whatsnew_1_3.rst [skip ci]

CHANGES.rst

@@ -24,6 +24,8 @@
 
 - The bundled libuv is now 1.20, up from 1.19.2. See :issue:`1177`.
 
+- The long-deprecated and undocumented module ``gevent.wsgi`` was removed.
+
 1.3b1 (2018-04-13)
 ==================
 

doc/api/gevent.event.rst

-:mod:`gevent.event` -- Notifications of multiple listeners
-==========================================================
+============================================================
+ :mod:`gevent.event` -- Notifications of multiple listeners
+============================================================
 
 .. module:: gevent.event
 

doc/api/gevent.rst

@@ -12,12 +12,16 @@ discussed here.
 
 .. autodata:: __version__
 
-See :class:`gevent.Greenlet` for information about greenlet objects.
-
 .. seealso:: :mod:`gevent.util`
 
+Working With Greenlets
+======================
+
+See :class:`gevent.Greenlet` for more information about greenlet
+objects.
+
 Creating Greenlets
-==================
+------------------
 
 .. autofunction:: spawn
 .. autofunction:: spawn_later
@@ -25,7 +29,7 @@ Creating Greenlets
 
 
 Getting Greenlets
-=================
+-----------------
 
 .. function:: getcurrent()
 
@@ -34,13 +38,12 @@ Getting Greenlets
    or :class:`greenlet.greenlet`.
 
 Stopping Greenlets
-==================
+------------------
 
 .. autofunction:: kill(greenlet, exception=GreenletExit)
 
 .. autofunction:: killall(greenlets, exception=GreenletExit, block=True, timeout=None)
 
-
 Sleeping
 ========
 

doc/api/gevent.wsgi.rst

-
-==============================================================================
- :mod:`gevent.wsgi` -- Backwards compatibility alias for :mod:`gevent.pywsgi`
-==============================================================================
-
-In the past, this module used libevent's http support, but that was dropped
-with the introduction of libev. libevent's http support had several
-limitations, including not supporting stream, not supporting
-pipelining, and not supporting SSL.
-
-This module now simply re-exports the contents of the
-:mod:`gevent.pywsgi` module.
-
-.. deprecated:: 1.1
-   Use :mod:`gevent.pywsgi`

doc/api/index.rst

@@ -86,7 +86,6 @@ Deprecated Modules
 .. toctree::
 
    gevent.ares
-   gevent.wsgi
 
 Examples
 ========

doc/contents.rst

@@ -11,6 +11,7 @@ Introduction and Basics
    intro
    whatsnew_1_3
    api/gevent
+   api/gevent.greenlet
    servers
    dns
    monitoring

doc/intro.rst

@@ -9,21 +9,12 @@
 Installation and Requirements
 =============================
 
-`gevent 1.3`_ runs on Python 2 and Python 3. Version 2.7 of Python 2
-is supported, and versions 3.4, 3.5 and 3.6 of Python 3 are supported.
-(Users of older versions of Python 2 need to install gevent 1.0.x
-(2.5), 1.1.x (2.6) or 1.2.x (<=2.7.8); gevent 1.2 can be installed on
-Python 3.3.) gevent requires the greenlet__ library and will install
-the `cffi`_ library by default on Windows.
-
-.. note:: Python 3.3 is no longer actively supported in gevent 1.2
-          because it is not supported by the Python developers. However,
-          it should continue to work with gevent 1.2 with the same
-          level of support as gevent 1.1. For Python 3.3, version
-          3.3.5 or newer is required to use the gevent's SSL support
-          due to bugs in the standard library of older versions. For
-          Python 2, 2.7.9 or newer is required; 2.7.8 is not tested
-          but probably runs, albeit with a less secure SSL module.
+`gevent 1.3`_ runs on Python 2.7 and Python 3. Releases 3.4, 3.5 and
+3.6 of Python 3 are supported. (Users of older versions of Python 2
+need to install gevent 1.0.x (2.5), 1.1.x (2.6) or 1.2.x (<=2.7.8);
+gevent 1.2 can be installed on Python 3.3.) gevent requires the
+greenlet__ library and will install the `cffi`_ library by default on
+Windows.
 
 gevent 1.3 also runs on PyPy 5.5 and above, although 5.9 or above is
 strongly recommended. On PyPy, there are no external dependencies.
@@ -46,6 +37,26 @@ without pre-built wheels or if wheel installation is disabled, a C compiler
 addition to the Cython backend on CPython; it is necessary to use the
 libuv backend.
 
+.. note::
+
+   On Linux, you'll need to install gevent from source if you wish to
+   use the libuv loop implementation. This is because the `manylinux1
+   <https://www.python.org/dev/peps/pep-0513/>`_ specification for the
+   distributed wheels does not support libuv. The `cffi`_ library
+   *must* be installed at build time.
+
+The `psutil <https://pypi.org/project/psutil>`_ library is needed to
+monitor memory usage.
+
+`zope.event <https://pypi.org/project/zope.event>`_ is highly
+recommended for configurable event support; it can be installed with
+the ``events`` extra, e.g., ``pip install gevent[events]``.
+
+`dnspython <https://pypi.org/project/dnspython>`_ is required for the
+new pure-Python resolver, and on Python 2, so is `idna
+<https://pypi.org/project/idna>`_. They can be installed with the
+``dnspython`` extra.
+
 Development instructions (including building from a source checkout)
 can be found `on PyPI <https://pypi.python.org/pypi/gevent#development>`_.
 

doc/monitoring.rst

@@ -56,6 +56,9 @@ and their stack traces. The function
 information). The greenlets are organized into a tree based on the
 greenlet that spawned them.
 
+The ``print_run_info`` function is commonly hooked up to a signal
+handler to get the application state at any given time.
+
 For each greenlet the following information is printed:
 
 - Its current execution stack
@@ -75,7 +78,6 @@ For each greenlet the following information is printed:
 The greenlet tree itself is represented as an object that you can also
 use for your own purposes: :class:`gevent.util.GreenletTree`.
 
-
 Profiling
 =========
 

doc/whatsnew_1_3.rst

@@ -2,6 +2,8 @@
  What's new in gevent 1.3
 ==========================
 
+.. currentmodule:: gevent
+
 .. toctree::
    :maxdepth: 2
 
@@ -11,13 +13,15 @@ Detailed information on what has changed is available in the
 :doc:`changelog`. This document summarizes the most important changes
 since :doc:`gevent 1.2 <whatsnew_1_2>`.
 
-.. caution:: This document has not yet been fully updated for gevent 1.3.
-
 gevent 1.3 is an important update for performance, debugging and
 monitoring, and platform support. It introduces an (optional) `libuv
 <http://libuv.org>`_ loop implementation and supports PyPy on Windows.
 See :ref:`gevent-configuration` for information on how to use libuv.
 
+Since gevent 1.2.2 there have been about 450 commits from a half-dozen
+contributors. Almost 100 pull requests and more than 100 issues have
+been closed.
+
 Platform Support
 ================
 
@@ -25,39 +29,105 @@ gevent 1.3 supports Python 2.7, 3.4, 3.5, 3.6 and 3.7 on the CPython
 (`python.org`_) interpreter. It also supports `PyPy2`_ 5.8.0 and above
 (PyPy2 5.10 or higher is recommended) and PyPy3 5.10.0.
 
-.. caution:: Python 2.7.8 and below (Python 2.7 without a modern
+.. caution::
+
+   Python 2.7.8 and below (Python 2.7 without a modern
    ``ssl`` module), is no longer tested or supported. The
    support code remains in this release and gevent can be
    installed on such implementations, but such usage is not
-             supported.
+   supported. Support for Python 2.7.8 will be removed in the next
+   major version of gevent.
 
-.. note:: PyPy is now supported on Windows with the libuv loop implementation.
+.. note::
+
+   PyPy is now supported on Windows with the libuv loop
+   implementation.
 
 Python 3.7 is in the process of release right now and gevent is tested
-with 3.7b2.
+with 3.7b3.
 
-For ease of installation on Windows and OS X, gevent 1.3 is
+For ease of installation on Windows, OS X and Linux, gevent 1.3 is
 distributed as pre-compiled binary wheels, in addition to source code.
 
-.. note:: On Linux, you'll need to install gevent from source if you
-          wish to use the libuv loop implementation. This is because
-          the `manylinux1
-          <https://www.python.org/dev/peps/pep-0513/>`_ specification
-          for the distributed wheels does not support libuv.
+.. note::
+
+   On Linux, you'll need to install gevent from source if you wish to
+   use the libuv loop implementation. This is because the `manylinux1
+   <https://www.python.org/dev/peps/pep-0513/>`_ specification for the
+   distributed wheels does not support libuv. The CFFI library *must*
+   be installed at build time.
 
 .. _python.org: http://www.python.org/downloads/
 .. _PyPy2: http://pypy.org
 
-Bug Fixes
-=========
-
-TODO: How many commits and contributors? How many pull requests merged?
+Greenlet Attributes
+===================
+
+:class:`Greenlet` objects have gained some useful new
+attributes:
+
+- :attr:`Greenlet.spawning_greenlet` is the greenlet that created this
+  greenlet. Since the ``parent`` is usually the hub, this can be more
+  useful.
+- :attr:`Greenlet.spawn_tree_locals` is a dictionary of values
+  maintained through the spawn tree. This is handy to share values
+  between a set of greenlets, for example, all those involved in
+  processing a request.
+- :attr:`Greenlet.spawning_stack` is a `frame` -like object that
+  captures where the greenlet was created.
+- :attr:`Greenlet.minimal_ident` is a small integer unique across all
+  greenlets.
+- :attr:`Greenlet.name` is a string printed in the greenlet's repr by default.
+
+"Raw" greenlets created with `spawn_raw` default to having the
+``spawning_parent`` and ``spawn_tree_locals``.
+
+This extra data is printed by the new
+:func:`gevent.util.print_run_info` function.
+
+Performance
+===========
+
+gevent 1.3 uses Cython on CPython to compile several performance
+critical modules. As a result, overall performance is improved.
+Specifically, queues are up to 5 times faster, pools are 10-20%
+faster, and the :class:`gevent.local.local` is up to 40 times faster.
+See :pr:`1156`, :pr:`1155`, :pr:`1117` and :pr:`1154`.
+
+
+Better Behaved Callbacks
+========================
+
+In gevent 1.2.2, event loop callbacks (including things like
+``sleep(0)``) would be run in sequence until we ran them all, or until
+we ran 10,000. Simply counting the number of callbacks could lead to
+no IO being serviced for an arbitrary, unbound, amount of time. To
+correct this, gevent 1.3 introduces `gevent.getswitchinterval` and
+will run callbacks for only (approximately) that amount of time before
+checking for IO. (This is similar to the way that Python 2 counted
+bytecode instructions between thread switches but Python 3 uses the
+more deterministic timer approach.) The hope is that this will result
+in "smoother" application behaviour and fewer pitfalls. See
+:issue:`1072` for more details.
+
+Monitoring and Debugging
+========================
+
+Many of the new greenlet attributes are useful for monitoring and
+debugging gevent applications. gevent also now has the (optional)
+ability to monitor for greenlets that call blocking functions and
+stall the event loop and to periodically check if the application has
+exceeded a configured memory limit. See :doc:`monitoring` for more
+information.
 
 
 New Pure-Python DNS Resolver
 ============================
 
-WRITE ME.
+The `dnspython <https://pypi.org/project/dnspython>`_ library is a
+new, pure-Python option for :doc:`/dns`. Benchmarks show it to be
+faster than the existing c-ares resolver and it is also more stable on
+PyPy. The c-ares resolver may be deprecated and removed in the future.
 
 API Additions
 =============
@@ -66,6 +136,21 @@ Numerous APIs offer slightly expanded functionality in this version.
 Look for "changed in version 1.3" or "added in version 1.3" throughout
 the documentation for specifics.
 
+A few changes of note:
+
+- The low-level watcher objects now have a
+  :func:`~gevent._interfaces.IWatcher.close` method that *must* be
+  called to promptly dispose of native (libev or libuv) resources.
+- `gevent.monkey.patch_all` defaults to patching ``Event``.
+- `gevent.subprocess.Popen` accepts the same keyword arguments in
+  Python 2 as it does in Python 3.
+- `gevent.monkey.patch_all` and the various individual patch
+  functions, emit events as patching is being done. This can be used
+  to extend the patching process for new modules. ``patch_all`` also
+  passes all unknown keyword arguments to these events. See
+  :pr:`1169`.
+- The module :mod:`gevent.events` contains the events that parts of
+  gevent can emit. It will use :mod:`zope.event` if that is installed.
 
 Library Updates
 ===============
@@ -89,4 +174,7 @@ The :doc:`resolvers <dns>` have been refactored. As a result,
 by alias (e.g., 'thread') in the ``GEVENT_RESOLVER`` environment
 variable continues to work as before.
 
-TODO: Remove deprecated gevent.wsgi package.
+The internal module ``gevent._threading`` was significantly
+refactored. The long-deprecated module ``gevent.wsgi`` was removed.
+
+..  LocalWords:  Greenlet

src/gevent/wsgi.py

-"""Backwards compatibility alias for :mod:`gevent.pywsgi`.
-
-In the past, this used libevent's http support, but that was dropped
-with the introduction of libev. libevent's http support had several
-limitations, including not supporting stream, not supporting
-pipelining, and not supporting SSL.
-
-.. deprecated:: 1.1
-   Use :mod:`gevent.pywsgi`
-"""
-
-from gevent.pywsgi import * # pylint:disable=wildcard-import,unused-wildcard-import
-import gevent.pywsgi as _pywsgi
-__all__ = _pywsgi.__all__
-del _pywsgi