Ticket #3696: extras_require-3696-10.diff

File extras_require-3696-10.diff, 14.2 KB (added by Chris Wolfe, 5 years ago)

doc fixes, rename plat to platform

  • docs/index.rst

    diff --git docs/index.rst docs/index.rst
    index 1172a49..a4eaf5f 100644
    Contents: 
    77    :maxdepth: 2
    88    :includehidden:
    99
     10    installation/index
    1011    core/index
    1112    conch/index
    1213    lore/index
  • new file docs/installation/howto/optional.rst

    diff --git docs/installation/howto/optional.rst docs/installation/howto/optional.rst
    new file mode 100644
    index 0000000..227bf01
    - +  
     1
     2:LastChangedDate: $LastChangedDate$
     3:LastChangedRevision: $LastChangedRevision$
     4:LastChangedBy: $LastChangedBy$
     5
     6Installing Optional Dependencies
     7================================
     8
     9This document describes how to install optional dependencies that enhance Twisted.
     10These dependencies are python packages that Twisted's developers have found useful either for developing Twisted itself or for developing Twisted applications.
     11
     12The intended audience of this document is someone who is going to use `pip`_ to manage a Twisted installation.
     13
     14
     15What are optional dependencies?
     16----------------------------------
     17
     18Optional dependencies are python packages that are not strictly necessary for Twisted to function but provide some functionality that would otherwise be unavailable.
     19
     20
     21Why use optional dependencies?
     22------------------------------
     23
     24The optional dependencies that Twisted recommends are used regularly by Twisted developers.
     25While 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.
     26
     27
     28Which options are supported?
     29----------------------------
     30
     31* **dev** - packages that aid in the development of Twisted itself.
     32    * `TwistedChecker`_
     33    * `pyflakes`_
     34    * `twisted-dev-tools`_
     35    * `python-subunit`_
     36    * `Sphinx`_
     37    * `pydoctor`_
     38
     39* **tls** - packages that are needed to work with TLS.
     40    * `pyOpenSSL`_
     41    * `service_identity`_
     42
     43* **conch** - packages for working with conch/SSH.
     44    * `gmpy`_
     45    * `pyasn1`_
     46    * `pycrypto`_
     47
     48* **soap** - the `SOAPpy`_ package to work with SOAP.
     49
     50* **serial** - the `pyserial`_ package to work with serial data.
     51
     52* **all_non_platform** - installs **dev**, **tls**, **conch**, **soap**, and **serial** options.
     53
     54* **osx_platform** - **all_non_platform** options and `pyobjc`_ to work with Objective-C apis.
     55
     56* **windows_platform** - **all_non_platform** options and `pypiwin32`_ to work with Windows's apis.
     57
     58
     59How do I install an optional dependency?
     60----------------------------------------
     61
     62To install optional dependencies one needs to use a slightly different syntax with `pip`_ than normal.
     63The following code snippet shows how to tell `pip`_ to install a package and an optional dependency.
     64In this example, ``option_name_to_install`` is the optional dependency.
     65
     66.. code-block:: shell
     67
     68                $ pip install "twisted[option_name_to_install]"
     69
     70For a real world example, the following command will install Twisted with the **dev** option.
     71
     72.. code-block:: shell
     73
     74                $ pip install "twisted[dev]"
     75
     76To install multiple options at the same time, one need only provide `pip`_ a comma seperated list of options.
     77For example, to install the **dev** and **tls** options, call `pip`_ like so:
     78
     79.. code-block:: shell
     80
     81                $ pip install "twisted[dev, tls]"
     82
     83Lastly, if you are developing Twisted and want to install your development source and an optional depency, use `pip`_ to create an `editable install`_:
     84
     85.. code-block:: shell
     86
     87                $ cd /into/directory/containing/Twisted/setup.py
     88                $ pip install -e ".[option_to_install]
     89
     90
     91Conclusion
     92----------
     93
     94In this document you've been shown:
     95
     96#. What optional dependences are.
     97#. Which optional dependencies are supported.
     98#. How to install optional dependencies using `pip`_.
     99
     100
     101.. _pip: https://pip.pypa.io/en/latest/quickstart.html
     102.. _TwistedChecker: https://pypi.python.org/pypi/TwistedChecker
     103.. _pyflakes: https://pypi.python.org/pypi/pyflakes
     104.. _twisted-dev-tools: https://pypi.python.org/pypi/twisted-dev-tools
     105.. _python-subunit: https://pypi.python.org/pypi/python-subunit
     106.. _Sphinx: https://pypi.python.org/pypi/Sphinx/1.3b1
     107.. _pydoctor: https://pypi.python.org/pypi/pydoctor
     108.. _pyOpenSSL: https://pypi.python.org/pypi/pyOpenSSL
     109.. _service_identity: https://pypi.python.org/pypi/service_identity
     110.. _gmpy: https://pypi.python.org/pypi/gmpy/1.17
     111.. _pyasn1: https://pypi.python.org/pypi/pyasn1
     112.. _pycrypto: https://pypi.python.org/pypi/pycrypto
     113.. _SOAPpy: https://pypi.python.org/pypi/SOAPpy
     114.. _pyserial: https://pypi.python.org/pypi/pyserial
     115.. _pyobjc: https://pypi.python.org/pypi/pyobjc
     116.. _pypiwin32: https://pypi.python.org/pypi/pypiwin32
     117.. _`editable install`: https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs
     118.. _`extras_require`: https://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
  • new file docs/installation/index.rst

    diff --git docs/installation/index.rst docs/installation/index.rst
    new file mode 100644
    index 0000000..d3e0360
    - +  
     1
     2:LastChangedDate: $LastChangedDate$
     3:LastChangedRevision: $LastChangedRevision$
     4:LastChangedBy: $LastChangedBy$
     5
     6Installing Twisted
     7==================
     8
     9.. toctree::
     10   :hidden:
     11
     12   howto/optional
     13
     14- :doc:`Installing Optional Dependencies <howto/optional>`: documentation
     15  on how to install Twisted's optional dependencies.
  • setup.py

    diff --git setup.py setup.py
    index 26f052b..e63f1b5 100755
    dependency resolution is disabled. 
    5454
    5555    from twisted.python.dist import (
    5656        STATIC_PACKAGE_METADATA, getDataFiles, getExtensions, getAllScripts,
    57         getPackages, setup)
     57        getPackages, setup, EXTRAS_REQUIRE)
    5858
    5959    scripts = getAllScripts()
    6060
    dependency resolution is disabled. 
    6262        packages=getPackages('twisted'),
    6363        conditionalExtensions=getExtensions(),
    6464        scripts=scripts,
     65        extras_require=EXTRAS_REQUIRE,
    6566        data_files=getDataFiles('twisted'),
    6667        **STATIC_PACKAGE_METADATA))
    6768
  • twisted/python/dist.py

    diff --git twisted/python/dist.py twisted/python/dist.py
    index 63b36b3..035d203 100644
    twisted_subprojects = ["conch", "lore", "mail", "names", 
    4949                       "news", "pair", "runner", "web",
    5050                       "words"]
    5151
     52# These are the actual package names and versions that will
     53# be used by extras_require. This is not passed to setup
     54# directly so that combinations of the packages can be created
     55# without the need to copy package names multiple times.
     56_extra_options = dict(
     57    dev=['twistedchecker >= 0.2.0',
     58         'pyflakes >= 0.8.1',
     59         'twisted-dev-tools >= 0.0.2',
     60         'python-subunit',
     61         'sphinx >= 1.2.2',
     62         'pydoctor >= 0.5'],
     63    tls=['pyopenssl >= 0.11',
     64         'service_identity'],
     65    conch=['gmpy',
     66           'pyasn1',
     67           'pycrypto'],
     68    soap=['soappy'],
     69    serial=['pyserial'],
     70    osx=['pyobjc'],
     71    windows=['pypiwin32']
     72)
     73
     74_platform_independent = (
     75    _extra_options['dev'] +
     76    _extra_options['tls'] +
     77    _extra_options['conch'] +
     78    _extra_options['soap'] +
     79    _extra_options['serial']
     80)
     81
     82# extras_require is a dictionary of items that can be passed to setup.py
     83# to install optional dependencies. For example, to install the optional
     84# dev dependencies one would type `pip install -e ".[dev]"`
     85# This has been supported by setuptools since 0.5a4
     86EXTRAS_REQUIRE = {
     87    'dev': _extra_options['dev'],
     88    'tls': _extra_options['tls'],
     89    'conch': _extra_options['conch'],
     90    'soap': _extra_options['soap'],
     91    'serial': _extra_options['serial'],
     92    'all_non_platform': _platform_independent,
     93    'osx_platform': (
     94        _extra_options['osx'] + _platform_independent
     95    ),
     96    'windows_platform': (
     97        _extra_options['windows'] + _platform_independent
     98    ),
     99}
    52100
    53101
    54102class ConditionalExtension(Extension):
  • twisted/python/test/test_dist.py

    diff --git twisted/python/test/test_dist.py twisted/python/test/test_dist.py
    index d2288ee..72b22d8 100644
    Tests for parts of our release automation system. 
    99import os
    1010import sys
    1111
    12 from distutils.core import Distribution
     12from setuptools.dist import Distribution
    1313
    1414from twisted.trial.unittest import TestCase
    1515
    1616from twisted.python import dist
    1717from twisted.python.dist import (get_setup_args, ConditionalExtension,
    18     build_scripts_twisted)
     18                                 build_scripts_twisted, EXTRAS_REQUIRE)
    1919from twisted.python.filepath import FilePath
    2020
    2121
    class SetupTest(TestCase): 
    5858        self.assertEqual(ext.define_macros, [("whatever", 2), ("WIN32", 1)])
    5959
    6060
     61class OptionalDependenciesTests(TestCase):
     62    """
     63    Tests for L{dist.EXTRA_REQUIRES}
     64    """
     65    def test_distributeTakesExtrasRequire(self):
     66        """
     67        Test that setuptools' Distribution object can use extra_requires.
     68        """
     69        extras = dict(im_an_extra_dependency="thing")
     70        attrs = dict(extras_require=extras)
     71        dist = Distribution(attrs)
     72        self.assertEqual(
     73            extras,
     74            dist.extras_require
     75        )
     76
     77    def test_extrasRequireDictContainsKeys(self):
     78        """
     79        L{dist.EXTRA_REQUIRES} C{dev} option contains a valid
     80        list with correct dependecies.
     81        """
     82        self.assertIn('dev', EXTRAS_REQUIRE)
     83        self.assertIn('tls', EXTRAS_REQUIRE)
     84        self.assertIn('conch', EXTRAS_REQUIRE)
     85        self.assertIn('soap', EXTRAS_REQUIRE)
     86        self.assertIn('serial', EXTRAS_REQUIRE)
     87        self.assertIn('all_non_platform', EXTRAS_REQUIRE)
     88        self.assertIn('osx_platform', EXTRAS_REQUIRE)
     89        self.assertIn('windows_platform', EXTRAS_REQUIRE)
     90
     91    def test_extrasRequiresDevDepsAreValid(self):
     92        """
     93        L{dist.EXTRA_REQUIRES} C{dev} option contains the correct
     94        dependencies.
     95        """
     96        deps = EXTRAS_REQUIRE['dev']
     97        self.assertIn('twistedchecker >= 0.2.0', deps)
     98        self.assertIn('pyflakes >= 0.8.1', deps)
     99        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
     100        self.assertIn('python-subunit', deps)
     101        self.assertIn('sphinx >= 1.2.2', deps)
     102        self.assertIn('pydoctor >= 0.5', deps)
     103
     104    def test_extrasRequiresTlsDepsAreValid(self):
     105        """
     106        L{dist.EXTRA_REQUIRES} C{tls} option contains the correct
     107        dependencies.
     108        """
     109        deps = EXTRAS_REQUIRE['tls']
     110        self.assertIn('pyopenssl >= 0.11', deps)
     111        self.assertIn('service_identity', deps)
     112
     113    def test_extrasRequiresConchDepsAreValid(self):
     114        """
     115        L{dist.EXTRA_REQUIRES} C{conch} option contains the correct
     116        dependencies.
     117        """
     118        deps = EXTRAS_REQUIRE['conch']
     119        self.assertIn('gmpy', deps)
     120        self.assertIn('pyasn1', deps)
     121        self.assertIn('pycrypto', deps)
     122
     123    def test_extrasRequiresSoapDepsAreValid(self):
     124        """
     125        L{dist.EXTRA_REQUIRES} C{soap} option contains the correct
     126        dependecies.
     127        """
     128        self.assertIn(
     129            'soappy',
     130            EXTRAS_REQUIRE['soap']
     131        )
     132
     133    def test_extrasRequiresSerialDepsAreValid(self):
     134        """
     135        L{dist.EXTRA_REQUIRES} C{serial} option contains the correct
     136        dependencies.
     137        """
     138        self.assertIn(
     139            'pyserial',
     140            EXTRAS_REQUIRE['serial']
     141        )
     142
     143    def test_extrasRequiresAllNonPlatDepsAreValid(self):
     144        """
     145        L{dist.EXTRA_REQUIRES} C{all_non_platform} option contains the
     146        correct dependencies.
     147        """
     148        deps = EXTRAS_REQUIRE['all_non_platform']
     149        self.assertIn('twistedchecker >= 0.2.0', deps)
     150        self.assertIn('pyflakes >= 0.8.1', deps)
     151        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
     152        self.assertIn('python-subunit', deps)
     153        self.assertIn('sphinx >= 1.2.2', deps)
     154        self.assertIn('pydoctor >= 0.5', deps)
     155        self.assertIn('pyopenssl >= 0.11', deps)
     156        self.assertIn('service_identity', deps)
     157        self.assertIn('gmpy', deps)
     158        self.assertIn('pyasn1', deps)
     159        self.assertIn('pycrypto', deps)
     160        self.assertIn('soappy', deps)
     161        self.assertIn('pyserial', deps)
     162
     163    def test_extrasRequiresOsxPlatDepsAreValid(self):
     164        """
     165        L{dist.EXTRA_REQUIRES} C{osx_platform} option contains the correct
     166        dependecies.
     167        """
     168        deps = EXTRAS_REQUIRE['osx_platform']
     169        self.assertIn('twistedchecker >= 0.2.0', deps)
     170        self.assertIn('pyflakes >= 0.8.1', deps)
     171        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
     172        self.assertIn('python-subunit', deps)
     173        self.assertIn('sphinx >= 1.2.2', deps)
     174        self.assertIn('pydoctor >= 0.5', deps)
     175        self.assertIn('pyopenssl >= 0.11', deps)
     176        self.assertIn('service_identity', deps)
     177        self.assertIn('gmpy', deps)
     178        self.assertIn('pyasn1', deps)
     179        self.assertIn('pycrypto', deps)
     180        self.assertIn('soappy', deps)
     181        self.assertIn('pyserial', deps)
     182        self.assertIn('pyobjc', deps)
     183
     184    def test_extrasRequiresWindowsPlatDepsAreValid(self):
     185        """
     186        L{dist.EXTRA_REQUIRES} C{windows_platform} option contains the correct
     187        dependecies.
     188        """
     189        deps = EXTRAS_REQUIRE['windows_platform']
     190        self.assertIn('twistedchecker >= 0.2.0', deps)
     191        self.assertIn('pyflakes >= 0.8.1', deps)
     192        self.assertIn('twisted-dev-tools >= 0.0.2', deps)
     193        self.assertIn('python-subunit', deps)
     194        self.assertIn('sphinx >= 1.2.2', deps)
     195        self.assertIn('pydoctor >= 0.5', deps)
     196        self.assertIn('pyopenssl >= 0.11', deps)
     197        self.assertIn('service_identity', deps)
     198        self.assertIn('gmpy', deps)
     199        self.assertIn('pyasn1', deps)
     200        self.assertIn('pycrypto', deps)
     201        self.assertIn('soappy', deps)
     202        self.assertIn('pyserial', deps)
     203        self.assertIn('pypiwin32', deps)
     204
    61205
    62206class GetExtensionsTest(TestCase):
    63207    """
  • new file twisted/topfiles/3696.misc

    diff --git twisted/topfiles/3696.misc twisted/topfiles/3696.misc
    new file mode 100644
    index 0000000..24d3d09
    - +  
     1Optional dependencies can be installed using the extra_requires facility provided by setuptools.
     2 No newline at end of file