Ticket #3696: extras_require-3696-10.diff

docs/index.rst

@@ -7 +7 @@
     :maxdepth: 2
     :includehidden:
 
+    installation/index
     core/index
     conch/index
     lore/index

new file docs/installation/howto/optional.rst

@@ +1 @@
+
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+Installing Optional Dependencies
+================================
+
+This document describes how to install optional dependencies that enhance Twisted.
+These dependencies are python packages that Twisted's developers have found useful either for developing Twisted itself or for developing Twisted applications.
+
+The intended audience of this document is someone who is going to use `pip`_ to manage a Twisted installation.
+
+
+What are optional dependencies?
+----------------------------------
+
+Optional dependencies are python packages that are not strictly necessary for Twisted to function but provide some functionality that would otherwise be unavailable.
+
+
+Why use optional dependencies?
+------------------------------
+
+The optional dependencies that Twisted recommends are used regularly by Twisted developers.
+While this is not a guarantee that each dependency combination works on every operating system and python interpreter, it is a good indication that the dependencies *should* work.
+
+
+Which options are supported?
+----------------------------
+
+* **dev** - packages that aid in the development of Twisted itself.
+    * `TwistedChecker`_
+    * `pyflakes`_
+    * `twisted-dev-tools`_
+    * `python-subunit`_
+    * `Sphinx`_
+    * `pydoctor`_
+
+* **tls** - packages that are needed to work with TLS.
+    * `pyOpenSSL`_
+    * `service_identity`_
+
+* **conch** - packages for working with conch/SSH.
+    * `gmpy`_
+    * `pyasn1`_
+    * `pycrypto`_
+
+* **soap** - the `SOAPpy`_ package to work with SOAP.
+
+* **serial** - the `pyserial`_ package to work with serial data.
+
+* **all_non_platform** - installs **dev**, **tls**, **conch**, **soap**, and **serial** options.
+
+* **osx_platform** - **all_non_platform** options and `pyobjc`_ to work with Objective-C apis.
+
+* **windows_platform** - **all_non_platform** options and `pypiwin32`_ to work with Windows's apis.
+
+
+How do I install an optional dependency?
+----------------------------------------
+
+To install optional dependencies one needs to use a slightly different syntax with `pip`_ than normal.
+The following code snippet shows how to tell `pip`_ to install a package and an optional dependency.
+In this example, ``option_name_to_install`` is the optional dependency.
+
+.. code-block:: shell
+
+                $ pip install "twisted[option_name_to_install]"
+
+For a real world example, the following command will install Twisted with the **dev** option.
+
+.. code-block:: shell
+
+                $ pip install "twisted[dev]"
+
+To install multiple options at the same time, one need only provide `pip`_ a comma seperated list of options.
+For example, to install the **dev** and **tls** options, call `pip`_ like so:
+
+.. code-block:: shell
+
+                $ pip install "twisted[dev, tls]"
+
+Lastly, if you are developing Twisted and want to install your development source and an optional depency, use `pip`_ to create an `editable install`_:
+
+.. code-block:: shell
+
+                $ cd /into/directory/containing/Twisted/setup.py
+                $ pip install -e ".[option_to_install]
+
+
+Conclusion
+----------
+
+In this document you've been shown:
+
+#. What optional dependences are.
+#. Which optional dependencies are supported.
+#. How to install optional dependencies using `pip`_.
+
+
+.. _pip: https://pip.pypa.io/en/latest/quickstart.html
+.. _TwistedChecker: https://pypi.python.org/pypi/TwistedChecker
+.. _pyflakes: https://pypi.python.org/pypi/pyflakes
+.. _twisted-dev-tools: https://pypi.python.org/pypi/twisted-dev-tools
+.. _python-subunit: https://pypi.python.org/pypi/python-subunit
+.. _Sphinx: https://pypi.python.org/pypi/Sphinx/1.3b1
+.. _pydoctor: https://pypi.python.org/pypi/pydoctor
+.. _pyOpenSSL: https://pypi.python.org/pypi/pyOpenSSL
+.. _service_identity: https://pypi.python.org/pypi/service_identity
+.. _gmpy: https://pypi.python.org/pypi/gmpy/1.17
+.. _pyasn1: https://pypi.python.org/pypi/pyasn1
+.. _pycrypto: https://pypi.python.org/pypi/pycrypto
+.. _SOAPpy: https://pypi.python.org/pypi/SOAPpy
+.. _pyserial: https://pypi.python.org/pypi/pyserial
+.. _pyobjc: https://pypi.python.org/pypi/pyobjc
+.. _pypiwin32: https://pypi.python.org/pypi/pypiwin32
+.. _`editable install`: https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs
+.. _`extras_require`: https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies

new file docs/installation/index.rst

@@ +1 @@
+
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+Installing Twisted
+==================
+
+.. toctree::
+   :hidden:
+
+   howto/optional
+
+- :doc:`Installing Optional Dependencies <howto/optional>`: documentation
+  on how to install Twisted's optional dependencies.

setup.py

@@ -54 +54 @@
 
     from twisted.python.dist import (
         STATIC_PACKAGE_METADATA, getDataFiles, getExtensions, getAllScripts,
-        getPackages, setup)
+        getPackages, setup, EXTRAS_REQUIRE)
 
     scripts = getAllScripts()
 
@@ -62 +62 @@
         packages=getPackages('twisted'),
         conditionalExtensions=getExtensions(),
         scripts=scripts,
+        extras_require=EXTRAS_REQUIRE,
         data_files=getDataFiles('twisted'),
         **STATIC_PACKAGE_METADATA))
 

twisted/python/dist.py

@@ -49 +49 @@
                        "news", "pair", "runner", "web",
                        "words"]
 
+# These are the actual package names and versions that will
+# be used by extras_require. This is not passed to setup
+# directly so that combinations of the packages can be created
+# without the need to copy package names multiple times.
+_extra_options = dict(
+    dev=['twistedchecker >= 0.2.0',
+         'pyflakes >= 0.8.1',
+         'twisted-dev-tools >= 0.0.2',
+         'python-subunit',
+         'sphinx >= 1.2.2',
+         'pydoctor >= 0.5'],
+    tls=['pyopenssl >= 0.11',
+         'service_identity'],
+    conch=['gmpy',
+           'pyasn1',
+           'pycrypto'],
+    soap=['soappy'],
+    serial=['pyserial'],
+    osx=['pyobjc'],
+    windows=['pypiwin32']
+)
+
+_platform_independent = (
+    _extra_options['dev'] +
+    _extra_options['tls'] +
+    _extra_options['conch'] +
+    _extra_options['soap'] +
+    _extra_options['serial']
+)
+
+# extras_require is a dictionary of items that can be passed to setup.py
+# to install optional dependencies. For example, to install the optional
+# dev dependencies one would type `pip install -e ".[dev]"`
+# This has been supported by setuptools since 0.5a4
+EXTRAS_REQUIRE = {
+    'dev': _extra_options['dev'],
+    'tls': _extra_options['tls'],
+    'conch': _extra_options['conch'],
+    'soap': _extra_options['soap'],
+    'serial': _extra_options['serial'],
+    'all_non_platform': _platform_independent,
+    'osx_platform': (
+        _extra_options['osx'] + _platform_independent
+    ),
+    'windows_platform': (
+        _extra_options['windows'] + _platform_independent
+    ),
+}
 
 
 class ConditionalExtension(Extension):

twisted/python/test/test_dist.py

@@ -9 +9 @@
 import os
 import sys
 
-from distutils.core import Distribution
+from setuptools.dist import Distribution
 
 from twisted.trial.unittest import TestCase
 
 from twisted.python import dist
 from twisted.python.dist import (get_setup_args, ConditionalExtension,
-    build_scripts_twisted)
+                                 build_scripts_twisted, EXTRAS_REQUIRE)
 from twisted.python.filepath import FilePath
 
 
@@ -58 +58 @@
         self.assertEqual(ext.define_macros, [("whatever", 2), ("WIN32", 1)])
 
 
+class OptionalDependenciesTests(TestCase):
+    """
+    Tests for L{dist.EXTRA_REQUIRES}
+    """
+    def test_distributeTakesExtrasRequire(self):
+        """
+        Test that setuptools' Distribution object can use extra_requires.
+        """
+        extras = dict(im_an_extra_dependency="thing")
+        attrs = dict(extras_require=extras)
+        dist = Distribution(attrs)
+        self.assertEqual(
+            extras,
+            dist.extras_require
+        )
+
+    def test_extrasRequireDictContainsKeys(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{dev} option contains a valid
+        list with correct dependecies.
+        """
+        self.assertIn('dev', EXTRAS_REQUIRE)
+        self.assertIn('tls', EXTRAS_REQUIRE)
+        self.assertIn('conch', EXTRAS_REQUIRE)
+        self.assertIn('soap', EXTRAS_REQUIRE)
+        self.assertIn('serial', EXTRAS_REQUIRE)
+        self.assertIn('all_non_platform', EXTRAS_REQUIRE)
+        self.assertIn('osx_platform', EXTRAS_REQUIRE)
+        self.assertIn('windows_platform', EXTRAS_REQUIRE)
+
+    def test_extrasRequiresDevDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{dev} option contains the correct
+        dependencies.
+        """
+        deps = EXTRAS_REQUIRE['dev']
+        self.assertIn('twistedchecker >= 0.2.0', deps)
+        self.assertIn('pyflakes >= 0.8.1', deps)
+        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
+        self.assertIn('python-subunit', deps)
+        self.assertIn('sphinx >= 1.2.2', deps)
+        self.assertIn('pydoctor >= 0.5', deps)
+
+    def test_extrasRequiresTlsDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{tls} option contains the correct
+        dependencies.
+        """
+        deps = EXTRAS_REQUIRE['tls']
+        self.assertIn('pyopenssl >= 0.11', deps)
+        self.assertIn('service_identity', deps)
+
+    def test_extrasRequiresConchDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{conch} option contains the correct
+        dependencies.
+        """
+        deps = EXTRAS_REQUIRE['conch']
+        self.assertIn('gmpy', deps)
+        self.assertIn('pyasn1', deps)
+        self.assertIn('pycrypto', deps)
+
+    def test_extrasRequiresSoapDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{soap} option contains the correct
+        dependecies.
+        """
+        self.assertIn(
+            'soappy',
+            EXTRAS_REQUIRE['soap']
+        )
+
+    def test_extrasRequiresSerialDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{serial} option contains the correct
+        dependencies.
+        """
+        self.assertIn(
+            'pyserial',
+            EXTRAS_REQUIRE['serial']
+        )
+
+    def test_extrasRequiresAllNonPlatDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{all_non_platform} option contains the
+        correct dependencies.
+        """
+        deps = EXTRAS_REQUIRE['all_non_platform']
+        self.assertIn('twistedchecker >= 0.2.0', deps)
+        self.assertIn('pyflakes >= 0.8.1', deps)
+        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
+        self.assertIn('python-subunit', deps)
+        self.assertIn('sphinx >= 1.2.2', deps)
+        self.assertIn('pydoctor >= 0.5', deps)
+        self.assertIn('pyopenssl >= 0.11', deps)
+        self.assertIn('service_identity', deps)
+        self.assertIn('gmpy', deps)
+        self.assertIn('pyasn1', deps)
+        self.assertIn('pycrypto', deps)
+        self.assertIn('soappy', deps)
+        self.assertIn('pyserial', deps)
+
+    def test_extrasRequiresOsxPlatDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{osx_platform} option contains the correct
+        dependecies.
+        """
+        deps = EXTRAS_REQUIRE['osx_platform']
+        self.assertIn('twistedchecker >= 0.2.0', deps)
+        self.assertIn('pyflakes >= 0.8.1', deps)
+        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
+        self.assertIn('python-subunit', deps)
+        self.assertIn('sphinx >= 1.2.2', deps)
+        self.assertIn('pydoctor >= 0.5', deps)
+        self.assertIn('pyopenssl >= 0.11', deps)
+        self.assertIn('service_identity', deps)
+        self.assertIn('gmpy', deps)
+        self.assertIn('pyasn1', deps)
+        self.assertIn('pycrypto', deps)
+        self.assertIn('soappy', deps)
+        self.assertIn('pyserial', deps)
+        self.assertIn('pyobjc', deps)
+
+    def test_extrasRequiresWindowsPlatDepsAreValid(self):
+        """
+        L{dist.EXTRA_REQUIRES} C{windows_platform} option contains the correct
+        dependecies.
+        """
+        deps = EXTRAS_REQUIRE['windows_platform']
+        self.assertIn('twistedchecker >= 0.2.0', deps)
+        self.assertIn('pyflakes >= 0.8.1', deps)
+        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
+        self.assertIn('python-subunit', deps)
+        self.assertIn('sphinx >= 1.2.2', deps)
+        self.assertIn('pydoctor >= 0.5', deps)
+        self.assertIn('pyopenssl >= 0.11', deps)
+        self.assertIn('service_identity', deps)
+        self.assertIn('gmpy', deps)
+        self.assertIn('pyasn1', deps)
+        self.assertIn('pycrypto', deps)
+        self.assertIn('soappy', deps)
+        self.assertIn('pyserial', deps)
+        self.assertIn('pypiwin32', deps)
+
 
 class GetExtensionsTest(TestCase):
     """

new file twisted/topfiles/3696.misc

@@ +1 @@
+Optional dependencies can be installed using the extra_requires facility provided by setuptools.
+ No newline at end of file