- Adjusted ``setup.py`` file to support the possible future

removal of the ``setuptools.Feature`` extension from setuptools.
If this keyword isn't present, the setup will still succeed
with setuptools rather than falling back to distutils.  C extension
building can be disabled now also by setting the
DISABLE_SQLALCHEMY_CEXT environment variable.  This variable works
whether or not setuptools is even available. fixes #2986
- using platform.python_implementation() in setup.py to detect CPython.
I've tested this function on OSX and linux on Python 2.6 through 3.4,
including 3.1, 3.2, 3.3.
Unfortunately, on OSX + 3.2 only, it seems to segfault.  I've tried
installing 3.2.5 from the python.org .dmg, building it from source,
and also blew away the whole 3.2 directory, something seems to be wrong
with the "platform" module on that platform only, and there's also no
issue on bugs.python.org; however, I'm going with
it anyway. If someone is using 3.2 on OSX they really should be upgrading.

3 files changed, 68 insertions, 21 deletions

diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index b88a53a88..a9cd75bae 100644
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -12,6 +12,19 @@
     :version: 0.8.6
 
     .. change::
+        :tags: bug, general
+        :tickets: 2986
+        :versions: 0.9.4
+
+        Adjusted ``setup.py`` file to support the possible future
+        removal of the ``setuptools.Feature`` extension from setuptools.
+        If this keyword isn't present, the setup will still succeed
+        with setuptools rather than falling back to distutils.  C extension
+        building can be disabled now also by setting the
+        DISABLE_SQLALCHEMY_CEXT environment variable.  This variable works
+        whether or not setuptools is even available.
+
+    .. change::
         :tags: bug, ext
         :versions: 0.9.4
         :tickets: 2997
diff --git a/doc/build/intro.rst b/doc/build/intro.rst
index 588701ce2..02b5002f2 100644
--- a/doc/build/intro.rst
+++ b/doc/build/intro.rst
@@ -92,7 +92,7 @@ SQLAlchemy supports installation using standard Python "distutils" or
   using the ``setup.py`` script. The C extensions as well as Python 3 builds are supported.
 * **Setuptools or Distribute** - When using `setuptools <http://pypi.python.org/pypi/setuptools/>`_,
   SQLAlchemy can be installed via ``setup.py`` or ``easy_install``, and the C
-  extensions are supported.  
+  extensions are supported.
 * **pip** - `pip <http://pypi.python.org/pypi/pip/>`_ is an installer that
   rides on top of ``setuptools`` or ``distribute``, replacing the usage
   of ``easy_install``.  It is often preferred for its simpler mode of usage.
@@ -113,7 +113,7 @@ This command will download the latest version of SQLAlchemy from the `Python
 Cheese Shop <http://pypi.python.org/pypi/SQLAlchemy>`_ and install it to your system.
 
 .. note::
-	
+
     Beta releases of SQLAlchemy may not be present on Pypi, and may instead
     require a direct download first.
 
@@ -135,26 +135,38 @@ and 3.xx series of cPython.
 
     The C extensions now compile on Python 3 as well as Python 2.
 
-setup.py will automatically build the extensions if an appropriate platform is
+``setup.py`` will automatically build the extensions if an appropriate platform is
 detected. If the build of the C extensions fails, due to missing compiler or
 other issue, the setup process will output a warning message, and re-run the
 build without the C extensions, upon completion reporting final status.
 
 To run the build/install without even attempting to compile the C extensions,
-pass the flag ``--without-cextensions`` to the ``setup.py`` script::
+the ``DISABLE_SQLALCHEMY_CEXT`` environment variable may be specified.  The
+use case for this is either for special testing circumstances, or in the rare
+case of compatibility/build issues not overcome by the usual "rebuild"
+mechanism::
 
-    python setup.py --without-cextensions install
+  # *** only in SQLAlchemy 0.9.4 / 0.8.6 or greater ***
+  export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install
 
-Or with pip::
+.. versionadded:: 0.9.4,0.8.6  Support for disabling the build of
+   C extensions using the ``DISABLE_SQLALCHEMY_CEXT`` environment variable
+   has been added.  This allows control of C extension building whether or not
+   setuptools is available, and additionally works around the fact that
+   setuptools will possibly be **removing support** for command-line switches
+   such as ``--without-extensions`` in a future release.
 
-    pip install --global-option='--without-cextensions' SQLAlchemy
+   For versions of SQLAlchemy prior to 0.9.4 or 0.8.6, the
+   ``--without-cextensions`` option may be used to disable the attempt to build
+   C extensions, provided setupools is in use, and provided the ``Feature``
+   construct is supported by the installed version of setuptools::
 
-.. note::
+      python setup.py --without-cextensions install
+
+   Or with pip::
+
+      pip install --global-option='--without-cextensions' SQLAlchemy
 
-   The ``--without-cextensions`` flag is available **only** if ``setuptools``
-   or ``distribute`` is installed.  It is not available on a plain Python ``distutils``
-   installation.  The library will still install without the C extensions if they
-   cannot be built, however.
 
 Installing on Python 3
 ----------------------------------
diff --git a/setup.py b/setup.py
index f682081df..298dc8bb4 100644
--- a/setup.py
+++ b/setup.py
@@ -10,18 +10,33 @@ import sys
 from distutils.command.build_ext import build_ext
 from distutils.errors import (CCompilerError, DistutilsExecError,
                               DistutilsPlatformError)
+
+has_feature = False
 try:
-    from setuptools import setup, Extension, Feature
-    has_setuptools = True
+    from setuptools import setup, Extension
+    try:
+        # see
+        # https://bitbucket.org/pypa/setuptools/issue/65/deprecate-and-remove-features,
+        # where they may remove Feature.
+        from setuptools import Feature
+        has_feature = True
+    except ImportError:
+        pass
 except ImportError:
-    has_setuptools = False
     from distutils.core import setup, Extension
-    Feature = None
 
-cmdclass = {}
-pypy = hasattr(sys, 'pypy_version_info')
-jython = sys.platform.startswith('java')
+try:
+    import platform
+except ImportError:
+    pypy = hasattr(sys, 'pypy_version_info')
+    jython = sys.platform.startswith('java')
+    cpython = not pypy and not jython
+else:
+    cpython = platform.python_implementation() == 'CPython'
+
 py3k = False
+
+cmdclass = {}
 extra = {}
 if sys.version_info < (2, 6):
     raise Exception("SQLAlchemy requires Python 2.6 or higher.")
@@ -100,7 +115,7 @@ r_file.close()
 def run_setup(with_cext):
     kwargs = extra.copy()
     if with_cext:
-        if Feature:
+        if has_feature:
             kwargs['features'] = {'cextensions': Feature(
                     "optional C speed-enhancements",
                     standard=True,
@@ -137,13 +152,20 @@ def run_setup(with_cext):
             **kwargs
           )
 
-if pypy or jython:
+if not cpython:
     run_setup(False)
     status_msgs(
         "WARNING: C extensions are not supported on " +
             "this Python platform, speedups are not enabled.",
         "Plain-Python build succeeded."
     )
+elif os.environ.get('DISABLE_SQLALCHEMY_CEXT'):
+    run_setup(False)
+    status_msgs(
+        "DISABLE_SQLALCHEMY_CEXT is set; not attempting to build C extensions.",
+        "Plain-Python build succeeded."
+    )
+
 else:
     try:
         run_setup(True)