Begin doc updates for 1.3 [skip ci]

099b997c · Jason Madden · 72164e50 · 099b997c · 099b997c · 099b997c
Commit 099b997c authored Jan 27, 2018 by Jason Madden
Showing with 167 additions and 62 deletions

README.rst README.rst +19 -31

doc/contents.rst doc/contents.rst +2 -1

doc/index.rst doc/index.rst +7 -3

doc/intro.rst doc/intro.rst +30 -27

doc/whatsnew_1_3.rst doc/whatsnew_1_3.rst +109 -0

No files found.
--- a/README.rst
+++ b/README.rst
@@ -6,7 +6,7 @@ gevent_ is a coroutine-based Python networking library.

 Features include:

-* Fast event loop based on libev_.
+* Fast event loop based on libev_ or libuv_.
 * Lightweight execution units based on greenlet_.
 * Familiar API that re-uses concepts from the Python standard library.
 * Cooperative sockets with SSL support.
@@ -18,7 +18,12 @@ simpler implementation and better performance. Read why others `use
 gevent`_ and check out the list of the `open source projects based on
 gevent`_.

-gevent is licensed under the MIT license.
+gevent was written by `Denis Bilenko <http://denisbilenko.com/>`_.
+
+Since version 1.1, gevent is maintained by `NextThought
+<https://nextthought.com>`_ with help from the `contributors
+<https://github.com/gevent/gevent/graphs/contributors>`_ and is
+licensed under the MIT license.

 See `what's new`_ in the latest major release.

@@ -28,9 +33,8 @@ Get gevent
 ==========

 gevent runs on Python >= 2.7, Python >= 3.4, or PyPy >= 5.5 (including
-PyPy2 and PyPy3) (*Note*: PyPy is not supported in Windows). On all
-platforms, installing setuptools is required (this is done
-automatically if working in a virtual environment).
+PyPy2 and PyPy3). On all platforms, installing setuptools is required
+(this is done automatically if working in a virtual environment).

 You can use pip to install gevent::

@@ -38,6 +42,9 @@ You can use pip to install gevent::

 .. tip:: You need Pip 8.0 or later to install the binary wheels.

+.. tip:: You need to install from source, not the manylinux wheels, to
+         use the libuv backend.
+
 Download the latest release from `Python Package Index`_ or clone `the repository`_.

 Read the documentation online at http://www.gevent.org. Additional
@@ -52,7 +59,7 @@ Development

 To install the latest development version::

-  pip install setuptools 'cython>=0.25' git+git://github.com/gevent/gevent.git#egg=gevent
+  pip install setuptools cffi 'cython>=0.27' git+git://github.com/gevent/gevent.git#egg=gevent

 To hack on gevent (using a virtualenv)::

@@ -64,21 +71,10 @@ To hack on gevent (using a virtualenv)::

 .. note::

-   You must have Cython, GNU Make, a C compiler, and the Python
-   development headers installed to build a checkout. Installing CFFI
-   on CPython (it's standard on PyPy) allows building the CFFI backend
-   for testing, and tox is the command used to test multiple versions
-   of Python.
-
-   BSD based systems like FreeBSD and OpenBSD often have BSD Make on
-   the PATH as the default ``make`` command, but building gevent from a
-   source checkout (not a source tarball distributed on PyPI) requires
-   GNU Make. GNU Make is often called ``gmake``. If you experience
-   Makefile-related problems building gevent from source on one of
-   these platforms, you can set the ``MAKE`` environment variable to
-   the executable that invokes GNU Make. For example::
-
-      $ MAKE=gmake python ./setup.py install
+   You must have a C compiler, Cython, and the Python development headers
+   installed to build a checkout. Installing CFFI on CPython (it's
+   standard on PyPy) allows building the CFFI backends for testing, and
+   tox is the command used to test multiple versions of Python.


 Running Tests
@@ -115,14 +111,6 @@ monitor test coverage.
 .. image:: https://coveralls.io/repos/gevent/gevent/badge.svg?branch=master&service=github
   :target: https://coveralls.io/github/gevent/gevent?branch=master

-Likewise, builds on Travis CI will automatically submit updates to
-`landscape.io`_ to monitor code health (adherence to PEP8, absence of
-common code smells, etc).
-
-.. image:: https://landscape.io/github/gevent/gevent/master/landscape.svg?style=flat
-   :target: https://landscape.io/github/gevent/gevent/master
-   :alt: Code Health
-
 .. note:: On Debian, you will probably need ``libpythonX.Y-testsuite``
          installed to run all the tests.

@@ -142,6 +130,7 @@ Windows.
 .. _gevent: http://www.gevent.org
 .. _greenlet: http://pypi.python.org/pypi/greenlet
 .. _libev: http://libev.schmorp.de/
+.. _libuv: http://libuv.org/
 .. _c-ares: http://c-ares.haxx.se/
 .. _inspired by eventlet: http://blog.gevent.org/2010/02/27/why-gevent/
 .. _use gevent: http://groups.google.com/group/gevent/browse_thread/thread/4de9703e5dca8271
@@ -155,6 +144,5 @@ Windows.
 .. _coverage.py: https://pypi.python.org/pypi/coverage/
 .. _coveralls.io: https://coveralls.io/github/gevent/gevent
 .. _AppVeyor: https://ci.appveyor.com/project/denik/gevent
-.. _what's new: http://www.gevent.org/whatsnew_1_2.html
+.. _what's new: http://www.gevent.org/whatsnew_1_3.html
 .. _changelog: http://www.gevent.org/changelog.html
-.. _landscape.io: https://landscape.io/github/gevent/gevent
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -4,8 +4,9 @@ Table Of Contents
 .. toctree::

   intro
-   whatsnew_1_2
+   whatsnew_1_3
   reference
+   whatsnew_1_2
   whatsnew_1_1
   whatsnew_1_0
   changelog

--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,7 +8,7 @@ event loop.

 Features include:

-* **Fast event loop** based on libev (epoll on Linux, kqueue on FreeBSD).
+* **Fast event loop** based on libev or libuv (epoll on Linux, kqueue on FreeBSD).
 * **Lightweight execution units** based on greenlet.
 * API that re-uses concepts from the Python standard library (for example there are :class:`gevent.event.Events` and :class:`gevent.queue.Queues`).
 * :doc:`Cooperative sockets with SSL support <networking>`
@@ -23,8 +23,12 @@ why others `use gevent
 <http://groups.google.com/group/gevent/browse_thread/thread/4de9703e5dca8271>`_
 and check out the list of the `open source projects based on gevent. <https://github.com/gevent/gevent/wiki/Projects>`_

-gevent is written and maintained by `Denis Bilenko
-<http://denisbilenko.com/>`_ with help from the `contributors <https://github.com/gevent/gevent/blob/master/AUTHORS#L1>`_ and is licensed under the MIT license.
+gevent was written by `Denis Bilenko <http://denisbilenko.com/>`_.
+
+Since version 1.1, gevent is maintained by `NextThought
+<https://nextthought.com>`_ with help from the `contributors
+<https://github.com/gevent/gevent/graphs/contributors>`_ and is
+licensed under the MIT license.

 :ref:`Continue reading <installation>` »


--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -6,8 +6,8 @@ gevent is a coroutine-based Python networking library.

 Features include:

-* Fast event loop based on libev (epoll on Linux, kqueue on FreeBSD,
-  select on Mac OS X).
+* Fast event loop based on libev or libuv (epoll on Linux, kqueue on FreeBSD,
+  select on Mac OS X, IOCP on Windows).
 * Lightweight execution units based on greenlet.
 * API that re-uses concepts from the Python standard library (e.g. :class:`gevent.event.Event`, :class:`gevent.queue.Queue`).
 * Cooperative :mod:`socket` and :mod:`ssl` modules.
@@ -22,33 +22,31 @@ Features include:
 Installation and Requirements
 =============================

-`gevent 1.2`_ 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) or 1.1.x (2.6); Python 3 is not supported by 1.0.) gevent requires the
-greenlet__ library.
-
-.. note:: Python 3.3 is no longer actively supported since 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 recommended for the best SSL support;
-          2.7.8 is also tested although it offers a less-secure SSL
-          module.
-
-gevent 1.2 also runs on PyPy 2.6.1 and above, although 5.0 or above is
+`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.
+
+.. note:: Python 3.3 is no longer actively supported in gevent 1.3.
+          since 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 also runs on PyPy 5.5 and above, although 5.9 or above is
 strongly recommended. On PyPy, there are no external dependencies.

 gevent is tested on Windows, OS X, and Linux, and should run on most
 other Unix-like operating systems (e.g., FreeBSD, Solaris, etc.)

-.. note:: gevent does *not* run on PyPy on Windows because the CFFI backend
-          does not build.
-
-.. note:: On Windows, gevent is limited to a maximum of 1024 open
-          sockets due to `limitations in libev`_.
+.. note:: On Windows using the default libev backend, gevent is
+          limited to a maximum of 1024 open sockets due to
+          `limitations in libev`_. This limitation should not exist
+          with the libuv backend.

 gevent and greenlet can both be installed with `pip`_, e.g., ``pip
 install gevent``. On Windows, OS X, and Linux, both gevent and greenlet are
@@ -57,7 +55,8 @@ as pip is at least version 8.0). For other platforms
 without pre-built wheels or if wheel installation is disabled, a C compiler
 (Xcode on OS X) and the Python development package are required.
 `cffi`_ can optionally be installed to build the CFFI backend in
-addition to the Cython backend on CPython.
+addition to the Cython backend on CPython; it is necessary to use the
+libuv backend.

 Development instructions (including building from a source checkout)
 can be found `on PyPI <https://pypi.python.org/pypi/gevent#development>`_.
@@ -65,7 +64,7 @@ can be found `on PyPI <https://pypi.python.org/pypi/gevent#development>`_.
 __ http://pypi.python.org/pypi/greenlet
 .. _`pip`: https://pip.pypa.io/en/stable/installing/
 .. _`wheels`: http://pythonwheels.com
-.. _`gevent 1.2`: whatsnew_1_2.html
+.. _`gevent 1.3`: whatsnew_1_3.html
 .. _`cffi`: https://cffi.readthedocs.io
 .. _`limitations in libev`: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#WIN32_PLATFORM_LIMITATIONS_AND_WORKA

@@ -190,6 +189,8 @@ The event loop provided by libev uses the fastest polling mechanism
 available on the system by default. Please read the `libev documentation`_ for more
 information.

+.. 1.3: libuv update needed
+
 .. As of 1.1 or before, we set the EVFLAG_NOENV so this isn't possible any more.

   It is possible to command libev to
@@ -201,7 +202,9 @@ information.

 .. _`libev documentation`: http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_EVENT_LOOPS

-The Libev API is available under the :mod:`gevent.core` module. Note that
+.. 1.3: libuv update needed
+
+The libev API is available under the :mod:`gevent.core` module. Note that
 the callbacks supplied to the libev API are run in the :class:`~gevent.hub.Hub`
 greenlet and thus cannot use the synchronous gevent API. It is possible to
 use the asynchronous API there, like :func:`gevent.spawn` and

--- a/doc/whatsnew_1_3.rst
+++ b/doc/whatsnew_1_3.rst
+==========================
+ What's new in gevent 1.3
+==========================
+
+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 updated for gevent 1.3.
+
+In general, gevent 1.2 is a smaller update than gevent 1.1, focusing
+on platform support, standard library compatibility, security, bug
+fixes and consistency.
+
+Platform Support
+========================
+
+gevent 1.2 supports Python 2.7, 3.4, 3.5 and 3.6 on the CPython
+(`python.org`_) interpreter. It also supports `PyPy2`_ 4.0.1 and above
+(PyPy2 5.4 or higher is recommended) and PyPy3 5.5.0.
+
+
+.. caution:: Support for Python 2.6 was removed. Support for Python 3.3 is only
+               tested on PyPy3.
+
+.. note:: PyPy is not supported on Windows. (gevent's CFFI backend is not
+         available on Windows.)
+
+Python 3.6 was released recently and is supported at the same level as 3.5.
+
+For ease of installation on Windows and OS X, gevent 1.2 is
+distributed as pre-compiled binary wheels, in addition to source code.
+
+.. _python.org: http://www.python.org/downloads/
+.. _PyPy2: http://pypy.org
+
+Bug Fixes
+=========
+
+Since 1.1.2, gevent 1.2 contains over 240 commits from nine different
+dozen contributors. About two dozen pull requests were merged.
+
+Improved subprocess support
+===========================
+
+In gevent 1.1, subprocess monkey-patching was on by default for the
+first time. Over time this led to discovery of a few issues and corner
+cases that have been fixed in 1.2.
+
+- Setting SIGCHLD to SIG_IGN or SIG_DFL after :mod:`gevent.subprocess`
+  had been used previously could not be reversed, causing
+  ``Popen.wait`` and other calls to hang. Now, if SIGCHLD has been
+  ignored, the next time :mod:`gevent.subprocess` is used this will be
+  detected and corrected automatically. (This potentially leads to
+  issues with :func:`os.popen` on Python 2, but the signal can always
+  be reset again. Mixing the low-level process handling calls,
+  low-level signal management and high-level use of
+  :mod:`gevent.subprocess` is tricky.) Reported in :issue:`857` by
+  Chris Utz.
+- ``Popen.kill`` and ``send_signal`` no longer attempt to send signals
+  to processes that are known to be exited.
+- The :func:`gevent.os.waitpid` function is cooperative in more
+  circumstances. Reported in :issue:`878` by Heungsub Lee.
+
+API Additions
+=============
+
+Numerous APIs offer slightly expanded functionality in this version.
+Look for "changed in version 1.2" or "added in version 1.2" throughout
+the documentation for specifics.
+
+Of particular note, several backwards compatible updates to the
+subprocess module have been backported from Python 3 to Python 2,
+making :mod:`gevent.subprocess` smaller, easier to maintain and in
+some cases safer, while letting gevent clients use the updated APIs
+even on older versions of Python.
+
+If ``concurrent.futures`` is available (Python 3, or if the Python 2
+backport has been installed), then the class
+:class:`gevent.threadpool.ThreadPoolExecutor` is defined to create an
+executor that always uses native threads, even when the system is
+monkey-patched.
+
+Library Updates
+===============
+
+The two C libraries that are bundled with gevent have been updated.
+libev has been updated from 4.20 to 4.23 (`libev release notes`_) and
+c-ares has been updated from 1.10.0 to 1.12.0 (`c-ares release notes`_).
+
+
+.. _libev release notes: https://github.com/gevent/gevent/blob/master/deps/libev/Changes
+.. _c-ares release notes: https://c-ares.haxx.se/changelog.html
+
+Compatibility
+=============
+
+This release is intended to be compatible with 1.1.x with no changes
+to client source code, so long as only non-deprecated and supported
+interfaces were used (as always, internal, non-documented
+implementation details may have changed).
+
+In particular the deprecated ``gevent.coros`` module has been removed
+and ``gevent.corecext`` and ``gevent.corecffi`` have also been removed.
+
+For security, ``gevent.pywsgi`` no longer accepts incoming headers
+containing an underscore, and header values passed to
+``start_response`` cannot contain a carriage return or newline. See
+:issue:`819` and :issue:`775`, respectively.