Merge pull request #443 from astrofrog/setup-wrapper

Create setup() wrapper that does all the standard astropy-helpers actions

CHANGES.rst

@@ -12,6 +12,10 @@ astropy-helpers Changelog
 
 - Simplified setup.py and moved most of the configuration to setup.cfg. [#445]
 
+- Add a new ``astropy_helpers.setup_helpers.setup`` function that does all
+  the default boilerplate in typical ``setup.py`` files that use
+  astropy-helpers. [#443]
+
 - Updated minimum required version of setuptools to 30.3.0. [#440]
 
 - Remove functionality to adjust compilers if a broken compiler is detected.

astropy_helpers/setup_helpers.py

@@ -14,19 +14,22 @@
 import traceback
 import warnings
 from configparser import ConfigParser
+import builtins
 
 from distutils import log
 from distutils.errors import DistutilsOptionError, DistutilsModuleError
 from distutils.core import Extension
 from distutils.core import Command
 from distutils.command.sdist import sdist as DistutilsSdist
 
+from setuptools import setup as setuptools_setup
+from setuptools.config import read_configuration
 from setuptools import find_packages as _find_packages
 
 from .distutils_helpers import (add_command_option, get_compiler_option,
                                 get_dummy_distribution, get_distutils_build_option,
                                 get_distutils_build_or_install_option)
-from .version_helpers import get_pkg_version_module
+from .version_helpers import get_pkg_version_module, generate_version_py
 from .utils import (walk_skip_hidden, import_file, extends_doc,
                     resolve_name, AstropyDeprecationWarning)
 
@@ -67,6 +70,41 @@
     pass
 
 
+def setup(**kwargs):
+    """
+    A wrapper around setuptools' setup() function that automatically sets up
+    custom commands, generates a version file, and customizes the setup process
+    via the ``setup_package.py`` files.
+    """
+
+    # DEPRECATED: store the package name in a built-in variable so it's easy
+    # to get from other parts of the setup infrastructure. We should phase this
+    # out in packages that use it - the cookiecutter template should now be
+    # able to put the right package name where needed.
+    conf = read_configuration('setup.cfg')
+    builtins._ASTROPY_PACKAGE_NAME_ = conf['metadata']['name']
+
+    # Create a dictionary with setup command overrides. Note that this gets
+    # information about the package (name and version) from the setup.cfg file.
+    cmdclass = register_commands()
+
+    # Freeze build information in version.py. Note that this gets information
+    # about the package (name and version) from the setup.cfg file.
+    version = generate_version_py()
+
+    # Get configuration information from all of the various subpackages.
+    # See the docstring for setup_helpers.update_package_files for more
+    # details.
+    package_info = get_package_info()
+    package_info['cmdclass'] = cmdclass
+    package_info['version'] = version
+
+    # Override using any specified keyword arguments
+    package_info.update(kwargs)
+
+    setuptools_setup(**package_info)
+
+
 def adjust_compiler(package):
     warnings.warn(
         'The adjust_compiler function in setup.py is '

astropy_helpers/tests/test_git_helpers.py

@@ -50,15 +50,10 @@
 #!/usr/bin/env python
 
 import sys
-from setuptools import setup
-
 sys.path.insert(0, r'{astropy_helpers_path}')
 
-from astropy_helpers.version_helpers import generate_version_py
-
-version = generate_version_py()
-
-setup(version=version, packages=['apyhtest_eva'])
+from astropy_helpers.setup_helpers import setup
+setup()
 """
 
 

astropy_helpers/tests/test_setup_helpers.py

@@ -300,20 +300,15 @@ class B(A):
     # arugments, instead getting the information from setup.cfg.
     test_pkg.join('setup.cfg').write(dedent("""
         [metadata]
-        name = 'mypackage'
+        name = mypackage
         version = 0.1
     """))
 
     test_pkg.join('setup.py').write(dedent("""\
         import sys
         sys.path.insert(0, r'{astropy_helpers_path}')
-        from setuptools import setup
-        from astropy_helpers.setup_helpers import register_commands, get_package_info
-
-        cmdclassd = register_commands()
-
-        setup(cmdclass=cmdclassd, **get_package_info()
-        )
+        from astropy_helpers.setup_helpers import setup
+        setup()
     """.format(astropy_helpers_path=ASTROPY_HELPERS_PATH)))
 
     with test_pkg.as_cwd():

docs/basic.rst

@@ -17,8 +17,10 @@ will be available::
     python setup.py build_docs
 
 and this command is implemented in astropy-helpers. To use the custom commands
-described here, you can use the
-:func:`~astropy_helpers.setup_helpers.register_commands` function by adding::
+described here, you can either use the simplified method of opting in to
+astropy-helpers described in :ref:`setup_all`, or if you want more control, use
+the :func:`~astropy_helpers.setup_helpers.register_commands` function by
+adding::
 
     from astropy_helpers.setup_helpers import register_commands
 
@@ -126,7 +128,9 @@ share the same version number).
 In addition, this module contains variables such as ``major``, ``minor``, and
 ``bugfix``, as well as ``version_info`` (a tuple of the previous three values),
 a ``release`` flag that indicates whether we are using a stable release, and
-several other complementary variables. To use the
+several other complementary variables.  To use the version helpers, you can
+either use the simplified method of opting in to astropy-helpers described in
+:ref:`setup_all`, or if you want more control, use the
 :func:`~astropy_helpers.version_helpers.generate_version_py`, import::
 
     from astropy_helpers.version_helpers import generate_version_py
@@ -222,7 +226,9 @@ these files can include one or more of the following functions:
     This function can returns a dict formatted as required by
     the ``entry_points`` argument to ``setup()``.
 
-With these files in place, you can then make use of the
+With these files in place, you can either use the simplified method of opting in
+to astropy-helpers described in :ref:`setup_all`, or if you want more control,
+use theyou can then make use of the
 :func:`~astropy_helpers.setup_helpers.get_package_info`  function in your
 ``setup.py`` file with::
 
@@ -235,3 +241,35 @@ With these files in place, you can then make use of the
     ...
 
     setup(..., **package_info)
+
+
+.. _setup_all:
+
+Opting in to all basic functionality
+------------------------------------
+
+If you are happy to opt in to all the functionality described on this page, you
+can make use of the :func:`~astropy_helpers.setup_helpers.setup` function from
+:mod:`astropy_helpers.setup_helpers` which wraps the function of the same name
+from setuptools and automatically runs
+:func:`~astropy_helpers.setup_helpers.register_commands`,
+:func:`~astropy_helpers.version_helpers.generate_version_py`, and
+:func:`~astropy_helpers.setup_helpers.get_package_info`. If you want to do this,
+make sure the package name and version number are defined in ``setup.cfg``::
+
+    [metadata]
+    name = mypackage
+    version = 0.4.dev
+
+then use the :func:`~astropy_helpers.setup_helpers.setup` function from
+astropy-helpers in your ``setup.py`` file as follows::
+
+    import ah_bootstrap
+    from astropy_helpers.setup_helpers import setup
+    setup()
+
+We recommend that you also include a comment along the following lines in your
+``setup.py`` file::
+
+    # The configuration for the package, including the name, version, and other
+    # information are set in the setup.cfg file.