Deprecate Trolliustrollius-2.1

9 files changed, 130 insertions, 0 deletions

diff --git a/doc/asyncio.rst b/doc/asyncio.rst
index 011a9a8..dd4cef3 100644
--- a/doc/asyncio.rst
+++ b/doc/asyncio.rst
@@ -2,6 +2,9 @@
 Trollius and asyncio
 ++++++++++++++++++++
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Differences between Trollius and asyncio
 ========================================
 
diff --git a/doc/changelog.rst b/doc/changelog.rst
index 23640a7..d4750cf 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -2,11 +2,15 @@
 Change log
 ++++++++++
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Version 2.1
 ===========
 
 Changes:
 
+* :ref:`The Trollius project is now deprecated <deprecated>`.
 * Ugly hack to support Python 3.5 with the PEP 479. asyncio coroutines are
   not supported on Python 3.5.
 * Better exception traceback. Patch written by Dhawal Yogesh Bhanushali.
diff --git a/doc/deprecated.rst b/doc/deprecated.rst
new file mode 100644
index 0000000..f5f5743
--- /dev/null
+++ b/doc/deprecated.rst
@@ -0,0 +1,98 @@
+.. _deprecated:
+
+Trollius is deprecated
+======================
+
+.. warning::
+   The Trollius project is now deprecated!
+
+Trollius is deprecated since the release 2.1. The maintainer of Trollius,
+Victor Stinner, doesn't want to maintain the project anymore for many reasons.
+This page lists some reasons.
+
+DON'T PANIC! There is the asyncio project which has the same API and is well
+maintained! Only trollius is deprecated.
+
+Since the Trollius is used for some projects in the wild, Trollius will
+not disappear. You can only expect *minimum* maintenance like minor bugfixes.
+Don't expect new features nor synchronization with the latest asyncio.
+
+To be clear: I am looking for a new maintainer. If you want to take over
+trollius: please do it, I will give you everything you need (and maybe more!).
+
+asyncio
+-------
+
+`asyncio is here <https://github.com/python/asyncio>`_! asyncio is well
+maintainted, has a growing community, has many libraries and don't stop
+evolving to be enhanced by users feedbacks. I (Victor Stinner) even heard that
+it is fast!
+
+asyncio requires Python 3.3 or newer. Yeah, you all have a long list of reasons
+to not port your legacy code for Python 3. But I have my own reasons to prefer
+to invest in the Python 3 rather than in legacy Python (Python 2).
+
+
+No Trollius Community
+---------------------
+
+* Very the asyncio is growing everyday, there is no trollius community.
+  Sadly, asyncio libraries don't work for trollius.
+* Only :ref:`very few libraries support Trollius <libraries>`: to be clear,
+  there is no HTTP client for Trollius, whereas HTTP is the most common
+  protocol in 2015.
+* It's a deliberate choice of library authors to not support Trollius to
+  keep a simple code base. The Python 3 is simpler than Python 2: supporting
+  Python 2 in a library requires more work. For example, aiohttp doesn't
+  want to support trollius.
+
+Python 2
+--------
+
+* Seriously? Come on! Stop procrastination and upgrade your code to Python 3!
+
+Lack of interest
+----------------
+
+* The Trollius project was created to replace eventlet with asyncio (trollius)
+  in the OpenStack project, but replacing eventlet with trollius has failed for
+  different reasons. The original motivation is gone.
+
+Technical issues with trollius
+------------------------------
+
+* While Trollius API is "simple", the implementation is very complex to be
+  efficient on all platforms.
+* Trollius requires :ref:`backports <backports>` of libraries to support
+  old Python versions. These backports are not as well supported as the version
+  in the Python standard library.
+* Supporting Python 2.7, Python 3.3 and Python 3.5 in the same code base
+  and supporting asyncio is very difficult. Generators and coroutines changed
+  a lot in each Python version. For example, hacks are required to support
+  Python 3.5 with the PEP 479 which changed the usage of the ``StopIteration``
+  exception. Trollius initially also supported Python 2.6 and 3.2.
+
+Technical issues related to asyncio and yield from
+--------------------------------------------------
+
+* Synchronizing trollius with asyncio is a complex, tricky and error-prone task
+  which requires to be very carefull and a lot of manual changes.
+* Porting Python 3 asyncio to Python 2 requires a lot of subtle changes which
+  takes a lot of time at each synchronization.
+* It is not possible to use asyncio ``yield from`` coroutines in Python 2,
+  since the ``yield from`` instruction raises a ``SyntaxError`` exceptions.
+  Supporting Trollius and asyncio requires to duplicate some parts of the
+  library and application code which makes the code more complex and more
+  difficult to maintain.
+* Trollius coroutines are slower than asyncio coroutines: the ``yield``
+  instruction requires to delegate manually nested coroutines, whereas the
+  ``yield from`` instruction delegates them directly in the Python language.
+  asyncio requires less loop iterations than trollius for the same nested
+  coroutine.
+
+Other technical issues
+----------------------
+
+* Building wheel packages on Windows is difficult (need a running Windows,
+  need working Windows SDKs for each version of Python, need to test
+  and fix bugs specific to Windows, etc.)
diff --git a/doc/dev.rst b/doc/dev.rst
index c0bbf36..a6a3fcd 100644
--- a/doc/dev.rst
+++ b/doc/dev.rst
@@ -1,6 +1,9 @@
 Run tests
 =========
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Run tests with tox
 ------------------
 
diff --git a/doc/index.rst b/doc/index.rst
index cb344e4..afc5167 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,6 +1,9 @@
 Trollius
 ========
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 .. image:: trollius.jpg
    :alt: Trollius altaicus from Khangai Mountains (Mongòlia)
    :align: right
@@ -58,6 +61,7 @@ Table Of Contents
 
 .. toctree::
 
+   deprecated
    using
    install
    libraries
diff --git a/doc/install.rst b/doc/install.rst
index 845e6e5..d67aa59 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -2,6 +2,9 @@
 Install Trollius
 ++++++++++++++++
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Trollius supports Python 2.7, 3.3 and 3.4.
 
 There is an experimental support of Python 3.5. Issues with Python 3.5:
@@ -94,6 +97,7 @@ extension using::
 
     C:\Python27\python.exe setup.py build_ext
 
+.. _backports:
 
 Backports
 =========
diff --git a/doc/libraries.rst b/doc/libraries.rst
index 424fd28..0793914 100644
--- a/doc/libraries.rst
+++ b/doc/libraries.rst
@@ -1,7 +1,12 @@
+.. _libraries:
+
 ++++++++++++++++++
 Trollius Libraries
 ++++++++++++++++++
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Libraries compatible with asyncio and trollius
 ==============================================
 
diff --git a/doc/using.rst b/doc/using.rst
index c730f86..c8185dc 100644
--- a/doc/using.rst
+++ b/doc/using.rst
@@ -2,6 +2,9 @@
 Using Trollius
 ++++++++++++++
 
+.. warning::
+   :ref:`The Trollius project is now deprecated! <deprecated>`
+
 Documentation of the asyncio module
 ===================================
 
diff --git a/setup.py b/setup.py
index 2a3df46..b42cba1 100644
--- a/setup.py
+++ b/setup.py
@@ -79,4 +79,10 @@ install_options = {
 if SETUPTOOLS:
     install_options['install_requires'] = requirements
 
+print("!!! WARNING !!! The Trollius project is now deprecated!")
+print("")
+
 setup(**install_options)
+
+print("")
+print("!!! WARNING !!! The Trollius project is now deprecated!")