Ticket #3696: extras_require-3696-9.diff

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

patch with docs, pypiwin32, more tests

  • 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..5805286
    - +  
     1
     2:LastChangedDate: $LastChangedDate$
     3:LastChangedRevision: $LastChangedRevision$
     4:LastChangedBy: $LastChangedBy$
     5
     6
     7
     8
     9
     10Installing Optional Dependencies
     11================================
     12
     13
     14
     15
     16This document describes how to install optional dependencies that Twisted's developers find helpful.
     17The target audience of this document is someone who is both familiar with pip and would like to install Twisted and several of its optional dependencies.
     18
     19
     20
     21Twisted takes advantage of setuptools' `extra_requires` functionality to simplify the process of installing optional dependencies.
     22In the list below, the `italicized`  word is the `extra option` that is passed to `pip` to install an optional set of dependencies.
     23
     24
     25
     26
     27.. _dev :
     28
     29- `dev` - packages to aid in the development of Twisted (linters, documentation builder, etc.).
     30    - `twistedchecker`_
     31    - `pyflakes`_
     32    - `twisted-dev-tools`_
     33    - `python-subunit`_
     34    - `sphinx`_
     35    - `pydoctor`_
     36
     37
     38
     39
     40.. _tls :
     41
     42- `tls` - packages that are needed to work with `TLS` from twisted.
     43    - `pyopenssl`_
     44    - `service_identity`_
     45
     46
     47
     48
     49
     50.. _conch :
     51
     52- `conch` - packages for working with conch/ssh.
     53    - `gmpy`_
     54    - `pyasn1`_
     55    - `pycrypto`_
     56
     57
     58
     59
     60
     61.. _soap :
     62
     63- `soap` - installs the `soappy`_ package to work with SOAP.
     64
     65
     66
     67
     68
     69.. _serial :
     70
     71- `serial` - installs the `pyserial`_ package to work with serial data.
     72
     73
     74
     75
     76
     77.. _all_non_plat :
     78
     79- `all_non_plat` - install all of the optional dependencies included in the the following options: :ref:`dev`, :ref:`tls`, :ref:`conch`, :ref:`soap`, and :ref:`serial` options.
     80
     81
     82
     83
     84
     85The following install all of the optional dependencies listed above with the addition of a platform specific library.
     86
     87
     88
     89
     90
     91.. _osx_plat :
     92
     93- `osx_plat` installs `pyobjc`_ to work with Objective-C apis.
     94
     95
     96
     97
     98
     99.. _windows_plat :
     100
     101- `windows_plat` installs `pypiwin32`_ to work with Windows' apis.
     102
     103
     104
     105
     106
     107Installing Twisted with all of the :ref:`dev` options would be done using the following:
     108
     109
     110
     111
     112
     113.. code-block:: shell
     114
     115                $ pip install "twisted[dev]"
     116
     117
     118
     119
     120
     121To install multiple options at the same time, you need only provide `pip` a comma seperated list of options that you would like to install.
     122For example, to install the :ref:`dev` and :ref:`tls` extra packages at the same time, you'd call `pip` like so:
     123
     124
     125
     126
     127
     128.. code-block:: shell
     129
     130                $ pip install "twisted[dev, tls]"
     131
     132
     133
     134
     135
     136.. _pip: https://pip.pypa.io/en/latest/quickstart.html
     137.. _twistedchecker: https://pypi.python.org/pypi/TwistedChecker
     138.. _pyflakes: https://pypi.python.org/pypi/pyflakes
     139.. _twisted-dev-tools: https://pypi.python.org/pypi/twisted-dev-tools
     140.. _python-subunit: https://pypi.python.org/pypi/python-subunit
     141.. _sphinx: https://pypi.python.org/pypi/Sphinx/1.3b1
     142.. _pydoctor: https://pypi.python.org/pypi/pydoctor
     143.. _pyopenssl: https://pypi.python.org/pypi/pyOpenSSL
     144.. _service_identity: https://pypi.python.org/pypi/service_identity
     145.. _gmpy: https://pypi.python.org/pypi/gmpy/1.17
     146.. _pyasn1: https://pypi.python.org/pypi/pyasn1
     147.. _pycrypto: https://pypi.python.org/pypi/pycrypto
     148.. _soappy: https://pypi.python.org/pypi/SOAPpy
     149.. _pyserial: https://pypi.python.org/pypi/pyserial
     150.. _pyobjc: https://pypi.python.org/pypi/pyobjc
     151.. _pypiwin32: https://pypi.python.org/pypi/pypiwin32
  • new file docs/installation/index.rst

    diff --git docs/installation/index.rst docs/installation/index.rst
    new file mode 100644
    index 0000000..7f44260
    - +  
     1
     2:LastChangedDate: $LastChangedDate$
     3:LastChangedRevision: $LastChangedRevision$
     4:LastChangedBy: $LastChangedBy$
     5
     6Installing Twisted
     7==================
     8
     9
     10.. toctree::
     11   :hidden:
     12
     13
     14
     15
     16   howto/optional
     17
     18
     19
     20
     21- :doc:`Installing Optional Dependencies <howto/optional>`: documentation
     22  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..ef7bab9 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_plat': _platform_independent,
     93    'osx_plat': (
     94        _extra_options['osx'] + _platform_independent
     95    ),
     96    'windows_plat':(
     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..a3ca4d2 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_plat', EXTRAS_REQUIRE)
     88        self.assertIn('osx_plat', EXTRAS_REQUIRE)
     89        self.assertIn('windows_plat', 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_plat} option contains the
     146        correct dependencies.
     147        """
     148        deps = EXTRAS_REQUIRE['all_non_plat']
     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_plat} option contains the correct
     166        dependecies.
     167        """
     168        deps = EXTRAS_REQUIRE['osx_plat']
     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_plat} option contains the correct
     187        dependecies.
     188        """
     189        deps = EXTRAS_REQUIRE['windows_plat']
     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