From ca9f8075a766bf41b9aa707ecf80e6af4b2ca284 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 18:48:59 +0000 Subject: [PATCH 01/44] Start refactoring package template to follow APE 17 --- hooks/post_gen_project.py | 23 +---- {{ cookiecutter.package_name }}/MANIFEST.in | 26 +---- .../pyproject.toml | 14 +++ {{ cookiecutter.package_name }}/setup.cfg | 61 ++++-------- {{ cookiecutter.package_name }}/setup.py | 96 +++++++++++++++---- {{ cookiecutter.package_name }}/tox.ini | 78 +++++++++++++++ ...{{ cookiecutter._parent_project }}_init.py | 4 - 7 files changed, 190 insertions(+), 112 deletions(-) create mode 100644 {{ cookiecutter.package_name }}/pyproject.toml create mode 100644 {{ cookiecutter.package_name }}/tox.ini diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index f52adecc..f25caf1d 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -68,26 +68,5 @@ def process_licence(licence_name): "Creation of {{ cookiecutter.package_name }} from astropy package template" ) - if '{{ cookiecutter.astropy_helpers_version }}': - Repo.create_submodule( - new_repo, "astropy_helpers", "astropy_helpers", - "https://github.com/astropy/astropy-helpers.git", - "{{ cookiecutter.astropy_helpers_version }}") - new_repo.submodules[0].update() - copy_file('astropy_helpers/ah_bootstrap.py', 'ah_bootstrap.py') - new_repo.git.add('ah_bootstrap.py') - new_repo.index.commit( - "Initialize astropy_helpers at version {{ cookiecutter.astropy_helpers_version }}" - ) - except ImportError: - print( - "gitpython is not installed so the repository will not be initialised " - "and astropy_helpers not downloaded.") - - else: - urllib.request.urlretrieve( - url=('https://raw.githubusercontent.com/astropy/astropy-helpers/' - '{{ cookiecutter.astropy_helpers_version }}/ah_bootstrap.py'), - filename='ah_bootstrap.py') - urllib.request.urlcleanup() + print("gitpython is not installed so the repository will not be initialised.") diff --git a/{{ cookiecutter.package_name }}/MANIFEST.in b/{{ cookiecutter.package_name }}/MANIFEST.in index 71c0fc34..446d6b4b 100644 --- a/{{ cookiecutter.package_name }}/MANIFEST.in +++ b/{{ cookiecutter.package_name }}/MANIFEST.in @@ -1,9 +1,8 @@ include README.rst include CHANGES.rst - -include ah_bootstrap.py include setup.cfg -include {{ cookiecutter.module_name }}/tests/coveragerc +include LICENSE.rst +include pyproject.toml recursive-include {{ cookiecutter.module_name }} *.pyx *.c *.pxd recursive-include docs * @@ -15,25 +14,4 @@ prune build prune docs/_build prune docs/api - -# the next few stanzas are for astropy_helpers. It's derived from the -# astropy_helpers/MANIFEST.in, but requires additional includes for the actual -# package directory and egg-info. - -include astropy_helpers/README.rst -include astropy_helpers/CHANGES.rst -include astropy_helpers/LICENSE.rst -recursive-include astropy_helpers/licenses * - -include astropy_helpers/ah_bootstrap.py - -recursive-include astropy_helpers/astropy_helpers *.py *.pyx *.c *.h *.rst -recursive-include astropy_helpers/astropy_helpers.egg-info * -# include the sphinx stuff with "*" because there are css/html/rst/etc. -recursive-include astropy_helpers/astropy_helpers/sphinx * - -prune astropy_helpers/build -prune astropy_helpers/astropy_helpers/tests - - global-exclude *.pyc *.o diff --git a/{{ cookiecutter.package_name }}/pyproject.toml b/{{ cookiecutter.package_name }}/pyproject.toml new file mode 100644 index 00000000..b27affd7 --- /dev/null +++ b/{{ cookiecutter.package_name }}/pyproject.toml @@ -0,0 +1,14 @@ +[build-system] +{% if cookiecutter.include_example_code == 'y' %} +requires = ["setuptools", + "setuptools_scm", + "wheel", + "extension-helpers", + "oldest-supported-numpy", + "cython==0.29.14"] +{% elif %} +requires = ["setuptools", + "setuptools_scm", + "wheel"] +{% endif %} +build-backend = 'setuptools.build_meta' diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index 059596dd..f2e86d60 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -1,62 +1,41 @@ [metadata] name = {{ cookiecutter.module_name }} -# version should be PEP440 compatible (https://www.python.org/dev/peps/pep-0440/) -version = {{ cookiecutter.project_version }} author = {{ cookiecutter.author_name }} author_email = {{ cookiecutter.author_email }} -description = {{ cookiecutter.short_description }} -long_description = {{ cookiecutter.long_description }} license = {{ cookiecutter.license }} +license_file = LICENSE.rst url = {{ cookiecutter.project_url }} +description = {{ cookiecutter.short_description }} +long_description = file: README.rst edit_on_github = {{ cookiecutter.edit_on_github_extension }} github_project = {{ cookiecutter.github_project }} -python_requires = ">={{ cookiecutter.minimum_python_version }}" [options] -# install_requires should be formatted as a semicolon-separated list, e.g.: -# install_requires = astropy; scipy; matplotlib -install_requires = {{ cookiecutter._install_requires }} zip_safe = False -use_2to3 = False +packages = find: +python_requires = ">={{ cookiecutter.minimum_python_version }}" +setup_requires = setuptools_scm +install_requires = {{ cookiecutter._install_requires }} +{% if cookiecutter.include_example_code == 'y' %} [options.entry_points] console_scripts = - {% if cookiecutter.include_example_code == 'y' %} astropy-package-template-example = packagename.example_mod:main - {% else %} - # astropy-package-template-example = packagename.example_mod:main - {% endif %} +{% endif %} + +[options.extras_require] +all = +test = + pytest-astropy +docs = + sphinx-astropy [options.package_data] -* = *.c {{ cookiecutter.module_name }} = data/* -{{ cookiecutter.module_name }}.tests = coveragerc - -[build_sphinx] -source-dir = docs -build-dir = docs/_build -all_files = 1 - -[build_docs] -source-dir = docs -build-dir = docs/_build -all_files = 1 - -[upload_docs] -upload-dir = docs/_build/html -show-response = 1 [tool:pytest] -minversion = 3.0 -norecursedirs = build docs/_build +testpaths = "{{ cookiecutter.module_name }}" "docs" +astropy_header = true doctest_plus = enabled -addopts = -p no:warnings - -[ah_bootstrap] -auto_use = True - -[flake8] -exclude = extern,sphinx,*parsetab.py,astropy_helpers,ah_bootstrap.py,conftest.py,docs/conf.py,setup.py - -[pycodestyle] -exclude = extern,sphinx,*parsetab.py,astropy_helpers,ah_bootstrap.py,conftest.py,docs/conf.py,setup.py +text_file_format = rst +addopts = --doctest-rst diff --git a/{{ cookiecutter.package_name }}/setup.py b/{{ cookiecutter.package_name }}/setup.py index c7715256..42e0042b 100755 --- a/{{ cookiecutter.package_name }}/setup.py +++ b/{{ cookiecutter.package_name }}/setup.py @@ -1,33 +1,87 @@ #!/usr/bin/env python - # Licensed under a 3-clause BSD style license - see LICENSE.rst -import builtins +# NOTE: The configuration for the package, including the name, version, and +# other information are set in the setup.cfg file. -# Ensure that astropy-helpers is available -import ah_bootstrap # noqa +import os +import sys -from setuptools import setup +from setuptools import setup, from setuptools.config import read_configuration +{% if cookiecutter.include_example_code == 'y' %} +from extension_helpers import get_extensions +{% endif %} + +# First provide helpful messages if contributors try and run legacy commands +# for tests or docs. + +TEST_HELP = """ +Note: running tests is no longer done using 'python setup.py test'. Instead +you will need to run: + + tox -e test + +If you don't already have tox installed, you can install it with: + + pip install tox + +If you only want to run part of the test suite, you can also use pytest +directly with:: + + pip install -e .[test] + pytest + +For more information, see: + + http://docs.astropy.org/en/latest/development/testguide.html#running-tests +""" + +if 'test' in sys.argv: + print(TEST_HELP) + sys.exit(1) + +DOCS_HELP = """ +Note: building the documentation is no longer done using +'python setup.py build_docs'. Instead you will need to run: + + tox -e build_docs + +If you don't already have tox installed, you can install it with: + + pip install tox + +You can also build the documentation with Sphinx directly using:: -from astropy_helpers.setup_helpers import register_commands, get_package_info -from astropy_helpers.version_helpers import generate_version_py + pip install -e .[docs] + cd docs + make html -# Store the package name in a built-in variable so it's easy -# to get from other parts of the setup infrastructure -builtins._ASTROPY_PACKAGE_NAME_ = read_configuration('setup.cfg')['metadata']['name'] +For more information, see: -# 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() + http://docs.astropy.org/en/latest/install.html#builddocs +""" -# 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() +if 'build_docs' in sys.argv or 'build_sphinx' in sys.argv: + print(DOCS_HELP) + sys.exit(1) -# 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() +VERSION_TEMPLATE = """ +# Note that we need to fall back to the hard-coded version if either +# setuptools_scm can't be imported or setuptools_scm can't determine the +# version, so we catch the generic 'Exception'. +try: + from setuptools_scm import get_version + version = get_version(root='..', relative_to=__file__) +except Exception: + version = '{version}' +""".lstrip() -setup(version=version, cmdclass=cmdclass, **package_info) +{% if cookiecutter.include_example_code == 'y' %} +setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), + 'write_to_template': VERSION_TEMPLATE}, + ext_modules=get_extensions()) +{% elif %} +setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), + 'write_to_template': VERSION_TEMPLATE}) +{% endif %} diff --git a/{{ cookiecutter.package_name }}/tox.ini b/{{ cookiecutter.package_name }}/tox.ini new file mode 100644 index 00000000..d3a85cc9 --- /dev/null +++ b/{{ cookiecutter.package_name }}/tox.ini @@ -0,0 +1,78 @@ +[tox] +envlist = + py{36,37,38}-test{,-alldeps,-oldestdeps,-devdeps,-numpy116,-numpy117,-numpy118} + build_docs + codestyle +requires = + setuptools >= 30.3.0 + pip >= 19.3.1 +isolated_build = true + +[testenv] + +# Pass through the following environemnt variables which may be needed for the CI +passenv = HOME WINDIR LC_ALL LC_CTYPE CC CI TRAVIS + +# Run the tests in a temporary directory to make sure that we don't import +# astropy from the source tree +changedir = .tmp/{envname} + +# tox environments are constructued with so-called 'factors' (or terms) +# separated by hyphens, e.g. test-devdeps-cov. Lines below starting with factor: +# will only take effect if that factor is included in the environment name. To +# see a list of example environments that can be run, along with a description, +# run: +# +# tox -l -v +# +description = + run tests + alldeps: with all optional dependencies + devdeps: with the latest developer version of key dependencies + oldestdeps: with the oldest supported version of key dependencies + cov: and test coverage + numpy116: with numpy 1.16.* + numpy117: with numpy 1.17.* + numpy118: with numpy 1.18.* + +deps = + + numpy116: numpy==1.16.* + numpy117: numpy==1.17.* + numpy118: numpy==1.18.* + + # The devdeps factor is intended to be used to install the latest developer version + # of key dependencies. + devdeps: git+https://github.com/numpy/numpy.git#egg=numpy + devdeps: git+https://github.com/astropy/astropy.git#egg=astropy + +# The following indicates which extras_require from setup.cfg will be installed +extras = + test + alldeps: all + +commands = + pip freeze + pytest --pyargs {{ cookiecutter.module_name }} {toxinidir}/docs --cov {{ cookiecutter.module_name }} --cov-config={toxinidir}/setup.cfg {posargs} + +[testenv:build_docs] +changedir = docs +description = invoke sphinx-build to build the HTML docs +extras = docs +commands = + pip freeze + sphinx-build -W -b html . _build/html + +[testenv:linkcheck] +changedir = docs +description = check the links in the HTML docs +extras = docs +commands = + pip freeze + sphinx-build -W -b linkcheck . _build/html + +[testenv:codestyle] +skip_install = true +description = check code style, e.g. with flake8 +deps = flake8 +commands = flake8 {{ cookiecutter.module_name }} --count diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py index 7c3fffa6..7e930be5 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py @@ -13,10 +13,6 @@ from .version import version as __version__ except ImportError: __version__ = '' -try: - from .version import githash as __githash__ -except ImportError: - __githash__ = '' if not _ASTROPY_SETUP_: # noqa From 517e032a821d603944170be2ba570984a3c7fd8a Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 21:53:17 +0000 Subject: [PATCH 02/44] Updated CI configuration --- {{ cookiecutter.package_name }}/.travis.yml | 159 ++++++++---------- {{ cookiecutter.package_name }}/setup.cfg | 33 ++++ .../tests/coveragerc | 31 ---- 3 files changed, 99 insertions(+), 124 deletions(-) delete mode 100644 {{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/coveragerc diff --git a/{{ cookiecutter.package_name }}/.travis.yml b/{{ cookiecutter.package_name }}/.travis.yml index b3726ae4..273d8281 100644 --- a/{{ cookiecutter.package_name }}/.travis.yml +++ b/{{ cookiecutter.package_name }}/.travis.yml @@ -1,7 +1,8 @@ -# We set the language to c because python isn't supported on the MacOS X nodes -# on Travis. However, the language ends up being irrelevant anyway, since we -# install Python ourselves using conda. -language: c +language: python + +# We need a full clone to make sure setuptools_scm works properly +git: + depth: false os: - linux @@ -33,47 +34,23 @@ stages: env: global: + # The following versions are the 'default' for tests, unless # overridden underneath. They are defined here in order to save having # to repeat them for all configurations. - - PYTHON_VERSION=3.7 - - NUMPY_VERSION=stable - - ASTROPY_VERSION=stable - - MAIN_CMD='python setup.py' - - SETUP_CMD='test' - - EVENT_TYPE='pull_request push' - - {% if cookiecutter.include_example_cython_code == 'y' %} - # For this package-template, we include examples of Cython modules, - # so Cython is required for testing. If your package does not include - # Cython code, you can set CONDA_DEPENDENCIES='' - - CONDA_DEPENDENCIES='Cython' - - CONDA_DEPENDENCIES_DOC='Cython sphinx-astropy' - {% else %} - # List runtime dependencies for the package that are available as conda - # packages here. - - CONDA_DEPENDENCIES='' - - CONDA_DEPENDENCIES_DOC='sphinx-astropy' - {% endif %} - # List other runtime dependencies for the package that are available as - # pip packages here. - - PIP_DEPENDENCIES='' - - # Conda packages for affiliated packages are hosted in channel - # "astropy" while builds for astropy LTS with recent numpy versions - # are in astropy-ci-extras. If your package uses either of these, - # add the channels to CONDA_CHANNELS along with any other channels - # you want to use. - - CONDA_CHANNELS='astropy' - - # If there are matplotlib or other GUI tests, uncomment the following - # line to use the X virtual framebuffer. - # - SETUP_XVFB=True - - # If you want to ignore certain flake8 errors, you can list them - # in FLAKE8_OPT, for example: - # - FLAKE8_OPT='--ignore=E501' - - FLAKE8_OPT='' + + # The following three variables are for tox. TOXENV is a standard + # variable that tox uses to determine the environment to run, + # TOXARGS are arguments passed to tox, and TOXPOSARGS are arguments + # that tox passes through to the {posargs} indicator in tox.ini. + # The latter can be used for example to pass arguments to pytest. + - TOXENV='test' + - TOXARGS='-v' + - TOXPOSARGS='' + + # The following is needed to avoid issues if e.g. Matplotlib tries + # to open a GUI window. + - SETUP_XVFB=True matrix: @@ -81,98 +58,94 @@ matrix: fast_finish: true include: - # Make sure that egg_info works without dependencies - - stage: Initial tests - env: PYTHON_VERSION=3.7 SETUP_CMD='egg_info' # Try MacOS X, usually enough only to run from cron as hardly there are - # issues that are not picked up by a linux worker + # issues that are not picked up by a linux worker. We set language to + # 'c' since 'python' doesn't work on non-Linux platforms. - os: osx + language: c stage: Cron tests - env: SETUP_CMD='test' EVENT_TYPE='cron' + env: PYTHON_VERSION=3.7 TOXENV=py37-test - # Do a coverage test. + # Do a regular build on Linux with Python 3.8. + # For Linux we use language: python to avoid using conda. - os: linux + python: 3.8 stage: Initial tests - env: SETUP_CMD='test --coverage' + env: TOXENV=py38-test - # Check for sphinx doc build warnings - we do this first because it - # may run for a long time + # Check for sphinx doc build warnings - os: linux - env: SETUP_CMD='build_docs -w' - CONDA_DEPENDENCIES=$CONDA_DEPENDENCIES_DOC + python: 3.8 + env: TOXENV=build_docs - # Now try Astropy dev with the latest Python and LTS with and 3.x. + # Now try Astropy dev with the latest Python - os: linux - env: ASTROPY_VERSION=development - EVENT_TYPE='pull_request push cron' + python: 3.8 + env: TOXENV=py38-test-devdeps + + # And with an older Python, Astropy LTS, and the oldest supported Numpy - os: linux - env: PYTHON_VERSION=3.6 ASTROPY_VERSION=lts NUMPY_VERSION=1.13 + python: 3.6 + env: TOXENV=py36-test-astropylts-numpy116 # Add a job that runs from cron only and tests against astropy dev and # numpy dev to give a change for early discovery of issues and feedback # for both developer teams. - os: linux + python: 3.8 stage: Cron tests - env: ASTROPY_VERSION=development NUMPY_VERSION=development - EVENT_TYPE='cron' + env: TOXENV=py36-test-astropydev-numpydev # Try on Windows. - os: windows + language: c stage: Slow tests - env: SETUP_CMD='test' + env: PYTHON_VERSION=3.8 TOXENV=py38-test - # Try all python versions and Numpy versions. Since we can assume that + # Try other python versions and Numpy versions. Since we can assume that # the Numpy developers have taken care of testing Numpy with different # versions of Python, we can vary Python and Numpy versions at the same # time. - os: linux - env: PYTHON_VERSION=3.6 NUMPY_VERSION=1.14 - - os: linux - env: NUMPY_VERSION=1.15 + python: 3.7 + env: TOXENV=py37-test-astropy30-numpy117 - # Do a PEP8 test with flake8 + # Do a code style check - os: linux + python: 3.8 stage: Initial tests - env: MAIN_CMD='flake8 {{ cookiecutter.module_name }} --count --show-source --statistics $FLAKE8_OPT' SETUP_CMD='' + env: TOXENV=codestyle allow_failures: # Do a PEP8 test with flake8 # (do allow to fail unless your code completely compliant) # - os: linux + # python: 3.8 # stage: Initial tests - # env: MAIN_CMD='flake8 {{ cookiecutter.module_name }} --count --show-source --statistics $FLAKE8_OPT' SETUP_CMD='' + # env: TOXENV=codestyle install: - # We now use the ci-helpers package to set up our testing environment. - # This is done by using Miniconda and then using conda and pip to install - # dependencies. Which dependencies are installed using conda and pip is - # determined by the CONDA_DEPENDENCIES and PIP_DEPENDENCIES variables, - # which should be space-delimited lists of package names. See the README - # in https://github.com/astropy/ci-helpers for information about the full - # list of environment variables that can be used to customize your - # environment. In some cases, ci-helpers may not offer enough flexibility - # in how to install a package, in which case you can have additional - # commands in the install: section below. - - - git clone --depth 1 git://github.com/astropy/ci-helpers.git - - source ci-helpers/travis/setup_conda.sh - - # As described above, using ci-helpers, you should be able to set up an - # environment with dependencies installed using conda and pip, but in some - # cases this may not provide enough flexibility in how to install a - # specific dependency (and it will not be able to install non-Python - # dependencies). Therefore, you can also include commands below (as - # well as at the start of the install section or in the before_install - # section if they are needed before setting up conda) to install any - # other dependencies. + # We now use the ci-helpers package to set up our Python environment + # on Windows and MacOS X but we don't set up any other dependencies, + # instead using tox to do this. See https://github.com/astropy/ci-helpers + # for more information about ci-helpers. + + - if [[ $TRAVIS_OS_NAME != linux ]]; then + git clone --depth 1 git://github.com/astropy/ci-helpers.git; + source ci-helpers/travis/setup_conda.sh; + fi script: - - $MAIN_CMD $SETUP_CMD + - pip install tox + - tox $TOXARGS -- $TOXPOSARGS after_success: - # If coveralls.io is set up for this package, uncomment the line below. - # The coveragerc file may be customized as needed for your package. - # - if [[ $SETUP_CMD == *coverage* ]]; then coveralls --rcfile='{{ cookiecutter.module_name }}/tests/coveragerc'; fi + # If coveralls.io is set up for this package, uncomment the two lines below. + # pip install coveralls + # coveralls + # If codecov is set up for this package, uncomment the two lines below + # pip install codecov + # codecov diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index f2e86d60..acda2de5 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -39,3 +39,36 @@ astropy_header = true doctest_plus = enabled text_file_format = rst addopts = --doctest-rst + +[coverage:run] +omit = + {packagename}/_{{ cookiecutter._parent_project }}_init* + {packagename}/conftest.py + {packagename}/*setup_package* + {packagename}/tests/* + {packagename}/*/tests/* + {packagename}/extern/* + {packagename}/version* + */{packagename}/_{{ cookiecutter._parent_project }}_init* + */{packagename}/conftest.py + */{packagename}/*setup_package* + */{packagename}/tests/* + */{packagename}/*/tests/* + */{packagename}/extern/* + */{packagename}/version* + +[coverage:report] +exclude_lines = + # Have to re-enable the standard pragma + pragma: no cover + # Don't complain about packages we have installed + except ImportError + # Don't complain if tests don't hit assertions + raise AssertionError + raise NotImplementedError + # Don't complain about script hooks + def main\(.*\): + # Ignore branches that don't pertain to this version of Python + pragma: py{ignore_python_version} + # Don't complain about IPython completion helper + def _ipython_key_completions_ diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/coveragerc b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/coveragerc deleted file mode 100644 index 89e98ec8..00000000 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/coveragerc +++ /dev/null @@ -1,31 +0,0 @@ -[run] -source = {packagename} -omit = - {packagename}/_{{ cookiecutter._parent_project }}_init* - {packagename}/conftest* - {packagename}/cython_version* - {packagename}/setup_package* - {packagename}/*/setup_package* - {packagename}/*/*/setup_package* - {packagename}/tests/* - {packagename}/*/tests/* - {packagename}/*/*/tests/* - {packagename}/version* - -[report] -exclude_lines = - # Have to re-enable the standard pragma - pragma: no cover - - # Don't complain about packages we have installed - except ImportError - - # Don't complain if tests don't hit assertions - raise AssertionError - raise NotImplementedError - - # Don't complain about script hooks - def main\(.*\): - - # Ignore branches that don't pertain to this version of Python - pragma: py{ignore_python_version} \ No newline at end of file From 0b4895cf9f361846eabbfd534698f0b44070ad94 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 22:50:42 +0000 Subject: [PATCH 03/44] More improvements to infrastructure --- .travis.yml | 23 ++---- {{ cookiecutter.package_name }}/.travis.yml | 24 ++++-- .../pyproject.toml | 2 +- {{ cookiecutter.package_name }}/setup.cfg | 4 +- {{ cookiecutter.package_name }}/setup.py | 4 +- {{ cookiecutter.package_name }}/tox.ini | 10 ++- .../__init__.py | 16 ++-- ...{{ cookiecutter._parent_project }}_init.py | 2 +- .../conftest.py | 73 ++++++++----------- .../data/README.rst | 1 - 10 files changed, 75 insertions(+), 84 deletions(-) diff --git a/.travis.yml b/.travis.yml index 213526d1..cf7653b0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,11 +1,10 @@ -# We set the language to c because python isn't supported on the MacOS X nodes -# on Travis. However, the language ends up being irrelevant anyway, since we -# install Python ourselves using conda. -language: c +language: python os: - linux +python: 3.8 + env: global: @@ -13,10 +12,6 @@ env: # overridden underneath. They are defined here in order to save having # to repeat them for all configurations. - FOLDERNAME='packagename' - - PYTHON_VERSION=3.7 - - CONDA_DEPENDENCIES='cython astropy sphinx' - - PIP_DEPENDENCIES='cookiecutter gitpython pytest-astropy sphinx-astropy' - - EVENT_TYPE='pull_request push' - TASK='test' - EXTRA_CONTEXT='' - FLAGS='' @@ -34,19 +29,15 @@ env: - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='include_example_cython_code=y initialize_git_repo=n license=Other' install: - - - git clone --depth 1 git://github.com/astropy/ci-helpers.git - - source ci-helpers/travis/setup_conda.sh + - pip sphinx cookiecuter gitpython tox script: - cd docs ; make html ; cd .. - cookiecutter --no-input ./ -o ../test $EXTRA_CONTEXT $FLAGS - cd ../test/$FOLDERNAME - - if [[ $TASK == 'test' ]]; then python setup.py egg_info; fi - - if [[ $TASK == 'test' ]]; then python setup.py build; fi - - if [[ $TASK == 'test' ]]; then python setup.py build_docs; fi - - if [[ $TASK == 'test' ]]; then python setup.py test; fi - - if [[ $TASK == 'error_check' ]]; then python setup.py egg_info 2>&1 | grep "ERROR:"; fi + - if [[ $TASK == 'test' ]]; then tox -e py38-test; fi + - if [[ $TASK == 'test' ]]; then tox -e build_docs; fi + - if [[ $TASK == 'test' ]]; then tox -e codestyle; fi after_success: diff --git a/{{ cookiecutter.package_name }}/.travis.yml b/{{ cookiecutter.package_name }}/.travis.yml index 273d8281..d59b87c1 100644 --- a/{{ cookiecutter.package_name }}/.travis.yml +++ b/{{ cookiecutter.package_name }}/.travis.yml @@ -18,18 +18,14 @@ addons: - graphviz -stage: Comprehensive tests - stages: # Do the style check and a single test job, don't proceed if it fails - name: Initial tests # Test docs, astropy dev, and without optional dependencies - name: Comprehensive tests - # Slow tests that should only run if comprehensive ones passed - - name: Slow tests # These will only run when cron is opted in - name: Cron tests - if: type = cron + # if: type = cron env: @@ -64,6 +60,7 @@ matrix: # 'c' since 'python' doesn't work on non-Linux platforms. - os: osx language: c + name: Python 3.7 with required dependencies stage: Cron tests env: PYTHON_VERSION=3.7 TOXENV=py37-test @@ -71,22 +68,29 @@ matrix: # For Linux we use language: python to avoid using conda. - os: linux python: 3.8 + name: Python 3.8 with required dependencies stage: Initial tests env: TOXENV=py38-test # Check for sphinx doc build warnings - os: linux python: 3.8 + name: Documentation build + stage: Comprehensive tests env: TOXENV=build_docs # Now try Astropy dev with the latest Python - os: linux python: 3.8 + name: Python 3.8 with developer version of astropy + stage: Comprehensive tests env: TOXENV=py38-test-devdeps # And with an older Python, Astropy LTS, and the oldest supported Numpy - os: linux python: 3.6 + name: Python 3.6 astropy LTS and Numpy 1.16 + stage: Comprehensive tests env: TOXENV=py36-test-astropylts-numpy116 # Add a job that runs from cron only and tests against astropy dev and @@ -94,13 +98,15 @@ matrix: # for both developer teams. - os: linux python: 3.8 + name: Python 3.6 latest developer version of key dependencies stage: Cron tests - env: TOXENV=py36-test-astropydev-numpydev + env: TOXENV=py36-test-devdeps # Try on Windows. - os: windows language: c - stage: Slow tests + name: Python 3.8 with required dependencies + stage: Comprehensive tests env: PYTHON_VERSION=3.8 TOXENV=py38-test # Try other python versions and Numpy versions. Since we can assume that @@ -110,11 +116,14 @@ matrix: - os: linux python: 3.7 + name: Python 3.7 with astropy 3.0 and Numpy 1.17 + stage: Comprehensive tests env: TOXENV=py37-test-astropy30-numpy117 # Do a code style check - os: linux python: 3.8 + name: Code style checks stage: Initial tests env: TOXENV=codestyle @@ -123,6 +132,7 @@ matrix: # (do allow to fail unless your code completely compliant) # - os: linux # python: 3.8 + # name: Code style checks # stage: Initial tests # env: TOXENV=codestyle diff --git a/{{ cookiecutter.package_name }}/pyproject.toml b/{{ cookiecutter.package_name }}/pyproject.toml index b27affd7..64816ac2 100644 --- a/{{ cookiecutter.package_name }}/pyproject.toml +++ b/{{ cookiecutter.package_name }}/pyproject.toml @@ -6,7 +6,7 @@ requires = ["setuptools", "extension-helpers", "oldest-supported-numpy", "cython==0.29.14"] -{% elif %} +{% else %} requires = ["setuptools", "setuptools_scm", "wheel"] diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index acda2de5..e79f44ac 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -3,7 +3,7 @@ name = {{ cookiecutter.module_name }} author = {{ cookiecutter.author_name }} author_email = {{ cookiecutter.author_email }} license = {{ cookiecutter.license }} -license_file = LICENSE.rst +license_file = licenses/LICENSE.rst url = {{ cookiecutter.project_url }} description = {{ cookiecutter.short_description }} long_description = file: README.rst @@ -13,7 +13,7 @@ github_project = {{ cookiecutter.github_project }} [options] zip_safe = False packages = find: -python_requires = ">={{ cookiecutter.minimum_python_version }}" +python_requires = >={{ cookiecutter.minimum_python_version }} setup_requires = setuptools_scm install_requires = {{ cookiecutter._install_requires }} diff --git a/{{ cookiecutter.package_name }}/setup.py b/{{ cookiecutter.package_name }}/setup.py index 42e0042b..34478612 100755 --- a/{{ cookiecutter.package_name }}/setup.py +++ b/{{ cookiecutter.package_name }}/setup.py @@ -7,7 +7,7 @@ import os import sys -from setuptools import setup, +from setuptools import setup from setuptools.config import read_configuration {% if cookiecutter.include_example_code == 'y' %} from extension_helpers import get_extensions @@ -81,7 +81,7 @@ setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), 'write_to_template': VERSION_TEMPLATE}, ext_modules=get_extensions()) -{% elif %} +{% else %} setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), 'write_to_template': VERSION_TEMPLATE}) {% endif %} diff --git a/{{ cookiecutter.package_name }}/tox.ini b/{{ cookiecutter.package_name }}/tox.ini index d3a85cc9..706ec539 100644 --- a/{{ cookiecutter.package_name }}/tox.ini +++ b/{{ cookiecutter.package_name }}/tox.ini @@ -41,8 +41,11 @@ deps = numpy117: numpy==1.17.* numpy118: numpy==1.18.* - # The devdeps factor is intended to be used to install the latest developer version - # of key dependencies. + astropy30: astropy==3.0.* + astropy40: astropy==4.0.* + astropylts: astropy==4.0.* + astropydev: git+https://github.com/astropy/astropy.git#egg=astropy + devdeps: git+https://github.com/numpy/numpy.git#egg=numpy devdeps: git+https://github.com/astropy/astropy.git#egg=astropy @@ -73,6 +76,7 @@ commands = [testenv:codestyle] skip_install = true +changedir = . description = check code style, e.g. with flake8 deps = flake8 -commands = flake8 {{ cookiecutter.module_name }} --count +commands = flake8 {{ cookiecutter.module_name }} --count --max-line-length=100 diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/__init__.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/__init__.py index cab415f6..b69d7423 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/__init__.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/__init__.py @@ -24,14 +24,10 @@ class UnsupportedPythonError(Exception): raise UnsupportedPythonError("{{ cookiecutter.module_name }} does not support Python < {}" .format(__minimum_python_version__)) -if not _ASTROPY_SETUP_: # noqa - # For egg_info test builds to pass, put package imports here. -{%- if cookiecutter.include_example_code != 'y' %} - pass -{%- else %} - from .example_mod import * # noqa - # Then you can be explicit to control what ends up in the namespace, - __all__ += ['do_primes'] # noqa - # or you can keep everything from the subpackage with the following instead - # __all__ += example_mod.__all__ +{%- if cookiecutter.include_example_code == 'y' %} +from .example_mod import * # noqa +# Then you can be explicit to control what ends up in the namespace, +__all__ += ['do_primes'] # noqa +# or you can keep everything from the subpackage with the following instead +# __all__ += example_mod.__all__ {%- endif %} diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py index 7e930be5..2dffe8fd 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init.py @@ -1,6 +1,6 @@ # Licensed under a 3-clause BSD style license - see LICENSE.rst -__all__ = ['__version__', '__githash__'] +__all__ = ['__version__'] # this indicates whether or not we are in the package's setup.py try: diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index 6cbbb303..562a3889 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -3,47 +3,38 @@ import os from astropy.version import version as astropy_version + +# For Astropy 3.0 and later, we can use the standalone pytest plugin if astropy_version < '3.0': - # With older versions of Astropy, we actually need to import the pytest - # plugins themselves in order to make them discoverable by pytest. - from astropy.tests.pytest_plugins import * + from astropy.tests.pytest_plugins import * # noqa + del pytest_report_header else: - # As of Astropy 3.0, the pytest plugins provided by Astropy are - # automatically made available when Astropy is installed. This means it's - # not necessary to import them here, but we still need to import global - # variables that are used for configuration. - from astropy.tests.plugins.display import (pytest_report_header, - PYTEST_HEADER_MODULES, - TESTED_VERSIONS) - -from astropy.tests.helper import enable_deprecations_as_exceptions - -## Uncomment the following line to treat all DeprecationWarnings as -## exceptions. For Astropy v2.0 or later, there are 2 additional keywords, -## as follow (although default should work for most cases). -## To ignore some packages that produce deprecation warnings on import -## (in addition to 'compiler', 'scipy', 'pygments', 'ipykernel', and -## 'setuptools'), add: -## modules_to_ignore_on_import=['module_1', 'module_2'] -## To ignore some specific deprecation warning messages for Python version -## MAJOR.MINOR or later, add: -## warnings_to_ignore_by_pyver={(MAJOR, MINOR): ['Message to ignore']} -# enable_deprecations_as_exceptions() + from pytest_astropy_header.display import PYTEST_HEADER_MODULES, TESTED_VERSIONS + + +def pytest_configure(config): + + config.option.astropy_header = True -# Customize the following lines to add/remove entries from -# the list of packages for which version numbers are displayed when running -# the tests. Making it pass for KeyError is essential in some cases when -# the package uses other astropy affiliated packages. -try: - PYTEST_HEADER_MODULES['Astropy'] = 'astropy' - del PYTEST_HEADER_MODULES['h5py'] -except KeyError: - pass - -# This is to figure out the package version, rather than -# using Astropy's -from .version import version, astropy_helpers_version - -packagename = os.path.basename(os.path.dirname(__file__)) -TESTED_VERSIONS[packagename] = version -TESTED_VERSIONS['astropy_helpers'] = astropy_helpers_version + # Customize the following lines to add/remove entries from the list of + # packages for which version numbers are displayed when running the tests. + PYTEST_HEADER_MODULES.pop('Pandas', None) + PYTEST_HEADER_MODULES['scikit-image'] = 'skimage' + + from .version import version + packagename = os.path.basename(os.path.dirname(__file__)) + TESTED_VERSIONS[packagename] = version + +from astropy.tests.helper import enable_deprecations_as_exceptions # noqa + +# Uncomment the last line in this block to treat all DeprecationWarnings as +# exceptions. For Astropy v2.0 or later, there are 2 additional keywords, +# as follow (although default should work for most cases). +# To ignore some packages that produce deprecation warnings on import +# (in addition to 'compiler', 'scipy', 'pygments', 'ipykernel', and +# 'setuptools'), add: +# modules_to_ignore_on_import=['module_1', 'module_2'] +# To ignore some specific deprecation warning messages for Python version +# MAJOR.MINOR or later, add: +# warnings_to_ignore_by_pyver={(MAJOR, MINOR): ['Message to ignore']} +# enable_deprecations_as_exceptions() diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/data/README.rst b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/data/README.rst index 9cc3b1ad..382f6e76 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/data/README.rst +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/data/README.rst @@ -4,4 +4,3 @@ Data directory This directory contains data files included with the package source code distribution. Note that this is intended only for relatively small files - large files should be externally hosted and downloaded as needed. - From bef5dcadbffaabb5e5224cc05db11c87cfa25d3b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 22:51:50 +0000 Subject: [PATCH 04/44] Fix Python version --- {{ cookiecutter.package_name }}/.travis.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{ cookiecutter.package_name }}/.travis.yml b/{{ cookiecutter.package_name }}/.travis.yml index d59b87c1..db6eb75c 100644 --- a/{{ cookiecutter.package_name }}/.travis.yml +++ b/{{ cookiecutter.package_name }}/.travis.yml @@ -98,9 +98,9 @@ matrix: # for both developer teams. - os: linux python: 3.8 - name: Python 3.6 latest developer version of key dependencies + name: Python 3.8 latest developer version of key dependencies stage: Cron tests - env: TOXENV=py36-test-devdeps + env: TOXENV=py38-test-devdeps # Try on Windows. - os: windows From 18b0b770ea98f2c96a392f40fe6a2a8cf2b72cd5 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 22:54:27 +0000 Subject: [PATCH 05/44] Fix syntax and spelling --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index cf7653b0..358b0cfa 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ env: - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='include_example_cython_code=y initialize_git_repo=n license=Other' install: - - pip sphinx cookiecuter gitpython tox + - pip install sphinx cookiecutter gitpython tox script: - cd docs ; make html ; cd .. From 16785ed9eac0cc76f34b32f6138a91abdffd0d97 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 17 Jan 2020 23:06:18 +0000 Subject: [PATCH 06/44] Fix dependency --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 358b0cfa..d7f57b56 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,7 +29,7 @@ env: - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='include_example_cython_code=y initialize_git_repo=n license=Other' install: - - pip install sphinx cookiecutter gitpython tox + - pip install sphinx-astropy cookiecutter gitpython tox script: - cd docs ; make html ; cd .. From 2af909cac70fd000bdaaeff3180be1124b057f3f Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 22 Jan 2020 19:27:39 +0000 Subject: [PATCH 07/44] Added initial migration guide to Sphinx docs --- docs/ape17.rst | 682 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 683 insertions(+) create mode 100644 docs/ape17.rst diff --git a/docs/ape17.rst b/docs/ape17.rst new file mode 100644 index 00000000..b97af244 --- /dev/null +++ b/docs/ape17.rst @@ -0,0 +1,682 @@ +APE 17 Migration Guide +====================== + +The Astropy project is now transitioning from using astropy-helpers for +infrastructure to more standard Python packaging tools. The motivation +and implications of this are discussed in an Astropy Proposal for +Enhancements: `APE 17: A roadmap for package infrastructure without +astropy-helpers `__ + +This document is a **work in progress** and aims to provide a guide to +migrating to using the new infrastructure described in APE 17. We assume +that your package is currently using astropy-helpers and that you have +used a version of the Astropy package-template in the past to set up +your package (though this guide might still be useful if the latter is +not the case). + +Throughout this guide, we will assume that your package is called +``my-package`` and that the module is called ``my_package``. We +deliberately choose a name where the package name is different from the +module name, but for many cases, these will be the same. + +Step 1: Remove astropy-helpers +------------------------------ + +To remove the astropy-helpers submodule, first, run:: + + git rm -r astropy_helpers + +if ``astropy_helpers`` was the only submodule in your repository, the +``.gitmodules`` file will be empty, you can remove this if you wish. + +Next you should remove the ``ah_bootstrap.py`` file:: + + git rm ah_bootstrap.py + +You can now commit your changes with:: + + git commit -m "Remove astropy-helpers submodule" + +Step 2: Update/create ``setup.cfg`` +----------------------------------- + +The next step is to update make sure that you have a ``setup.cfg`` file +that contains meta-data about the package. If you already have this +file, you will likely need to update it, and if you don’t already have +this file, you will need to create it. + +This file should contain at least the following entries:: + + [metadata] + name = my-package + author = ... + author_email = ... + license = ... + license_file = LICENSE.rst + url = ... + description = ... + long_description = file: README.rst + + [options] + zip_safe = False + packages = find: + install_requires = + numpy + astropy + ... + python_requires = >=3.6 + +Replace the ``...`` with the information for your package. Make sure +that ``license_file`` and ``long_description`` have the right filename, +and specify your required dependencies one per line in the +``install_requires`` section. Make sure the ``python_requires`` line is +set to indicate the correct minimum Python version for your package. + +If you already had a file, make sure you remove the following entries +(if present): + +- ``package_name`` +- ``version`` +- ``setup_requires`` +- ``tests_require`` +- ``[ah_bootstrap]`` and all entries in it + +Step 3 - Define Optional, test, and docs dependencies +----------------------------------------------------- + +Next up, add a new section to the ``setup.cfg`` file (or modify, if it +already exists), to specify optional dependencies as well as +dependencies required to run tests and build the documentation, for +example:: + + [options.extras_require] + all = + scipy + matplotlib + test = + pytest-astropy + docs = + sphinx-astropy + +If you don’t need any optional dependencies, remove the ``all`` section. +You will likely need to have at least ``pytest-astropy`` in the ``test`` +section and ``sphinx-astropy`` in ``docs``. + +Step 4 - Define package data +---------------------------- + +If your package includes non-Python data files, you will need to update +how you declare which data files to include. If you have been using the +Astropy package template, it is likely that you have functions called +``get_package_data`` defined inside ``setup_package.py`` files. Remove +these functions, and instead define the package data using a +``[options.package_data]`` section inside your ``setup.cfg`` file, +e.g.:: + + [options.package_data] + * = *.fits, *.csv + my_package.tests = data/* + +In the above example, all ``.fits`` and ``.csv`` in the package will be +included as well as all files inside ``my_package/tests/data``. + +Step 5 - Update your ``setup.py`` file +-------------------------------------- + +If you don’t have any compiled (e.g. C or Cython) extensions in your +package, you can replace your existing ``setup.py`` file with the +following: + +.. code:: python + + #!/usr/bin/env python + + import os + import sys + from setuptools import setup + + TEST_HELP = """ + Note: running tests is no longer done using 'python setup.py test'. Instead + you will need to run: + + tox -e test + + If you don't already have tox installed, you can install it with: + + pip install tox + + If you only want to run part of the test suite, you can also use pytest + directly with:: + + pip install -e . + pytest + + For more information, see: + + http://docs.astropy.org/en/latest/development/testguide.html#running-tests + """ + + if 'test' in sys.argv: + print(TEST_HELP) + sys.exit(1) + + DOCS_HELP = """ + Note: building the documentation is no longer done using + 'python setup.py build_docs'. Instead you will need to run: + + tox -e build_docs + + If you don't already have tox installed, you can install it with: + + pip install tox + + For more information, see: + + http://docs.astropy.org/en/latest/install.html#builddocs + """ + + if 'build_docs' in sys.argv or 'build_sphinx' in sys.argv: + print(DOCS_HELP) + sys.exit(1) + + setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}) + +Step 6: add a ``pyproject.toml`` file +------------------------------------- + +The ``pyproject.toml`` file is used to declare dependencies needed to +run ``setup.py`` and build the package. If your package doesn’t have any +compiled extensions, the file should contain: + +.. code:: toml + + [build-system] + requires = ["setuptools", + "wheel"] + build-backend = 'setuptools.build_meta' + +Step 7 - Handling C/Cython extensions +------------------------------------- + +If your package has no compiled C/Cython extensions, you can skip this +step. Otherwise, if you have C or Cython extensions, you can either +define your extensions manually inside the ``setup.py`` file or make use +of the `extension-helpers `__ +package to collect extensions in a similar way to astropy-helpers. + +Step 7a - Defining extensions manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can define extensions manually as described +`here `__. +If you do this, you can remove all ``setup_package.py`` files in your +package. + +If you have Cython extensions or your extensions use the NumPy C API, +proceed to Step 7c, otherwise you can proceed to Step 8. + +Step 7b - Using extension-helpers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the extension-helpers package to: + +- Automatically define extensions for Cython files +- Pick up extensions declared in ``setup_package.py`` files, as + described in the `extension-helpers + documentation `__. + +The latter works by looking through all the ``setup_package.py`` files +in your package and executing the ``get_extensions()`` functions, which +each should return a list of extensions. Check through your existing +``setup_package.py`` files (if any), and make sure that any +``astropy_helpers`` imports are changed to ``extension_helpers``. + +Next, add: + +.. code:: python + + from extension_helpers.setup_helpers import get_extensions + +just under the following lines at the top of the ``setup.py`` file: + +.. code:: python + + import sys + from setuptools import setup + +In addition, in the same file, change: + +.. code:: python + + setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}) + +to + +.. code:: python + + setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}, + ext_modules=get_extensions()) + +If you have Cython extensions or your extensions use the NumPy C API, +proceed to Step 7c, otherwise you can proceed to Step 8. + +Step 7c - Cython and Numpy build-time dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your compiled extensions rely on the NumPy C API, you will need to +declare Numpy as a build-time dependency in ``pyproject.toml``. Note +that as described in `APE +17 `__, +you need to pin the build-time Numpy dependency to the **oldest** +supported Numpy version for each Python version. However, rather than +doing this manually, you can add the ``oldest-supported-numpy`` package +to your ``pyproject.toml`` file: + +.. code:: toml + + [build-system] + requires = ["setuptools", + "wheel", + "oldest-supported-numpy"] + build-backend = 'setuptools.build_meta' + +If you have Cython extensions, you will need to also add an entry for +Cython, pinning it to a recent version: + +.. code:: toml + + [build-system] + requires = ["setuptools", + "wheel", + "cython==0.29.14"] + build-backend = 'setuptools.build_meta' + +Whenever a new major Python version is released, you will likely need to +update this pinning to use the most recent Cython version available. + +Step 8 - Using setuptools_scm +----------------------------- + +The `setuptools_scm `__ +package is now recommended to manage the version numbers for your +package. The way this works is that instead of setting the version +number manually in e.g. \ ``setup.cfg`` or elsewhere in your package, +the version number is based on git tags. + +First, define ``setup_requires`` inside the ``[options]`` section of +your ``setup.cfg`` file:: + + [options] + ... + setup_requires = setuptools_scm + ... + +Next, add ``setuptools_scm`` as a build-time dependency in the +``requires`` list of your ``pyproject.toml`` file: + +.. code:: toml + + [build-system] + requires = ["setuptools", + "setuptools_scm", + ... + +Check your ``.gitignore`` and make sure that you have a line containing:: + + my_package/version.py + +Finally, edit your ``my_package/_astropy_init.py`` file and remove the +following lines: + +.. code:: python + + try: + from .version import githash as __githash__ + except ImportError: + __githash__ = '' + +and remove ``'__githash__'`` from the ``__all__`` list at the top of the +file. + +The git hash is now contained in the version number, so this is no +longer needed. + +Step 9 - Configuring pytest +--------------------------- + +To make sure that pytest works properly, you can set a few options in a +``[tool:pytest]`` section in your ``setup.cfg`` file:: + + [tool:pytest] + testpaths = "my_package" "docs" + astropy_header = true + doctest_plus = enabled + text_file_format = rst + addopts = --doctest-rst + +For the ``testpaths`` line, make sure you replace ``my_package`` with +the name of your package. + +The remaining options ensure that the output from pytest includes a +header that lists dependencies and system information, and also ensure +that the ``.rst`` files are picked up and tested by pytest. + +Step 10 - Update ``MANIFEST.in`` +-------------------------------- + +Edit your ``MANIFEST.in`` file to remove the following lines, if present +(and any other line related to ``astropy_helpers``):: + + include ez_setup.py + include ah_bootstrap.py + + # the next few stanzas are for astropy_helpers. It's derived from the + # astropy_helpers/MANIFEST.in, but requires additional includes for the actual + # package directory and egg-info. + + include astropy_helpers/README.rst + include astropy_helpers/CHANGES.rst + include astropy_helpers/LICENSE.rst + recursive-include astropy_helpers/licenses * + + include astropy_helpers/ez_setup.py + include astropy_helpers/ah_bootstrap.py + + recursive-include astropy_helpers/astropy_helpers *.py *.pyx *.c *.h + recursive-include astropy_helpers/astropy_helpers.egg-info * + # include the sphinx stuff with "*" because there are css/html/rst/etc. + recursive-include astropy_helpers/astropy_helpers/sphinx * + + prune astropy_helpers/build + prune astropy_helpers/astropy_helpers/tests + +Then add a new line near the top with the following:: + + include pyproject.toml + +Step 11 - Updating your documentation configuration +--------------------------------------------------- + +You will need to edit the ``docs/conf.py`` file to make sure it does not +use astropy-helpers. If you see a code block such as: + +.. code:: python + + try: + import astropy_helpers + except ImportError: + # Building from inside the docs/ directory? + if os.path.basename(os.getcwd()) == 'docs': + a_h_path = os.path.abspath(os.path.join('..', 'astropy_helpers')) + if os.path.isdir(a_h_path): + sys.path.insert(1, a_h_path) + + # Load all of the global Astropy configuration + from astropy_helpers.sphinx.conf import * + + # Get configuration information from setup.cfg + try: + from ConfigParser import ConfigParser + except ImportError: + from configparser import ConfigParser + +you should change it to: + +.. code:: python + + try: + from sphinx_astropy.conf.v1 import * # noqa + except ImportError: + print('ERROR: the documentation requires the sphinx-astropy package to be installed') + sys.exit(1) + + # Get configuration information from setup.cfg + from configparser import ConfigParser + conf = ConfigParser() + +Find and replace any instances of ``package_name`` in the file with +``name``. + +TODO: there are probably some more changes here for older packages, +might need to really just make a new template ``conf.py`` to use. + +Step 12 - Setting up tox +------------------------ + +`tox `__ is a tool for automating +commands, which is well suited to e.g. running tests for your package or +building the documentation. One of the benefits of using tox is that it +will (by default) create a source distribution for your package and +install it into a virtual environment before running tests or building +docs, which means that it will be a good test of whether e.g. you have +declared the package data correctly. + +Given the set-up described in the previous steps, you should be able to +create a ``tox.ini`` file at the root of your package with the following +content: + +*Suggestion: add ``package_name = my_package`` and then replace +``my_package`` throughout with ``[tox]package_name`` to avoid needing to +change package name in multiple places.* + +:: + + [tox] + envlist = + py{36,37,38}-test{,-alldeps,-devdeps} + build_docs + codestyle + requires = + setuptools >= 30.3.0 + pip >= 19.3.1 + isolated_build = true + + [testenv] + passenv = + HOME + WINDIR + LC_ALL + LC_CTYPE + CC + CFLAGS + changedir = + test: .tmp/{envname} + build_docs: docs + description = + test: run tests with pytest + build_docs: invoke sphinx-build to build the HTML docs + alldeps: run tests with all optional dependencies + devdeps: run tests with numpy and astropy dev versions + deps = + astropylts: astropy==4.0rc2 + numpy116: numpy==1.16.* + numpy117: numpy==1.17.* + numpy118: numpy==1.18.* + devdeps: git+https://github.com/numpy/numpy.git#egg=numpy + devdeps: git+https://github.com/astropy/astropy.git#egg=astropy + extras = + test: test + build_docs: docs + alldeps: all + commands = + test: pytest --pyargs my_package {toxinidir}/docs {posargs} + build_docs: sphinx-build -W -b html . _build/html {posargs} + + [testenv:codestyle] + skip_install = true + description = check package code style + deps = pycodestyle + commands = pycodestyle my_package + +Replace instances of ``my_package`` with your module name. To try this +out, you should be able to do the following: + +Run tests with minimal dependencies:: + + tox -e test + +Run tests with astropy LTS and Numpy 1.16:: + + tox -e test-astropylts-numpy116 + +Run tests with all optional dependencies:: + + tox -e test-all + +Run tests with minimal dependencies and the latest developer version of +numpy and astropy:: + + tox -e test-dev + +Build the documentation:: + + tox -e build_docs + +Run code style checks on your code:: + + tox -e codestyle + +The ``{posargs}`` corresponds to arguments passed to ``tox`` after a +``--`` separator - for example to make pytest verbose in a ``test`` +environment, you can do:: + + tox -e test -- -v + +Step 13 - Updating your Continuous Integration +---------------------------------------------- + +This step will depend on what continuous integration services you use. +Broadly speaking, unless there are dependencies you need that can only +be installed with conda, you should no longer need to use ci-helpers. + +The recommended approach is to use the tox file to set up the different +configurations you want to use, and to then keep the CI configuration as +simple as possible. For example, if you wanted to set up a Travis CI +file to run the tox environments defined in Step 10, you could use a +configuration such as: + +.. code:: yaml + + language: c + + sudo: false + + env: + global: + - TOXENV='' + - TOXARGS='' + - TOXPOSARGS='' + + matrix: + + include: + + # Run the default test environment on + # all major platforms + + - os: linux + python: 3.8 + env: TOXENV='test' + + - os: osx + env: PYTHON_VERSION=3.7 TOXENV='test' + + - os: windows + env: PYTHON_VERSION=3.7 TOXENV='test' + + # Run the test-dev-all environment and pass the + # --remote-data to demonstrate passing positional + # arguments for pytest + - os: linux + python: 3.7 + env: TOXENV="test-all-dev" + TOXPOSARGS="--remote-data=astropy" + + # Build the docs + - os: linux + python: 3.7 + env: TOXENV="build_docs" + + # Run pycodestyle checks + - os: linux + python: 3.7 + env: TOXENV="pycodestyle" + + before_install: + + # We need a full clone to make sure setuptools_scm + # works properly + - git fetch --unshallow . + - git fetch --depth=1000000 + + install: + + - if [[ $TRAVIS_OS_NAME == osx || $TRAVIS_OS_NAME == windows ]]; then + git clone git://github.com/astropy/ci-helpers.git; + source ci-helpers/travis/setup_conda.sh; + fi + + - pip install tox --upgrade + + script: + - tox -e $TOXENV $TOXARGS -- $TOXPOSARGS + + after_success: + - pip install codecov + - codecov + +Note that the above shouldn’t be used as-is - it just shows how one can +configure Travis to use tox, optionally using conda via ci-helpers to +set up Python on MacOS X and Windows, but you should adapt your existing +CI configuration rather than using the above. + +Step 14 - Update ReadTheDocs configuration +------------------------------------------ + +With the set-up described in this migration guide, you should be able to +simplify the configuration for ReadTheDocs. This can be done via a +``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is +recommended). This file just needs to contain: + +.. code:: yaml + + version: 2 + + build: + image: latest + + python: + version: 3.7 + install: + - method: pip + path: . + extra_requirements: + - docs + - all + +If you don’t have the ``all`` extras_require defined, you can remove +that line. + +If you don’t need to build non-HTML formats for the docs (e.g. epub), +you can also add the following line at the end of your +``.readthedocs.yml`` file: + +.. code:: yaml + + formats: [] + +Step 15 - Final cleanup +----------------------- + +Once you’ve made the above changes, you should be able to remove the +following sections from your ``setup.cfg`` file: + +- ``[build_docs]`` +- ``[build_sphinx]`` +- ``[upload_docs]`` + +You should also add ``pip-wheel-metadata`` to your ``.gitignore`` file. + +TODO: there will likely be more things that can be removed + +Things to add: version.py file in .gitignore, coveragerc, conftest.py diff --git a/docs/index.rst b/docs/index.rst index ada6814f..0dfc7411 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,6 +63,7 @@ documentation, read the :ref:`next-steps` for further information. options nextsteps updating + ape17 Removal of Python 2 support From dce1c2c07967c15ffa30e2e8baa09cb9bbde99af Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 24 Jan 2020 16:31:38 +0000 Subject: [PATCH 08/44] More updates to migration guide --- docs/ape17.rst | 207 +++++++++++++++------- {{ cookiecutter.package_name }}/setup.cfg | 54 +++--- {{ cookiecutter.package_name }}/setup.py | 2 +- 3 files changed, 170 insertions(+), 93 deletions(-) mode change 100755 => 100644 {{ cookiecutter.package_name }}/setup.py diff --git a/docs/ape17.rst b/docs/ape17.rst index b97af244..250961bb 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -1,23 +1,25 @@ APE 17 Migration Guide ====================== +.. warning:: This guide is not yet ready for widespread use and may + still change significantly. + The Astropy project is now transitioning from using astropy-helpers for infrastructure to more standard Python packaging tools. The motivation and implications of this are discussed in an Astropy Proposal for Enhancements: `APE 17: A roadmap for package infrastructure without astropy-helpers `__ -This document is a **work in progress** and aims to provide a guide to -migrating to using the new infrastructure described in APE 17. We assume -that your package is currently using astropy-helpers and that you have -used a version of the Astropy package-template in the past to set up -your package (though this guide might still be useful if the latter is -not the case). +This page aims to provide a guide to migrating to using the new infrastructure +described in APE 17. We assume that your package is currently using +astropy-helpers and that you have used a version of the Astropy package-template +in the past to set up your package (though this guide might still be useful if +the latter is not the case). -Throughout this guide, we will assume that your package is called -``my-package`` and that the module is called ``my_package``. We -deliberately choose a name where the package name is different from the -module name, but for many cases, these will be the same. +Throughout this guide, we will assume that your package is called ``my-package`` +and that the module is called ``my_package``. We deliberately choose a name +where the package name is different from the module name, but for many cases, +these will be the same. Step 1: Remove astropy-helpers ------------------------------ @@ -81,7 +83,7 @@ If you already had a file, make sure you remove the following entries - ``tests_require`` - ``[ah_bootstrap]`` and all entries in it -Step 3 - Define Optional, test, and docs dependencies +Step 3 - Define optional, test, and docs dependencies ----------------------------------------------------- Next up, add a new section to the ``setup.cfg`` file (or modify, if it @@ -129,57 +131,85 @@ following: .. code:: python - #!/usr/bin/env python + #!/usr/bin/env python + # Licensed under a 3-clause BSD style license - see LICENSE.rst - import os - import sys - from setuptools import setup + # NOTE: The configuration for the package, including the name, version, and + # other information are set in the setup.cfg file. - TEST_HELP = """ - Note: running tests is no longer done using 'python setup.py test'. Instead - you will need to run: + import os + import sys - tox -e test + from setuptools import setup + from extension_helpers import get_extensions - If you don't already have tox installed, you can install it with: + # First provide helpful messages if contributors try and run legacy commands + # for tests or docs. - pip install tox + TEST_HELP = """ + Note: running tests is no longer done using 'python setup.py test'. Instead + you will need to run: - If you only want to run part of the test suite, you can also use pytest - directly with:: + tox -e test - pip install -e . - pytest + If you don't already have tox installed, you can install it with: - For more information, see: + pip install tox - http://docs.astropy.org/en/latest/development/testguide.html#running-tests - """ + If you only want to run part of the test suite, you can also use pytest + directly with:: - if 'test' in sys.argv: - print(TEST_HELP) - sys.exit(1) + pip install -e .[test] + pytest - DOCS_HELP = """ - Note: building the documentation is no longer done using - 'python setup.py build_docs'. Instead you will need to run: + For more information, see: - tox -e build_docs + http://docs.astropy.org/en/latest/development/testguide.html#running-tests + """ - If you don't already have tox installed, you can install it with: + if 'test' in sys.argv: + print(TEST_HELP) + sys.exit(1) - pip install tox + DOCS_HELP = """ + Note: building the documentation is no longer done using + 'python setup.py build_docs'. Instead you will need to run: - For more information, see: + tox -e build_docs - http://docs.astropy.org/en/latest/install.html#builddocs - """ + If you don't already have tox installed, you can install it with: - if 'build_docs' in sys.argv or 'build_sphinx' in sys.argv: - print(DOCS_HELP) - sys.exit(1) + pip install tox - setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}) + You can also build the documentation with Sphinx directly using:: + + pip install -e .[docs] + cd docs + make html + + For more information, see: + + http://docs.astropy.org/en/latest/install.html#builddocs + """ + + if 'build_docs' in sys.argv or 'build_sphinx' in sys.argv: + print(DOCS_HELP) + sys.exit(1) + + VERSION_TEMPLATE = """ + # Note that we need to fall back to the hard-coded version if either + # setuptools_scm can't be imported or setuptools_scm can't determine the + # version, so we catch the generic 'Exception'. + try: + from setuptools_scm import get_version + version = get_version(root='..', relative_to=__file__) + except Exception: + version = '{version}' + """.lstrip() + + setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), + 'write_to_template': VERSION_TEMPLATE}, + ext_modules=get_extensions()) Step 6: add a ``pyproject.toml`` file ------------------------------------- @@ -365,7 +395,8 @@ Step 10 - Update ``MANIFEST.in`` -------------------------------- Edit your ``MANIFEST.in`` file to remove the following lines, if present -(and any other line related to ``astropy_helpers``):: +(and any other line related to ``astropy_helpers``) - those lines might +include any of the following:: include ez_setup.py include ah_bootstrap.py @@ -437,9 +468,6 @@ you should change it to: Find and replace any instances of ``package_name`` in the file with ``name``. -TODO: there are probably some more changes here for older packages, -might need to really just make a new template ``conf.py`` to use. - Step 12 - Setting up tox ------------------------ @@ -453,13 +481,7 @@ declared the package data correctly. Given the set-up described in the previous steps, you should be able to create a ``tox.ini`` file at the root of your package with the following -content: - -*Suggestion: add ``package_name = my_package`` and then replace -``my_package`` throughout with ``[tox]package_name`` to avoid needing to -change package name in multiple places.* - -:: +content:: [tox] envlist = @@ -470,6 +492,7 @@ change package name in multiple places.* setuptools >= 30.3.0 pip >= 19.3.1 isolated_build = true + module_name = my_package [testenv] passenv = @@ -499,17 +522,17 @@ change package name in multiple places.* build_docs: docs alldeps: all commands = - test: pytest --pyargs my_package {toxinidir}/docs {posargs} + test: pytest --pyargs {[tox]module_name} {toxinidir}/docs --cov {[tox]module_name} --cov-config {toxinidir}/setup.cfg {posargs} build_docs: sphinx-build -W -b html . _build/html {posargs} [testenv:codestyle] skip_install = true description = check package code style deps = pycodestyle - commands = pycodestyle my_package + commands = pycodestyle {[tox]module_name} -Replace instances of ``my_package`` with your module name. To try this -out, you should be able to do the following: +Edit the ``module_name`` line in the ``[tox]`` section to specify your module +name. Once you have done this you should be able to do the following: Run tests with minimal dependencies:: @@ -521,12 +544,12 @@ Run tests with astropy LTS and Numpy 1.16:: Run tests with all optional dependencies:: - tox -e test-all + tox -e test-alldeps Run tests with minimal dependencies and the latest developer version of numpy and astropy:: - tox -e test-dev + tox -e test-devdeps Build the documentation:: @@ -665,7 +688,61 @@ you can also add the following line at the end of your formats: [] -Step 15 - Final cleanup +Step 15 - Coverage configuration +-------------------------------- + +Preivously, astropy-helpers expected the coverage configuration to +be located in ``my_package/tests/coveragerc``. This is now no longer +necessary, so you can now define the coverage configuration inside +the ``setup.cfg`` file, which should help reduce the number of files +to keep track of. Add the following to the bottom of your ``setup.cfg``:: + + [coverage:run] + omit = + my_package/_{{ cookiecutter._parent_project }}_init* + my_package/conftest.py + my_package/*setup_package* + my_package/tests/* + my_package/*/tests/* + my_package/extern/* + my_package/version* + */my_package/_{{ cookiecutter._parent_project }}_init* + */my_package/conftest.py + */my_package/*setup_package* + */my_package/tests/* + */my_package/*/tests/* + */my_package/extern/* + */my_package/version* + + [coverage:report] + exclude_lines = + # Have to re-enable the standard pragma + pragma: no cover + # Don't complain about packages we have installed + except ImportError + # Don't complain if tests don't hit assertions + raise AssertionError + raise NotImplementedError + # Don't complain about script hooks + def main\(.*\): + # Ignore branches that don't pertain to this version of Python + pragma: py{ignore_python_version} + # Don't complain about IPython completion helper + def _ipython_key_completions_ + +Make sure to replace ``my_package`` by your module name. If you had any +customizations in ``coveragerc`` you can include them here, but otherwise the +above should be sufficient. + +Step 16 - conftest.py file updates +---------------------------------- + +For the header in your test runs to be correct with the latest versions of +astropy, you will need to make sure that you update your ``conftest.py`` +file as described in the `pytest-astropy-header instructions +`_. + +Step 17 - Final cleanup ----------------------- Once you’ve made the above changes, you should be able to remove the @@ -677,6 +754,6 @@ following sections from your ``setup.cfg`` file: You should also add ``pip-wheel-metadata`` to your ``.gitignore`` file. -TODO: there will likely be more things that can be removed - -Things to add: version.py file in .gitignore, coveragerc, conftest.py +**Once you are done, if you would like us to help by reviewing your changes, +you can open a pull request to your package and mention @astrofrog or +@Cadair to ask for a review** diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index e79f44ac..2ebf6820 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -42,33 +42,33 @@ addopts = --doctest-rst [coverage:run] omit = - {packagename}/_{{ cookiecutter._parent_project }}_init* - {packagename}/conftest.py - {packagename}/*setup_package* - {packagename}/tests/* - {packagename}/*/tests/* - {packagename}/extern/* - {packagename}/version* - */{packagename}/_{{ cookiecutter._parent_project }}_init* - */{packagename}/conftest.py - */{packagename}/*setup_package* - */{packagename}/tests/* - */{packagename}/*/tests/* - */{packagename}/extern/* - */{packagename}/version* + {{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init* + {{ cookiecutter.module_name }}/conftest.py + {{ cookiecutter.module_name }}/*setup_package* + {{ cookiecutter.module_name }}/tests/* + {{ cookiecutter.module_name }}/*/tests/* + {{ cookiecutter.module_name }}/extern/* + {{ cookiecutter.module_name }}/version* + */{{ cookiecutter.module_name }}/_{{ cookiecutter._parent_project }}_init* + */{{ cookiecutter.module_name }}/conftest.py + */{{ cookiecutter.module_name }}/*setup_package* + */{{ cookiecutter.module_name }}/tests/* + */{{ cookiecutter.module_name }}/*/tests/* + */{{ cookiecutter.module_name }}/extern/* + */{{ cookiecutter.module_name }}/version* [coverage:report] exclude_lines = - # Have to re-enable the standard pragma - pragma: no cover - # Don't complain about packages we have installed - except ImportError - # Don't complain if tests don't hit assertions - raise AssertionError - raise NotImplementedError - # Don't complain about script hooks - def main\(.*\): - # Ignore branches that don't pertain to this version of Python - pragma: py{ignore_python_version} - # Don't complain about IPython completion helper - def _ipython_key_completions_ + # Have to re-enable the standard pragma + pragma: no cover + # Don't complain about packages we have installed + except ImportError + # Don't complain if tests don't hit assertions + raise AssertionError + raise NotImplementedError + # Don't complain about script hooks + def main\(.*\): + # Ignore branches that don't pertain to this version of Python + pragma: py{ignore_python_version} + # Don't complain about IPython completion helper + def _ipython_key_completions_ diff --git a/{{ cookiecutter.package_name }}/setup.py b/{{ cookiecutter.package_name }}/setup.py old mode 100755 new mode 100644 index 34478612..65e30eaf --- a/{{ cookiecutter.package_name }}/setup.py +++ b/{{ cookiecutter.package_name }}/setup.py @@ -77,7 +77,7 @@ version = '{version}' """.lstrip() -{% if cookiecutter.include_example_code == 'y' %} +{% if cookiecutter.use_compiled_extensions == 'y' %} setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), 'write_to_template': VERSION_TEMPLATE}, ext_modules=get_extensions()) From 343087999f1abb29f7a4c698080806760e440a93 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 24 Jan 2020 16:54:06 +0000 Subject: [PATCH 09/44] More cleanup --- cookiecutter.json | 8 ++------ hooks/post_gen_project.py | 5 +---- {{ cookiecutter.package_name }}/README.rst | 2 -- .../docs/_templates/autosummary/base.rst | 2 -- .../docs/_templates/autosummary/class.rst | 2 -- .../docs/_templates/autosummary/module.rst | 2 -- {{ cookiecutter.package_name }}/docs/index.rst | 1 - .../{{ cookiecutter.module_name }}/example_mod.py | 2 +- .../{{ cookiecutter.module_name }}/tests/test_example.py | 2 +- 9 files changed, 5 insertions(+), 21 deletions(-) delete mode 100644 {{ cookiecutter.package_name }}/docs/_templates/autosummary/base.rst delete mode 100644 {{ cookiecutter.package_name }}/docs/_templates/autosummary/class.rst delete mode 100644 {{ cookiecutter.package_name }}/docs/_templates/autosummary/module.rst diff --git a/cookiecutter.json b/cookiecutter.json index d2dbbc24..f2f60238 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -8,9 +8,9 @@ "license": ["BSD 3-Clause", "GNU GPL v3+", "Apache Software Licence 2.0", "BSD 2-Clause", "Other"], "project_url": "http://docs.astropy.org/projects/package-template/", "project_version": "0.0.dev", - "include_example_code": "y", - "include_example_cython_code": "n", "include_cextern_folder": "n", + "use_compiled_extensions": "y", + "include_example_code": "n", "edit_on_github_extension": "False", "github_project": "astropy/astropy", "use_travis_ci": "y", @@ -19,9 +19,5 @@ "initialize_git_repo": "y", "_parent_project": "astropy", "_install_requires": "astropy", - "_copy_without_render": [ - "docs/_templates" - ], "minimum_python_version": ["3.7", "3.6", "3.5"], - "astropy_helpers_version": "v3.2.1" } diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index f25caf1d..6bd9322f 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -47,15 +47,12 @@ def process_licence(licence_name): remove_file('.rtd-environment.yml') remove_file('readthedocs.yml') - if '{{ cookiecutter.include_cextern_folder }}' != 'y': - remove_dir("cextern") - if '{{ cookiecutter.include_example_code }}' != 'y': remove_dir('{{ cookiecutter.module_name }}/example_subpkg/') remove_file('{{ cookiecutter.module_name }}/example_mod.py') remove_file('{{ cookiecutter.module_name }}/tests/test_example.py') - if '{{ cookiecutter.include_example_cython_code }}' != 'y': + if '{{ cookiecutter.use_compiled_extensions }}' != 'y' or '{{ cookiecutter.include_example_code }}' != 'y': remove_file('{{ cookiecutter.module_name }}/example_c.pyx') if '{{ cookiecutter.initialize_git_repo }}' == 'y': diff --git a/{{ cookiecutter.package_name }}/README.rst b/{{ cookiecutter.package_name }}/README.rst index 36c09c86..ade8df96 100644 --- a/{{ cookiecutter.package_name }}/README.rst +++ b/{{ cookiecutter.package_name }}/README.rst @@ -5,8 +5,6 @@ :target: http://www.astropy.org :alt: Powered by Astropy Badge -{{ cookiecutter.long_description|wordwrap(break_long_words=False) }} - License ------- diff --git a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/base.rst b/{{ cookiecutter.package_name }}/docs/_templates/autosummary/base.rst deleted file mode 100644 index 9cabaf52..00000000 --- a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/base.rst +++ /dev/null @@ -1,2 +0,0 @@ -{% extends "autosummary_core/base.rst" %} -{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/class.rst b/{{ cookiecutter.package_name }}/docs/_templates/autosummary/class.rst deleted file mode 100644 index 6b214a5c..00000000 --- a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/class.rst +++ /dev/null @@ -1,2 +0,0 @@ -{% extends "autosummary_core/class.rst" %} -{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/module.rst b/{{ cookiecutter.package_name }}/docs/_templates/autosummary/module.rst deleted file mode 100644 index f38315b2..00000000 --- a/{{ cookiecutter.package_name }}/docs/_templates/autosummary/module.rst +++ /dev/null @@ -1,2 +0,0 @@ -{% extends "autosummary_core/module.rst" %} -{# The template this is inherited from is in astropy/sphinx/ext/templates/autosummary_core. If you want to modify this template, it is strongly recommended that you still inherit from the astropy template. #} \ No newline at end of file diff --git a/{{ cookiecutter.package_name }}/docs/index.rst b/{{ cookiecutter.package_name }}/docs/index.rst index ccaed6a4..9cbaa3a6 100644 --- a/{{ cookiecutter.package_name }}/docs/index.rst +++ b/{{ cookiecutter.package_name }}/docs/index.rst @@ -2,7 +2,6 @@ Documentation ============= This is the documentation for {{ cookiecutter.package_name }}. -{{ cookiecutter.long_description|wordwrap(break_long_words=False) }} .. toctree:: :maxdepth: 2 diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/example_mod.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/example_mod.py index 730ca83c..d5f3f1cd 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/example_mod.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/example_mod.py @@ -41,7 +41,7 @@ def primes(imax): def do_primes(n, usecython=False): if usecython: -{% if cookiecutter.include_example_cython_code != 'y' %} +{% if cookiecutter.use_compiled_extensions != 'y' %} raise Exception("This template does not have the example C code included.") {% else %} from .example_c import primes as cprimes diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/test_example.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/test_example.py index cce7bd7c..446761f3 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/test_example.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/tests/test_example.py @@ -1,4 +1,4 @@ -{% if cookiecutter.include_example_cython_code == 'y' %} +{% if cookiecutter.use_compiled_extensions == 'y' %} def test_primes_c(): from ..example_c import primes as primes_c assert primes_c(10) == [2, 3, 5, 7, 11, 13, 17, 19, 23, 29] From 2c3659c3982b6f8d2baf3bb21ebd8645ba8bbc5e Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 15:38:15 +0000 Subject: [PATCH 10/44] Remove .rtd-environment.yml file --- .../.rtd-environment.yml | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 {{ cookiecutter.package_name }}/.rtd-environment.yml diff --git a/{{ cookiecutter.package_name }}/.rtd-environment.yml b/{{ cookiecutter.package_name }}/.rtd-environment.yml deleted file mode 100644 index b046d9de..00000000 --- a/{{ cookiecutter.package_name }}/.rtd-environment.yml +++ /dev/null @@ -1,14 +0,0 @@ -name: {{ cookiecutter.module_name }} - -channels: - - astropy - -dependencies: - - python>={{ cookiecutter.minimum_python_version }} - - astropy - - Cython - - matplotlib - - numpy - - sphinx-astropy -# - pip: -# - dependency_from_pip From e2658567565187b3c1e5bedbc3316784da60bfb0 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 15:38:33 +0000 Subject: [PATCH 11/44] Fix syntax in cookiecutter.json and change default back for include_example_code --- cookiecutter.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookiecutter.json b/cookiecutter.json index f2f60238..b0450378 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -10,7 +10,7 @@ "project_version": "0.0.dev", "include_cextern_folder": "n", "use_compiled_extensions": "y", - "include_example_code": "n", + "include_example_code": "y", "edit_on_github_extension": "False", "github_project": "astropy/astropy", "use_travis_ci": "y", @@ -19,5 +19,5 @@ "initialize_git_repo": "y", "_parent_project": "astropy", "_install_requires": "astropy", - "minimum_python_version": ["3.7", "3.6", "3.5"], + "minimum_python_version": ["3.7", "3.6", "3.5"] } From 4c00c239362a546797923e9119de741a5ad83b83 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 15:49:18 +0000 Subject: [PATCH 12/44] Remove questions that are no longer needed --- QUESTIONS.rst | 27 +++++++++++++-------------- cookiecutter.json | 2 -- docs/options.rst | 5 +---- rendered.yml | 3 +-- 4 files changed, 15 insertions(+), 22 deletions(-) diff --git a/QUESTIONS.rst b/QUESTIONS.rst index c3019d81..04759f8f 100644 --- a/QUESTIONS.rst +++ b/QUESTIONS.rst @@ -5,20 +5,19 @@ To use the package template run ``cookiecutter gh:astropy/package-template``, once you have run this command you will be asked a series of questions. Below is a description of each of the prompts. -1. ``package_name``: This is a human readable name for your package, like 'Astropy' or 'SunPy'. -2. ``module_name``: This is the name of your python package i.e. 'astropy' or 'sunpy'. +1. ``package_name``: This is a human readable name for your package, like ``Astropy`` or ``SunPy``. +2. ``module_name``: This is the name of your python package i.e. ``astropy`` or ``sunpy``. 3. ``short_description``: This is a one sentence description of your package. -4. ``long_description``: This is a multi-line description of your package. -5. ``author_name``: The name or names of the authors. -6. ``author_email``: A contact email for the authors. -7. ``license``: The license of your project. -8. ``project_url``: Project website. -9. ``include_example_code``: This includes a set of example python and cython files showing you how to use the package template. If you choose 'n' then none of this will be included and you will have to populate the directory structure before you can import the package. +4. ``author_name``: The name or names of the authors. +5. ``author_email``: A contact email for the authors. +6. ``license``: The license of your package. +7. ``project_url``: Project website. +8. ``include_example_code``: This includes a set of example python files showing you how to use the package template. If you choose ``n`` then none of this will be included and you will have to populate the directory structure before you can import the package. +9. ``use_compiled_extensions``: Whether you plan to use compiled extensions in your package 10. ``include_cextern_folder``: The cextern folder should be used if you are including non-python C code. -11. ``edit_on_github_extension``: Set to "True" to enable the edit on GitHub sphinx extension. +11. ``edit_on_github_extension``: Set to ``True`` to enable the edit on GitHub sphinx extension. 12. ``github_project``: This is the GitHub identifier for the edit on GitHub extension and the changelog link extension. -13. ``project_version``: The current version number of your project. -14. ``use_travis_ci``: If 'y' the template will include an example ``.travis.yml`` file for the Travis CI service. -15. ``use_read_the_docs``: If 'y' the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. -16. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. -17. ``minimum_python_version``: Version string of minimum supported Python version +13. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. +14. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. +15. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. +16. ``initialize_git_repo``: If `gitpython `_ is installed this option will turn the rendered package into a git repository and add and initilize the ``astropy_helpers`` submodule. diff --git a/cookiecutter.json b/cookiecutter.json index b0450378..8b7ffcd5 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -2,12 +2,10 @@ "package_name": "packagename", "module_name": "{{ cookiecutter.package_name|lower()|replace(' ', '_') }}", "short_description": "{{ cookiecutter.package_name|replace('-', ' ')|replace('_', ' ') }}", - "long_description": "", "author_name": "Astropy Developers", "author_email": "", "license": ["BSD 3-Clause", "GNU GPL v3+", "Apache Software Licence 2.0", "BSD 2-Clause", "Other"], "project_url": "http://docs.astropy.org/projects/package-template/", - "project_version": "0.0.dev", "include_cextern_folder": "n", "use_compiled_extensions": "y", "include_example_code": "y", diff --git a/docs/options.rst b/docs/options.rst index 02a3ab96..36f93f74 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -10,14 +10,12 @@ a description of each of the prompts: #. ``package_name``: This is a human readable name for your package, like ``Astropy`` or ``SunPy``. #. ``module_name``: This is the name of your python package i.e. ``astropy`` or ``sunpy``. #. ``short_description``: This is a one sentence description of your package. -#. ``long_description``: This is a multi-line description of your package. #. ``author_name``: The name or names of the authors. #. ``author_email``: A contact email for the authors. #. ``license``: The license of your package. #. ``project_url``: Project website. -#. ``project_version``: The version number for the package. #. ``include_example_code``: This includes a set of example python files showing you how to use the package template. If you choose ``n`` then none of this will be included and you will have to populate the directory structure before you can import the package. -#. ``include_example_cython_code``: This includes a set of example Cython code, which demonstrates how to add compiled code to the package. +#. ``use_compiled_extensions``: Whether you plan to use compiled extensions in your package #. ``include_cextern_folder``: The cextern folder should be used if you are including non-python C code. #. ``edit_on_github_extension``: Set to ``True`` to enable the edit on GitHub sphinx extension. #. ``github_project``: This is the GitHub identifier for the edit on GitHub extension and the changelog link extension. @@ -25,7 +23,6 @@ a description of each of the prompts: #. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. #. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. #. ``initialize_git_repo``: If `gitpython `_ is installed this option will turn the rendered package into a git repository and add and initilize the ``astropy_helpers`` submodule. -#. ``astropy_helpers_version``: The version number of the ``astropy_helpers`` submodule to be used, only used if ``initialize_git_repo`` is true. Once the project has been set up, any of the values can still be `manually updated `_. diff --git a/rendered.yml b/rendered.yml index 51ebdc63..eaf5d2dc 100644 --- a/rendered.yml +++ b/rendered.yml @@ -2,14 +2,13 @@ default_context: package_name: "packagename" module_name: "packagename" short_description: "Astropy Package Template" - long_description: "This is a rendered version of the cookiecutter Astropy package template, which you can find `here `_. You can also read the `documentation `_ for more details." author_name: "Astropy Developers" author_email: "" license: "BSD 3-Clause" project_url: "http://docs.astropy.org/projects/package-template/" project_version: "0.0.dev" include_example_code: "y" - include_example_cython_code: "y" + use_compiled_extensions: "y" include_cextern_folder: "y" edit_on_github_extension: "False" github_project: "astropy/astropy" From 77a2ad6a6df7b34b1d869018ba1f04dda6ef2c8b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 15:57:09 +0000 Subject: [PATCH 13/44] More updates to migration guide --- docs/ape17.rst | 18 ++++++++++++++++++ docs/index.rst | 2 +- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 250961bb..547464e2 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -21,6 +21,20 @@ and that the module is called ``my_package``. We deliberately choose a name where the package name is different from the module name, but for many cases, these will be the same. +Step 0: Re-rendering the template (optional) +-------------------------------------------- + +In this guide, we will descibe the changes to make to the files in your package. +However, you may not currently have the latest version of all files from the +template, so this is also a good chance to make sure you are completely up to +date by re-rendering the cookiecutter template to a new folder:: + + cookiecutter gh:astropy/package-template -o my_package_tmp + +As you progress through this guide, you can then - if you wish - copy over the +newest version of the file, taking care to edit it if needed to match any +desired customizations you had previously. + Step 1: Remove astropy-helpers ------------------------------ @@ -688,6 +702,10 @@ you can also add the following line at the end of your formats: [] +With this updated file, you should now be able to remove any pip +requirements file or conda yml file that were previously used by +``readthedocs.yml``. + Step 15 - Coverage configuration -------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 0dfc7411..794e7c88 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,7 +57,7 @@ For further customization of your package including setting up testing and documentation, read the :ref:`next-steps` for further information. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: options From bac13750f866b9ca161564b8378ddf469ab00dbf Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 16:06:07 +0000 Subject: [PATCH 14/44] Added changelog entry --- TEMPLATE_CHANGES.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/TEMPLATE_CHANGES.md b/TEMPLATE_CHANGES.md index 8764f0f0..b46cec66 100644 --- a/TEMPLATE_CHANGES.md +++ b/TEMPLATE_CHANGES.md @@ -15,6 +15,9 @@ be copied over manually if desired. - Removed Appveyor CI option. Use ``os: windows`` in Travis CI. [#420] +- Refactored the template to follow the recommendations in APE 17: + https://github.com/astropy/astropy-APEs/blob/master/APE17.rst [#438] + 2.1 (unreleased) ---------------- From 38a4a950054e3392416f0011f169a0d265d44503 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 16:11:10 +0000 Subject: [PATCH 15/44] Enable cron again --- {{ cookiecutter.package_name }}/.travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{ cookiecutter.package_name }}/.travis.yml b/{{ cookiecutter.package_name }}/.travis.yml index db6eb75c..0108512e 100644 --- a/{{ cookiecutter.package_name }}/.travis.yml +++ b/{{ cookiecutter.package_name }}/.travis.yml @@ -25,7 +25,7 @@ stages: - name: Comprehensive tests # These will only run when cron is opted in - name: Cron tests - # if: type = cron + if: type = cron env: From 33574f14b52c4933b7b8685c76db4b9614e562af Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 16:50:28 +0000 Subject: [PATCH 16/44] Simplified migration guide to avoid duplication with template --- docs/ape17.rst | 376 ++++-------------- .../.readthedocs.yml | 20 +- 2 files changed, 83 insertions(+), 313 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 547464e2..87b672a5 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -21,8 +21,8 @@ and that the module is called ``my_package``. We deliberately choose a name where the package name is different from the module name, but for many cases, these will be the same. -Step 0: Re-rendering the template (optional) --------------------------------------------- +Step 0: Re-rendering the template +--------------------------------- In this guide, we will descibe the changes to make to the files in your package. However, you may not currently have the latest version of all files from the @@ -33,7 +33,8 @@ date by re-rendering the cookiecutter template to a new folder:: As you progress through this guide, you can then - if you wish - copy over the newest version of the file, taking care to edit it if needed to match any -desired customizations you had previously. +desired customizations you had previously. This will also be useful for any new +files which you can then just copy from the rendered template. Step 1: Remove astropy-helpers ------------------------------ @@ -139,103 +140,23 @@ included as well as all files inside ``my_package/tests/data``. Step 5 - Update your ``setup.py`` file -------------------------------------- -If you don’t have any compiled (e.g. C or Cython) extensions in your -package, you can replace your existing ``setup.py`` file with the -following: - -.. code:: python - - #!/usr/bin/env python - # Licensed under a 3-clause BSD style license - see LICENSE.rst - - # NOTE: The configuration for the package, including the name, version, and - # other information are set in the setup.cfg file. - - import os - import sys - - from setuptools import setup - from extension_helpers import get_extensions - - # First provide helpful messages if contributors try and run legacy commands - # for tests or docs. - - TEST_HELP = """ - Note: running tests is no longer done using 'python setup.py test'. Instead - you will need to run: - - tox -e test - - If you don't already have tox installed, you can install it with: - - pip install tox - - If you only want to run part of the test suite, you can also use pytest - directly with:: - - pip install -e .[test] - pytest - - For more information, see: - - http://docs.astropy.org/en/latest/development/testguide.html#running-tests - """ - - if 'test' in sys.argv: - print(TEST_HELP) - sys.exit(1) - - DOCS_HELP = """ - Note: building the documentation is no longer done using - 'python setup.py build_docs'. Instead you will need to run: - - tox -e build_docs - - If you don't already have tox installed, you can install it with: - - pip install tox - - You can also build the documentation with Sphinx directly using:: - - pip install -e .[docs] - cd docs - make html - - For more information, see: - - http://docs.astropy.org/en/latest/install.html#builddocs - """ - - if 'build_docs' in sys.argv or 'build_sphinx' in sys.argv: - print(DOCS_HELP) - sys.exit(1) - - VERSION_TEMPLATE = """ - # Note that we need to fall back to the hard-coded version if either - # setuptools_scm can't be imported or setuptools_scm can't determine the - # version, so we catch the generic 'Exception'. - try: - from setuptools_scm import get_version - version = get_version(root='..', relative_to=__file__) - except Exception: - version = '{version}' - """.lstrip() - - setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), - 'write_to_template': VERSION_TEMPLATE}, - ext_modules=get_extensions()) +Copy the ``setup.py`` file you generated in Step 0 and replace your existing one +- it should be good to go as-is without any further customizations. Step 6: add a ``pyproject.toml`` file ------------------------------------- -The ``pyproject.toml`` file is used to declare dependencies needed to -run ``setup.py`` and build the package. If your package doesn’t have any -compiled extensions, the file should contain: +The ``pyproject.toml`` file is used to declare dependencies needed to run +``setup.py`` and build the package. Copy the ``pyproject.toml`` file you +generated in Step 0 and replace your existing one. + +If your package doesn’t have any compiled extensions, the file should contain: .. code:: toml [build-system] requires = ["setuptools", + "setuptools_scm", "wheel"] build-backend = 'setuptools.build_meta' @@ -254,7 +175,8 @@ Step 7a - Defining extensions manually You can define extensions manually as described `here `__. If you do this, you can remove all ``setup_package.py`` files in your -package. +package, and you don't need to include extension-helpers in the +``pyproject.toml`` file. If you have Cython extensions or your extensions use the NumPy C API, proceed to Step 7c, otherwise you can proceed to Step 8. @@ -275,7 +197,9 @@ each should return a list of extensions. Check through your existing ``setup_package.py`` files (if any), and make sure that any ``astropy_helpers`` imports are changed to ``extension_helpers``. -Next, add: +Provided you indicated when you generated the template that you wanted to +use compiled extensions, you should be good to go. If not, make sure +you add: .. code:: python @@ -288,18 +212,8 @@ just under the following lines at the top of the ``setup.py`` file: import sys from setuptools import setup -In addition, in the same file, change: - -.. code:: python - - setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}) - -to - -.. code:: python - - setup(use_scm_version={'write_to': os.path.join('my_package', 'version.py')}, - ext_modules=get_extensions()) +In addition, in the same file, add ``ext_modules=get_extensions()`` to the +call to ``setup.py``. If you have Cython extensions or your extensions use the NumPy C API, proceed to Step 7c, otherwise you can proceed to Step 8. @@ -312,31 +226,28 @@ declare Numpy as a build-time dependency in ``pyproject.toml``. Note that as described in `APE 17 `__, you need to pin the build-time Numpy dependency to the **oldest** -supported Numpy version for each Python version. However, rather than -doing this manually, you can add the ``oldest-supported-numpy`` package -to your ``pyproject.toml`` file: - -.. code:: toml - - [build-system] - requires = ["setuptools", - "wheel", - "oldest-supported-numpy"] - build-backend = 'setuptools.build_meta' - -If you have Cython extensions, you will need to also add an entry for -Cython, pinning it to a recent version: +supported Numpy version for each Python version. However, rather than doing this +manually, you can add the ``oldest-supported-numpy`` package to the build +dependencies in your ``pyproject.toml`` file. In addition if you have Cython +extensions, you will need to also add an entry for Cython, pinning it to a +recent version. Provided you indicated when you generated the template in Step 0 +that you wanted to use compiled extensions, you should be good to go as both +``oldest-supported-numpy`` and ``cython`` should be in the ``pyproject.toml`` +file. In this case your ``pyproject.toml`` file will look like: .. code:: toml [build-system] requires = ["setuptools", + "setuptools_scm", "wheel", + "extension-helpers", + "oldest-supported-numpy", "cython==0.29.14"] build-backend = 'setuptools.build_meta' Whenever a new major Python version is released, you will likely need to -update this pinning to use the most recent Cython version available. +update the Cython pinning to use the most recent Cython version available. Step 8 - Using setuptools_scm ----------------------------- @@ -344,32 +255,29 @@ Step 8 - Using setuptools_scm The `setuptools_scm `__ package is now recommended to manage the version numbers for your package. The way this works is that instead of setting the version -number manually in e.g. \ ``setup.cfg`` or elsewhere in your package, +number manually in e.g. ``setup.cfg`` or elsewhere in your package, the version number is based on git tags. -First, define ``setup_requires`` inside the ``[options]`` section of -your ``setup.cfg`` file:: +In Steps 5 and 6, we already added the required entry for +setuptools_scm to ``setup.py`` and ``pyproject.toml``. + +In addition to these, we recommend that you define ``setup_requires`` inside the +``[options]`` section of your ``setup.cfg`` file:: [options] ... setup_requires = setuptools_scm ... -Next, add ``setuptools_scm`` as a build-time dependency in the -``requires`` list of your ``pyproject.toml`` file: +This is not strictly necessary but will make it possible for ``python setup.py --version`` +to work without having to install ``setuptools_scm`` manually. -.. code:: toml - - [build-system] - requires = ["setuptools", - "setuptools_scm", - ... - -Check your ``.gitignore`` and make sure that you have a line containing:: +Next, check your ``.gitignore`` and make sure that you have a line containing:: my_package/version.py -Finally, edit your ``my_package/_astropy_init.py`` file and remove the +Finally, copy over the ``_astropy_init.py`` file generated in Step 0, or +alternatively edit your ``my_package/_astropy_init.py`` file and remove the following lines: .. code:: python @@ -380,9 +288,7 @@ following lines: __githash__ = '' and remove ``'__githash__'`` from the ``__all__`` list at the top of the -file. - -The git hash is now contained in the version number, so this is no +file. The git hash is now contained in the version number, so this is no longer needed. Step 9 - Configuring pytest @@ -493,60 +399,11 @@ install it into a virtual environment before running tests or building docs, which means that it will be a good test of whether e.g. you have declared the package data correctly. -Given the set-up described in the previous steps, you should be able to -create a ``tox.ini`` file at the root of your package with the following -content:: - - [tox] - envlist = - py{36,37,38}-test{,-alldeps,-devdeps} - build_docs - codestyle - requires = - setuptools >= 30.3.0 - pip >= 19.3.1 - isolated_build = true - module_name = my_package - - [testenv] - passenv = - HOME - WINDIR - LC_ALL - LC_CTYPE - CC - CFLAGS - changedir = - test: .tmp/{envname} - build_docs: docs - description = - test: run tests with pytest - build_docs: invoke sphinx-build to build the HTML docs - alldeps: run tests with all optional dependencies - devdeps: run tests with numpy and astropy dev versions - deps = - astropylts: astropy==4.0rc2 - numpy116: numpy==1.16.* - numpy117: numpy==1.17.* - numpy118: numpy==1.18.* - devdeps: git+https://github.com/numpy/numpy.git#egg=numpy - devdeps: git+https://github.com/astropy/astropy.git#egg=astropy - extras = - test: test - build_docs: docs - alldeps: all - commands = - test: pytest --pyargs {[tox]module_name} {toxinidir}/docs --cov {[tox]module_name} --cov-config {toxinidir}/setup.cfg {posargs} - build_docs: sphinx-build -W -b html . _build/html {posargs} - - [testenv:codestyle] - skip_install = true - description = check package code style - deps = pycodestyle - commands = pycodestyle {[tox]module_name} - -Edit the ``module_name`` line in the ``[tox]`` section to specify your module -name. Once you have done this you should be able to do the following: +As a starting point, copy over the ``tox.ini`` file generated in Step 0. +You can always then customize it if needed (although it should work out +of the box). + +Once you have done this you should be able to do the following: Run tests with minimal dependencies:: @@ -582,129 +439,28 @@ environment, you can do:: Step 13 - Updating your Continuous Integration ---------------------------------------------- -This step will depend on what continuous integration services you use. -Broadly speaking, unless there are dependencies you need that can only -be installed with conda, you should no longer need to use ci-helpers. - -The recommended approach is to use the tox file to set up the different -configurations you want to use, and to then keep the CI configuration as -simple as possible. For example, if you wanted to set up a Travis CI -file to run the tox environments defined in Step 10, you could use a -configuration such as: - -.. code:: yaml - - language: c - - sudo: false - - env: - global: - - TOXENV='' - - TOXARGS='' - - TOXPOSARGS='' - - matrix: - - include: - - # Run the default test environment on - # all major platforms - - - os: linux - python: 3.8 - env: TOXENV='test' +This step will depend on what continuous integration services you use. Broadly +speaking, unless there are dependencies you need that can only be installed with +conda, you should no longer need to use ci-helpers to install these. The +recommended approach is to use the tox file to set up the different +configurations you want to use, and to then keep the CI configuration as simple +as possible. - - os: osx - env: PYTHON_VERSION=3.7 TOXENV='test' - - - os: windows - env: PYTHON_VERSION=3.7 TOXENV='test' - - # Run the test-dev-all environment and pass the - # --remote-data to demonstrate passing positional - # arguments for pytest - - os: linux - python: 3.7 - env: TOXENV="test-all-dev" - TOXPOSARGS="--remote-data=astropy" - - # Build the docs - - os: linux - python: 3.7 - env: TOXENV="build_docs" - - # Run pycodestyle checks - - os: linux - python: 3.7 - env: TOXENV="pycodestyle" - - before_install: - - # We need a full clone to make sure setuptools_scm - # works properly - - git fetch --unshallow . - - git fetch --depth=1000000 - - install: - - - if [[ $TRAVIS_OS_NAME == osx || $TRAVIS_OS_NAME == windows ]]; then - git clone git://github.com/astropy/ci-helpers.git; - source ci-helpers/travis/setup_conda.sh; - fi - - - pip install tox --upgrade - - script: - - tox -e $TOXENV $TOXARGS -- $TOXPOSARGS - - after_success: - - pip install codecov - - codecov - -Note that the above shouldn’t be used as-is - it just shows how one can -configure Travis to use tox, optionally using conda via ci-helpers to -set up Python on MacOS X and Windows, but you should adapt your existing -CI configuration rather than using the above. +If you use Travis CI, a good place to start is the ``.travis.yml`` file +generated in Step 0, and you can then see if any previous customizations you had +made need to be copied over. This file shows how one can configure Travis to use +tox, optionally using conda via ci-helpers to set up Python on MacOS X and +Windows. Step 14 - Update ReadTheDocs configuration ------------------------------------------ With the set-up described in this migration guide, you should be able to simplify the configuration for ReadTheDocs. This can be done via a -``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is -recommended). This file just needs to contain: - -.. code:: yaml - - version: 2 - - build: - image: latest - - python: - version: 3.7 - install: - - method: pip - path: . - extra_requirements: - - docs - - all - -If you don’t have the ``all`` extras_require defined, you can remove -that line. - -If you don’t need to build non-HTML formats for the docs (e.g. epub), -you can also add the following line at the end of your -``.readthedocs.yml`` file: - -.. code:: yaml - - formats: [] - -With this updated file, you should now be able to remove any pip -requirements file or conda yml file that were previously used by -``readthedocs.yml``. +``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is recommended). +You should be able to copy over the ``.readthedocs.yml`` file created in Step 0. +With this updated file, you should now be able to remove any pip requirements +file or conda yml file that were previously used by ``readthedocs.yml``. Step 15 - Coverage configuration -------------------------------- @@ -756,9 +512,11 @@ Step 16 - conftest.py file updates ---------------------------------- For the header in your test runs to be correct with the latest versions of -astropy, you will need to make sure that you update your ``conftest.py`` -file as described in the `pytest-astropy-header instructions +astropy, you will need to make sure that you update your ``conftest.py`` file as +described in the `pytest-astropy-header instructions `_. +You can also just copy over the file created in Step 0 and add back any +customizations you had. Step 17 - Final cleanup ----------------------- diff --git a/{{ cookiecutter.package_name }}/.readthedocs.yml b/{{ cookiecutter.package_name }}/.readthedocs.yml index 47fe6adf..75c2f4b8 100644 --- a/{{ cookiecutter.package_name }}/.readthedocs.yml +++ b/{{ cookiecutter.package_name }}/.readthedocs.yml @@ -1,5 +1,17 @@ -conda: - file: .rtd-environment.yml +.. code:: yaml -python: - setup_py_install: true + version: 2 + + build: + image: latest + + python: + version: 3.7 + install: + - method: pip + path: . + extra_requirements: + - docs + - all + +formats: [] From 4d8b5c7f3b8b303c0c9c62956f48fc6f1554a4d4 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 17:16:07 +0000 Subject: [PATCH 17/44] More cleanup of the APE 17 migration guide --- docs/ape17.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 87b672a5..be6ee123 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -21,6 +21,8 @@ and that the module is called ``my_package``. We deliberately choose a name where the package name is different from the module name, but for many cases, these will be the same. +.. _step0: + Step 0: Re-rendering the template --------------------------------- @@ -140,7 +142,7 @@ included as well as all files inside ``my_package/tests/data``. Step 5 - Update your ``setup.py`` file -------------------------------------- -Copy the ``setup.py`` file you generated in Step 0 and replace your existing one +Copy the ``setup.py`` file you generated in :ref:`Step 0 ` and replace your existing one - it should be good to go as-is without any further customizations. Step 6: add a ``pyproject.toml`` file @@ -148,7 +150,7 @@ Step 6: add a ``pyproject.toml`` file The ``pyproject.toml`` file is used to declare dependencies needed to run ``setup.py`` and build the package. Copy the ``pyproject.toml`` file you -generated in Step 0 and replace your existing one. +generated in :ref:`Step 0 ` and replace your existing one. If your package doesn’t have any compiled extensions, the file should contain: @@ -197,9 +199,9 @@ each should return a list of extensions. Check through your existing ``setup_package.py`` files (if any), and make sure that any ``astropy_helpers`` imports are changed to ``extension_helpers``. -Provided you indicated when you generated the template that you wanted to -use compiled extensions, you should be good to go. If not, make sure -you add: +Provided you indicated when you generated the template in :ref:`Step 0 ` +that you wanted to use compiled extensions, you should be good to go. If not, +make sure you add: .. code:: python @@ -230,7 +232,7 @@ supported Numpy version for each Python version. However, rather than doing this manually, you can add the ``oldest-supported-numpy`` package to the build dependencies in your ``pyproject.toml`` file. In addition if you have Cython extensions, you will need to also add an entry for Cython, pinning it to a -recent version. Provided you indicated when you generated the template in Step 0 +recent version. Provided you indicated when you generated the template in :ref:`Step 0 ` that you wanted to use compiled extensions, you should be good to go as both ``oldest-supported-numpy`` and ``cython`` should be in the ``pyproject.toml`` file. In this case your ``pyproject.toml`` file will look like: @@ -276,7 +278,7 @@ Next, check your ``.gitignore`` and make sure that you have a line containing:: my_package/version.py -Finally, copy over the ``_astropy_init.py`` file generated in Step 0, or +Finally, copy over the ``_astropy_init.py`` file generated in :ref:`Step 0 `, or alternatively edit your ``my_package/_astropy_init.py`` file and remove the following lines: @@ -399,7 +401,7 @@ install it into a virtual environment before running tests or building docs, which means that it will be a good test of whether e.g. you have declared the package data correctly. -As a starting point, copy over the ``tox.ini`` file generated in Step 0. +As a starting point, copy over the ``tox.ini`` file generated in :ref:`Step 0 `. You can always then customize it if needed (although it should work out of the box). @@ -447,7 +449,7 @@ configurations you want to use, and to then keep the CI configuration as simple as possible. If you use Travis CI, a good place to start is the ``.travis.yml`` file -generated in Step 0, and you can then see if any previous customizations you had +generated in :ref:`Step 0 `, and you can then see if any previous customizations you had made need to be copied over. This file shows how one can configure Travis to use tox, optionally using conda via ci-helpers to set up Python on MacOS X and Windows. @@ -458,7 +460,7 @@ Step 14 - Update ReadTheDocs configuration With the set-up described in this migration guide, you should be able to simplify the configuration for ReadTheDocs. This can be done via a ``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is recommended). -You should be able to copy over the ``.readthedocs.yml`` file created in Step 0. +You should be able to copy over the ``.readthedocs.yml`` file created in :ref:`Step 0 `. With this updated file, you should now be able to remove any pip requirements file or conda yml file that were previously used by ``readthedocs.yml``. @@ -515,7 +517,7 @@ For the header in your test runs to be correct with the latest versions of astropy, you will need to make sure that you update your ``conftest.py`` file as described in the `pytest-astropy-header instructions `_. -You can also just copy over the file created in Step 0 and add back any +You can also just copy over the file created in :ref:`Step 0 ` and add back any customizations you had. Step 17 - Final cleanup From 471e6ca30ece5deb526d85ae9cbb01f919a45a8b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Mon, 27 Jan 2020 17:20:15 +0000 Subject: [PATCH 18/44] Fix RTD config files --- .readthedocs.yml | 11 ++++++-- requirements.txt | 1 - .../.readthedocs.yml | 28 +++++++++---------- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 271aee44..6901e0da 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,4 +1,11 @@ -requirements_file: requirements.txt +version: 2 + +build: + image: latest python: - version: 3.5 + version: 3.7 + install: + - requirements: requirements.txt + +formats: [] diff --git a/requirements.txt b/requirements.txt index eaaced99..202ff07d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,3 @@ -astropy-helpers sphinx gitpython sphinx-astropy diff --git a/{{ cookiecutter.package_name }}/.readthedocs.yml b/{{ cookiecutter.package_name }}/.readthedocs.yml index 75c2f4b8..91be6211 100644 --- a/{{ cookiecutter.package_name }}/.readthedocs.yml +++ b/{{ cookiecutter.package_name }}/.readthedocs.yml @@ -1,17 +1,15 @@ -.. code:: yaml - - version: 2 - - build: - image: latest - - python: - version: 3.7 - install: - - method: pip - path: . - extra_requirements: - - docs - - all +version: 2 + +build: + image: latest + +python: + version: 3.7 + install: + - method: pip + path: . + extra_requirements: + - docs + - all formats: [] From b4a2092c0948f8be3135434004aeac29ee78ebfd Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 12:00:16 +0000 Subject: [PATCH 19/44] Fix variable --- {{ cookiecutter.package_name }}/setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{ cookiecutter.package_name }}/setup.py b/{{ cookiecutter.package_name }}/setup.py index 65e30eaf..5496d47b 100644 --- a/{{ cookiecutter.package_name }}/setup.py +++ b/{{ cookiecutter.package_name }}/setup.py @@ -9,7 +9,7 @@ from setuptools import setup from setuptools.config import read_configuration -{% if cookiecutter.include_example_code == 'y' %} +{% if cookiecutter.use_compiled_extensions == 'y' %} from extension_helpers import get_extensions {% endif %} From e1658a33dc75102ebcba1078fd1c622409949841 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 12:05:00 +0000 Subject: [PATCH 20/44] Make Step 0 sound less optional --- docs/ape17.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index be6ee123..4c3c51b5 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -27,16 +27,12 @@ Step 0: Re-rendering the template --------------------------------- In this guide, we will descibe the changes to make to the files in your package. -However, you may not currently have the latest version of all files from the -template, so this is also a good chance to make sure you are completely up to -date by re-rendering the cookiecutter template to a new folder:: +To make some of the steps easier below, you should first re-run cookiecutter to +re-render the template to a temporary folder:: cookiecutter gh:astropy/package-template -o my_package_tmp -As you progress through this guide, you can then - if you wish - copy over the -newest version of the file, taking care to edit it if needed to match any -desired customizations you had previously. This will also be useful for any new -files which you can then just copy from the rendered template. +We will refer to some of the rendered files in several of the steps below. Step 1: Remove astropy-helpers ------------------------------ From 34ad4ce35f62c4708fc6e7ac46fe0c1d55e678e4 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 12:09:03 +0000 Subject: [PATCH 21/44] Fix typo --- docs/ape17.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 4c3c51b5..d3d274f9 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -471,14 +471,14 @@ to keep track of. Add the following to the bottom of your ``setup.cfg``:: [coverage:run] omit = - my_package/_{{ cookiecutter._parent_project }}_init* + my_package/_astropy_init* my_package/conftest.py my_package/*setup_package* my_package/tests/* my_package/*/tests/* my_package/extern/* my_package/version* - */my_package/_{{ cookiecutter._parent_project }}_init* + */my_package/_astropy_init* */my_package/conftest.py */my_package/*setup_package* */my_package/tests/* From 93f106678c9000f0b2b520a9640c22e2b8e9406b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:21:24 +0000 Subject: [PATCH 22/44] Apply suggestions from code review Co-Authored-By: P. L. Lim <2090236+pllim@users.noreply.github.com> --- docs/ape17.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index d3d274f9..a61c23d1 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -8,7 +8,7 @@ The Astropy project is now transitioning from using astropy-helpers for infrastructure to more standard Python packaging tools. The motivation and implications of this are discussed in an Astropy Proposal for Enhancements: `APE 17: A roadmap for package infrastructure without -astropy-helpers `__ +astropy-helpers `__. This page aims to provide a guide to migrating to using the new infrastructure described in APE 17. We assume that your package is currently using @@ -26,7 +26,7 @@ these will be the same. Step 0: Re-rendering the template --------------------------------- -In this guide, we will descibe the changes to make to the files in your package. +In this guide, we will describe the changes to make to the files in your package. To make some of the steps easier below, you should first re-run cookiecutter to re-render the template to a temporary folder:: @@ -42,7 +42,9 @@ To remove the astropy-helpers submodule, first, run:: git rm -r astropy_helpers if ``astropy_helpers`` was the only submodule in your repository, the -``.gitmodules`` file will be empty, you can remove this if you wish. +``.gitmodules`` file will be empty, you can remove this if you wish:: + + git rm .gitmodules Next you should remove the ``ah_bootstrap.py`` file:: @@ -184,7 +186,7 @@ Step 7b - Using extension-helpers You can use the extension-helpers package to: -- Automatically define extensions for Cython files +- Automatically define extensions for Cython files. - Pick up extensions declared in ``setup_package.py`` files, as described in the `extension-helpers documentation `__. @@ -253,7 +255,7 @@ Step 8 - Using setuptools_scm The `setuptools_scm `__ package is now recommended to manage the version numbers for your package. The way this works is that instead of setting the version -number manually in e.g. ``setup.cfg`` or elsewhere in your package, +number manually in, e.g., ``setup.cfg`` or elsewhere in your package, the version number is based on git tags. In Steps 5 and 6, we already added the required entry for @@ -390,11 +392,11 @@ Step 12 - Setting up tox ------------------------ `tox `__ is a tool for automating -commands, which is well suited to e.g. running tests for your package or +commands, which is well suited to, e.g., running tests for your package or building the documentation. One of the benefits of using tox is that it will (by default) create a source distribution for your package and install it into a virtual environment before running tests or building -docs, which means that it will be a good test of whether e.g. you have +docs, which means that it will be a good test of whether, e.g., you have declared the package data correctly. As a starting point, copy over the ``tox.ini`` file generated in :ref:`Step 0 `. @@ -458,7 +460,7 @@ simplify the configuration for ReadTheDocs. This can be done via a ``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is recommended). You should be able to copy over the ``.readthedocs.yml`` file created in :ref:`Step 0 `. With this updated file, you should now be able to remove any pip requirements -file or conda yml file that were previously used by ``readthedocs.yml``. +file or conda YAML file that were previously used by ``readthedocs.yml``. Step 15 - Coverage configuration -------------------------------- @@ -513,7 +515,7 @@ For the header in your test runs to be correct with the latest versions of astropy, you will need to make sure that you update your ``conftest.py`` file as described in the `pytest-astropy-header instructions `_. -You can also just copy over the file created in :ref:`Step 0 ` and add back any +You can also copy over the file created in :ref:`Step 0 ` and add back any customizations you had. Step 17 - Final cleanup @@ -530,4 +532,4 @@ You should also add ``pip-wheel-metadata`` to your ``.gitignore`` file. **Once you are done, if you would like us to help by reviewing your changes, you can open a pull request to your package and mention @astrofrog or -@Cadair to ask for a review** +@Cadair to ask for a review.** From 1c46da4f99c4180395aa42772eb27cb67056da16 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:12:50 +0000 Subject: [PATCH 23/44] Remove option to initialize git repository since it is no longer very useful without astropy-helpers. Also remove remaining references to astropy-helpers. --- .travis-deploy.sh | 12 ------------ .travis.yml | 4 ++-- QUESTIONS.rst | 1 - cookiecutter.json | 1 - docs/index.rst | 4 +--- docs/options.rst | 1 - docs/updating.rst | 11 +++-------- hooks/post_gen_project.py | 13 ------------- rendered.yml | 1 - 9 files changed, 6 insertions(+), 42 deletions(-) diff --git a/.travis-deploy.sh b/.travis-deploy.sh index 51912f7b..152b432a 100644 --- a/.travis-deploy.sh +++ b/.travis-deploy.sh @@ -19,18 +19,6 @@ if [[ "${TRAVIS_PULL_REQUEST}" = "false" && "$TRAVIS_OS_NAME" = "linux" && $TASK git checkout master rsync -avz --delete --exclude .git/ ../packagename/ ./ git add -A - - # Add astropy_helpers manually at the version in the cookiecutter template - git submodule add https://github.com/astropy/astropy-helpers astropy_helpers || true - git submodule update --init - cd astropy_helpers - # parse the json with jq to get the helpers version - helpers_version=$(jq -r ".cookiecutter.astropy_helpers_version" $HOME/.cookiecutter_replay/package-template.json) - git checkout $helpers_version - cp ah_bootstrap.py ../ - cd .. - git add astropy_helpers ah_bootstrap.py - git commit --allow-empty -m "Update rendered version to ""$TRAVIS_COMMIT" git push origin master fi diff --git a/.travis.yml b/.travis.yml index d7f57b56..594c532e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -22,11 +22,11 @@ env: # being overridden here must exist in the cookiecutter.json # See https://cookiecutter.readthedocs.io/en/0.9.1/advanced_usage.html#injecting-extra-context - EXTRA_CONTEXT='' - - EXTRA_CONTEXT='include_example_cython_code=y' + - EXTRA_CONTEXT='use_compiled_extensions=y include_example_code=y' - EXTRA_CONTEXT="package_name=AstropyProject" FOLDERNAME='AstropyProject' - EXTRA_CONTEXT='_parent_project=sunpy' - EXTRA_CONTEXT='minimum_python_version=3.5' - - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='include_example_cython_code=y initialize_git_repo=n license=Other' + - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='use_compiled_extensions=y include_example_code=y license=Other' install: - pip install sphinx-astropy cookiecutter gitpython tox diff --git a/QUESTIONS.rst b/QUESTIONS.rst index 04759f8f..b02cdf30 100644 --- a/QUESTIONS.rst +++ b/QUESTIONS.rst @@ -20,4 +20,3 @@ a description of each of the prompts. 13. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. 14. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. 15. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. -16. ``initialize_git_repo``: If `gitpython `_ is installed this option will turn the rendered package into a git repository and add and initilize the ``astropy_helpers`` submodule. diff --git a/cookiecutter.json b/cookiecutter.json index 8b7ffcd5..7794a2b0 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -14,7 +14,6 @@ "use_travis_ci": "y", "use_read_the_docs": "y", "sphinx_theme": "astropy-bootstrap", - "initialize_git_repo": "y", "_parent_project": "astropy", "_install_requires": "astropy", "minimum_python_version": ["3.7", "3.6", "3.5"] diff --git a/docs/index.rst b/docs/index.rst index 794e7c88..e0e0e373 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,9 +20,7 @@ Getting Started The Astropy Package template uses the `Cookiecutter `_ project to make it easier to customise the template for your package. To use the package template you need cookiecutter -installed. The package template also optionally makes use of `gitpython -`_ to setup the -``astropy_helpers`` submodule. Depending on how you have Python +installed. Depending on how you have Python installed these packages can be obtained through either pip or conda:: conda install -c conda-forge cookiecutter gitpython diff --git a/docs/options.rst b/docs/options.rst index 36f93f74..0f3cd6f0 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -22,7 +22,6 @@ a description of each of the prompts: #. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. #. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. #. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. -#. ``initialize_git_repo``: If `gitpython `_ is installed this option will turn the rendered package into a git repository and add and initilize the ``astropy_helpers`` submodule. Once the project has been set up, any of the values can still be `manually updated `_. diff --git a/docs/updating.rst b/docs/updating.rst index b7fbbc4f..f1a5ef80 100644 --- a/docs/updating.rst +++ b/docs/updating.rst @@ -2,10 +2,9 @@ Updating Your Package ===================== Once you have setup your project there will come a time when some things in the -package template change, new versions of ``astropy_helpers`` or updates to the -infrastructure you want to utilise. Updating your package with these changes is -a balance between maintaining parity with the original template and customising -your project to your needs. +package template change. Updating your package with these changes is a balance +between maintaining parity with the original template and customising your +project to your needs. Using Cookiecutter to Update @@ -28,10 +27,6 @@ settings configured to your package and then pull the changes into your package. $ cookiecutter [--replay] gh:astropy/package-template -o /tmp - .. note:: - - You should choose 'n' for the "initialize_git_repo" question. - #. **Make a new branch**:: $ git checkout -b update_template diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index 6bd9322f..ee59f10b 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -54,16 +54,3 @@ def process_licence(licence_name): if '{{ cookiecutter.use_compiled_extensions }}' != 'y' or '{{ cookiecutter.include_example_code }}' != 'y': remove_file('{{ cookiecutter.module_name }}/example_c.pyx') - - if '{{ cookiecutter.initialize_git_repo }}' == 'y': - try: - from git import Repo - - new_repo = Repo.init(PROJECT_DIRECTORY) - new_repo.git.add('.') - new_repo.index.commit( - "Creation of {{ cookiecutter.package_name }} from astropy package template" - ) - - except ImportError: - print("gitpython is not installed so the repository will not be initialised.") diff --git a/rendered.yml b/rendered.yml index eaf5d2dc..108ff785 100644 --- a/rendered.yml +++ b/rendered.yml @@ -15,5 +15,4 @@ default_context: use_travis_ci: "y" use_read_the_docs: "y" sphinx_theme: "astropy-bootstrap" - initialize_git_repo: "n" minimum_python_version: "3.6" From ce4854833f17da6d9e8025b959fc753045ca93d6 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:16:03 +0000 Subject: [PATCH 24/44] Bump minimum supported version to 3.6 and add 3.8 --- .travis.yml | 2 +- cookiecutter.json | 2 +- docs/index.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 594c532e..98d68301 100644 --- a/.travis.yml +++ b/.travis.yml @@ -25,7 +25,7 @@ env: - EXTRA_CONTEXT='use_compiled_extensions=y include_example_code=y' - EXTRA_CONTEXT="package_name=AstropyProject" FOLDERNAME='AstropyProject' - EXTRA_CONTEXT='_parent_project=sunpy' - - EXTRA_CONTEXT='minimum_python_version=3.5' + - EXTRA_CONTEXT='minimum_python_version=3.6' - TASK='render' FLAGS='--config-file rendered.yml --no-input' EXTRA_CONTEXT='use_compiled_extensions=y include_example_code=y license=Other' install: diff --git a/cookiecutter.json b/cookiecutter.json index 7794a2b0..06be8970 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -16,5 +16,5 @@ "sphinx_theme": "astropy-bootstrap", "_parent_project": "astropy", "_install_requires": "astropy", - "minimum_python_version": ["3.7", "3.6", "3.5"] + "minimum_python_version": ["3.6", "3.7", "3.8"] } diff --git a/docs/index.rst b/docs/index.rst index e0e0e373..eaca5118 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,7 +67,7 @@ documentation, read the :ref:`next-steps` for further information. Removal of Python 2 support =========================== -This package template now supports Python 3.5+ versions only. However we +This package template now supports Python 3.6+ versions only. However we will provide critical bug fixes to the ``cookiecutter-2.x`` branch until the end of 2019. We also provide a Python 2 compatible rendered versions of the template in From 190fb6b38191848b597a5cf17462b61a292fc539 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:19:21 +0000 Subject: [PATCH 25/44] Added sentence about core package --- docs/ape17.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ape17.rst b/docs/ape17.rst index a61c23d1..dd7db19c 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -9,6 +9,8 @@ infrastructure to more standard Python packaging tools. The motivation and implications of this are discussed in an Astropy Proposal for Enhancements: `APE 17: A roadmap for package infrastructure without astropy-helpers `__. +The core astropy package has already migrated and these changes will be included +in astropy v4.1. This page aims to provide a guide to migrating to using the new infrastructure described in APE 17. We assume that your package is currently using From 66cc65ad659fdb181a275187c54d31f8afd40424 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:44:51 +0000 Subject: [PATCH 26/44] Improvements to migration guide following review --- docs/ape17.rst | 67 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 21 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index dd7db19c..7bfb760d 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -23,7 +23,7 @@ and that the module is called ``my_package``. We deliberately choose a name where the package name is different from the module name, but for many cases, these will be the same. -.. _step0: +.. _step-rerender: Step 0: Re-rendering the template --------------------------------- @@ -59,10 +59,11 @@ You can now commit your changes with:: Step 2: Update/create ``setup.cfg`` ----------------------------------- -The next step is to update make sure that you have a ``setup.cfg`` file -that contains meta-data about the package. If you already have this -file, you will likely need to update it, and if you don’t already have -this file, you will need to create it. +The next step is to update make sure that you have a `setup.cfg +`_ +file that contains meta-data about the package. If you already have this file, +you will likely need to update it, and if you don’t already have this file, you +will need to create it. This file should contain at least the following entries:: @@ -96,10 +97,13 @@ If you already had a file, make sure you remove the following entries - ``package_name`` - ``version`` -- ``setup_requires`` - ``tests_require`` - ``[ah_bootstrap]`` and all entries in it +Also remove any existing ``setup_requires`` entry, though we'll add +back this key for the setuptools-scm package in +:ref:`Step 8 `. + Step 3 - Define optional, test, and docs dependencies ----------------------------------------------------- @@ -139,18 +143,22 @@ e.g.:: In the above example, all ``.fits`` and ``.csv`` in the package will be included as well as all files inside ``my_package/tests/data``. +.. _step-setup-py: + Step 5 - Update your ``setup.py`` file -------------------------------------- -Copy the ``setup.py`` file you generated in :ref:`Step 0 ` and replace your existing one +Copy the ``setup.py`` file you generated in :ref:`Step 0 ` and replace your existing one - it should be good to go as-is without any further customizations. +.. _step-pyproject-toml: + Step 6: add a ``pyproject.toml`` file ------------------------------------- The ``pyproject.toml`` file is used to declare dependencies needed to run ``setup.py`` and build the package. Copy the ``pyproject.toml`` file you -generated in :ref:`Step 0 ` and replace your existing one. +generated in :ref:`Step 0 ` and replace your existing one. If your package doesn’t have any compiled extensions, the file should contain: @@ -181,7 +189,8 @@ package, and you don't need to include extension-helpers in the ``pyproject.toml`` file. If you have Cython extensions or your extensions use the NumPy C API, -proceed to Step 7c, otherwise you can proceed to Step 8. +proceed to :ref:`Step 7c `, otherwise you can proceed to +:ref:`Step 8 `. Step 7b - Using extension-helpers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -197,9 +206,16 @@ The latter works by looking through all the ``setup_package.py`` files in your package and executing the ``get_extensions()`` functions, which each should return a list of extensions. Check through your existing ``setup_package.py`` files (if any), and make sure that any -``astropy_helpers`` imports are changed to ``extension_helpers``. - -Provided you indicated when you generated the template in :ref:`Step 0 ` +``astropy_helpers`` imports are changed to ``extension_helpers``. Also +note that all functions in extension-helpers should now be imported from +the top level. See the `extension-helpers API documentation +`_ for a complete +list of functions still provided by extension-helpers. Finally, make +sure that any instance of ``include_dirs='numpy'`` is changed to +``include_dirs=np.get_include()`` and add the ``import numpy as np`` +import if not already present. + +Provided you indicated when you generated the template in :ref:`Step 0 ` that you wanted to use compiled extensions, you should be good to go. If not, make sure you add: @@ -218,7 +234,10 @@ In addition, in the same file, add ``ext_modules=get_extensions()`` to the call to ``setup.py``. If you have Cython extensions or your extensions use the NumPy C API, -proceed to Step 7c, otherwise you can proceed to Step 8. +proceed to :ref:`Step 7c `, otherwise you can proceed to +:ref:`Step 8 `. + +.. _step-cython-numpy: Step 7c - Cython and Numpy build-time dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -232,7 +251,7 @@ supported Numpy version for each Python version. However, rather than doing this manually, you can add the ``oldest-supported-numpy`` package to the build dependencies in your ``pyproject.toml`` file. In addition if you have Cython extensions, you will need to also add an entry for Cython, pinning it to a -recent version. Provided you indicated when you generated the template in :ref:`Step 0 ` +recent version. Provided you indicated when you generated the template in :ref:`Step 0 ` that you wanted to use compiled extensions, you should be good to go as both ``oldest-supported-numpy`` and ``cython`` should be in the ``pyproject.toml`` file. In this case your ``pyproject.toml`` file will look like: @@ -251,6 +270,8 @@ file. In this case your ``pyproject.toml`` file will look like: Whenever a new major Python version is released, you will likely need to update the Cython pinning to use the most recent Cython version available. +.. _step-setuptools-scm: + Step 8 - Using setuptools_scm ----------------------------- @@ -260,8 +281,9 @@ package. The way this works is that instead of setting the version number manually in, e.g., ``setup.cfg`` or elsewhere in your package, the version number is based on git tags. -In Steps 5 and 6, we already added the required entry for -setuptools_scm to ``setup.py`` and ``pyproject.toml``. +In :ref:`Steps 5 ` and :ref:`6 `, we already +added the required entry for setuptools_scm to ``setup.py`` and +``pyproject.toml``. In addition to these, we recommend that you define ``setup_requires`` inside the ``[options]`` section of your ``setup.cfg`` file:: @@ -278,7 +300,7 @@ Next, check your ``.gitignore`` and make sure that you have a line containing:: my_package/version.py -Finally, copy over the ``_astropy_init.py`` file generated in :ref:`Step 0 `, or +Finally, copy over the ``_astropy_init.py`` file generated in :ref:`Step 0 `, or alternatively edit your ``my_package/_astropy_init.py`` file and remove the following lines: @@ -401,7 +423,7 @@ install it into a virtual environment before running tests or building docs, which means that it will be a good test of whether, e.g., you have declared the package data correctly. -As a starting point, copy over the ``tox.ini`` file generated in :ref:`Step 0 `. +As a starting point, copy over the ``tox.ini`` file generated in :ref:`Step 0 `. You can always then customize it if needed (although it should work out of the box). @@ -449,7 +471,7 @@ configurations you want to use, and to then keep the CI configuration as simple as possible. If you use Travis CI, a good place to start is the ``.travis.yml`` file -generated in :ref:`Step 0 `, and you can then see if any previous customizations you had +generated in :ref:`Step 0 `, and you can then see if any previous customizations you had made need to be copied over. This file shows how one can configure Travis to use tox, optionally using conda via ci-helpers to set up Python on MacOS X and Windows. @@ -460,7 +482,10 @@ Step 14 - Update ReadTheDocs configuration With the set-up described in this migration guide, you should be able to simplify the configuration for ReadTheDocs. This can be done via a ``readthedocs.yml`` or ``.readthedocs.yml`` file (the latter is recommended). -You should be able to copy over the ``.readthedocs.yml`` file created in :ref:`Step 0 `. +See the `ReadTheDocs `_ +documentation for more information about this file. + +You should be able to copy over the ``.readthedocs.yml`` file created in :ref:`Step 0 `. With this updated file, you should now be able to remove any pip requirements file or conda YAML file that were previously used by ``readthedocs.yml``. @@ -517,7 +542,7 @@ For the header in your test runs to be correct with the latest versions of astropy, you will need to make sure that you update your ``conftest.py`` file as described in the `pytest-astropy-header instructions `_. -You can also copy over the file created in :ref:`Step 0 ` and add back any +You can also copy over the file created in :ref:`Step 0 ` and add back any customizations you had. Step 17 - Final cleanup From 7ef315e4076bfb9c552c6db7f9c12912688314f9 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Tue, 28 Jan 2020 21:53:32 +0000 Subject: [PATCH 27/44] Make sure repository is initialized on Travis --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index 98d68301..299bcccd 100644 --- a/.travis.yml +++ b/.travis.yml @@ -35,6 +35,7 @@ script: - cd docs ; make html ; cd .. - cookiecutter --no-input ./ -o ../test $EXTRA_CONTEXT $FLAGS - cd ../test/$FOLDERNAME + - git init - if [[ $TASK == 'test' ]]; then tox -e py38-test; fi - if [[ $TASK == 'test' ]]; then tox -e build_docs; fi - if [[ $TASK == 'test' ]]; then tox -e codestyle; fi From b2dd969b5824fa69c6798953a1e72261adea79a7 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 08:44:24 +0000 Subject: [PATCH 28/44] Add back minimum_python_version to list of questions/options --- QUESTIONS.rst | 1 + docs/options.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/QUESTIONS.rst b/QUESTIONS.rst index b02cdf30..aca53a73 100644 --- a/QUESTIONS.rst +++ b/QUESTIONS.rst @@ -20,3 +20,4 @@ a description of each of the prompts. 13. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. 14. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. 15. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. +16. ``minimum_python_version``: Version string of minimum supported Python version diff --git a/docs/options.rst b/docs/options.rst index 0f3cd6f0..9ba4801b 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -22,6 +22,7 @@ a description of each of the prompts: #. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. #. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. #. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. +#. ``minimum_python_version``: Version string of minimum supported Python version Once the project has been set up, any of the values can still be `manually updated `_. From cf0b842f46597fdd64fddf035c9d644cfdf07814 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 08:51:48 +0000 Subject: [PATCH 29/44] Give more example environments in the tox envlist --- {{ cookiecutter.package_name }}/tox.ini | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/{{ cookiecutter.package_name }}/tox.ini b/{{ cookiecutter.package_name }}/tox.ini index 706ec539..b5ac2869 100644 --- a/{{ cookiecutter.package_name }}/tox.ini +++ b/{{ cookiecutter.package_name }}/tox.ini @@ -1,6 +1,8 @@ [tox] envlist = - py{36,37,38}-test{,-alldeps,-oldestdeps,-devdeps,-numpy116,-numpy117,-numpy118} + py{36,37,38}-test{,-alldeps,-devdeps} + py{36,37,38}-test-numpy{116,117,118} + py{36,37,38}-test-astropy{30,40,lts} build_docs codestyle requires = @@ -34,7 +36,11 @@ description = numpy116: with numpy 1.16.* numpy117: with numpy 1.17.* numpy118: with numpy 1.18.* + astropy30: with astropy 3.0.* + astropy40: with astropy 4.0.* + astropylts: with the latest astropy LTS +# The following provides some specific pinnings for key packages deps = numpy116: numpy==1.16.* @@ -44,7 +50,6 @@ deps = astropy30: astropy==3.0.* astropy40: astropy==4.0.* astropylts: astropy==4.0.* - astropydev: git+https://github.com/astropy/astropy.git#egg=astropy devdeps: git+https://github.com/numpy/numpy.git#egg=numpy devdeps: git+https://github.com/astropy/astropy.git#egg=astropy From c6dbd6e2ea73c6f760091a090badf630b50897e6 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 13:41:53 +0000 Subject: [PATCH 30/44] Added support for specifying required and optional dependencies --- cookiecutter.json | 3 ++- rendered.yml | 2 ++ {{ cookiecutter.package_name }}/setup.cfg | 12 ++++++++++-- .../{{ cookiecutter.module_name }}/conftest.py | 5 ++--- 4 files changed, 16 insertions(+), 6 deletions(-) diff --git a/cookiecutter.json b/cookiecutter.json index 06be8970..b4850f7e 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -15,6 +15,7 @@ "use_read_the_docs": "y", "sphinx_theme": "astropy-bootstrap", "_parent_project": "astropy", - "_install_requires": "astropy", + "required_dependencies": "astropy", + "optional_dependencies": "", "minimum_python_version": ["3.6", "3.7", "3.8"] } diff --git a/rendered.yml b/rendered.yml index 108ff785..08845f29 100644 --- a/rendered.yml +++ b/rendered.yml @@ -16,3 +16,5 @@ default_context: use_read_the_docs: "y" sphinx_theme: "astropy-bootstrap" minimum_python_version: "3.6" + required_dependencies: "astropy" + optional_dependencies: "" diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index 2ebf6820..69558403 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -15,16 +15,24 @@ zip_safe = False packages = find: python_requires = >={{ cookiecutter.minimum_python_version }} setup_requires = setuptools_scm -install_requires = {{ cookiecutter._install_requires }} +{% if cookiecutter.required_dependencies -%} +install_requires = +{%- for req in cookiecutter.required_dependencies.split(',') %} + {{ req.strip() }}{% endfor %} +{% endif -%} {% if cookiecutter.include_example_code == 'y' %} [options.entry_points] console_scripts = astropy-package-template-example = packagename.example_mod:main -{% endif %} +{%- endif %} [options.extras_require] +{% if cookiecutter.optional_dependencies -%} all = +{%- for req in cookiecutter.optional_dependencies.split(',') %} + {{ req.strip() }}{% endfor %} +{% endif -%} test = pytest-astropy docs = diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index 562a3889..5fe7787a 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -25,9 +25,7 @@ def pytest_configure(config): packagename = os.path.basename(os.path.dirname(__file__)) TESTED_VERSIONS[packagename] = version -from astropy.tests.helper import enable_deprecations_as_exceptions # noqa - -# Uncomment the last line in this block to treat all DeprecationWarnings as +# Uncomment the last two lines in this block to treat all DeprecationWarnings as # exceptions. For Astropy v2.0 or later, there are 2 additional keywords, # as follow (although default should work for most cases). # To ignore some packages that produce deprecation warnings on import @@ -37,4 +35,5 @@ def pytest_configure(config): # To ignore some specific deprecation warning messages for Python version # MAJOR.MINOR or later, add: # warnings_to_ignore_by_pyver={(MAJOR, MINOR): ['Message to ignore']} +# from astropy.tests.helper import enable_deprecations_as_exceptions # noqa # enable_deprecations_as_exceptions() From 45122d67275111619d4bd4aa7e6ee213730fe051 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 13:51:47 +0000 Subject: [PATCH 31/44] Added description of new options --- QUESTIONS.rst | 4 +++- docs/options.rst | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/QUESTIONS.rst b/QUESTIONS.rst index aca53a73..8d2b4b52 100644 --- a/QUESTIONS.rst +++ b/QUESTIONS.rst @@ -20,4 +20,6 @@ a description of each of the prompts. 13. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. 14. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. 15. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. -16. ``minimum_python_version``: Version string of minimum supported Python version +16. ``required_dependencies``: Comma-separated list of required dependencies +17. ``optional_dependencies``: Comma-separated list of optional dependencies +18. ``minimum_python_version``: Version string of minimum supported Python version diff --git a/docs/options.rst b/docs/options.rst index 9ba4801b..422cddc3 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -22,6 +22,8 @@ a description of each of the prompts: #. ``use_travis_ci``: If ``'y'`` the template will include an example ``.travis.yml`` file for the Travis CI service. #. ``use_read_the_docs``: If ``'y'`` the ``read_the_docs.yml`` and ``.rtd-environment.yml`` files will be included for using conda on Read the Docs. #. ``sphinx_theme``: The value of the ``html_theme`` variable in the sphinx configuration file. +#. ``required_dependencies``: Comma-separated list of required dependencies +#. ``optional_dependencies``: Comma-separated list of optional dependencies #. ``minimum_python_version``: Version string of minimum supported Python version Once the project has been set up, any of the values can still be `manually From a4948220742f43d598ad60b63d3624cd9ff617a6 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 13:55:17 +0000 Subject: [PATCH 32/44] Avoid repetition in setup.py --- {{ cookiecutter.package_name }}/setup.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/{{ cookiecutter.package_name }}/setup.py b/{{ cookiecutter.package_name }}/setup.py index 5496d47b..11a397b6 100644 --- a/{{ cookiecutter.package_name }}/setup.py +++ b/{{ cookiecutter.package_name }}/setup.py @@ -77,11 +77,9 @@ version = '{version}' """.lstrip() -{% if cookiecutter.use_compiled_extensions == 'y' %} setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), - 'write_to_template': VERSION_TEMPLATE}, + 'write_to_template': VERSION_TEMPLATE} +{%- if cookiecutter.use_compiled_extensions == 'y' %}, ext_modules=get_extensions()) -{% else %} -setup(use_scm_version={'write_to': os.path.join('{{ cookiecutter.module_name }}', 'version.py'), - 'write_to_template': VERSION_TEMPLATE}) -{% endif %} +{%- else %}) +{%- endif %} From 65d57c120391a4f1b2ced387e319fac87ea08144 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 14:04:12 +0000 Subject: [PATCH 33/44] Added new entry to .gitignore --- {{ cookiecutter.package_name }}/.gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/{{ cookiecutter.package_name }}/.gitignore b/{{ cookiecutter.package_name }}/.gitignore index 55e2af05..c841f0cf 100644 --- a/{{ cookiecutter.package_name }}/.gitignore +++ b/{{ cookiecutter.package_name }}/.gitignore @@ -55,6 +55,7 @@ distribute-*.tar.gz .project .pydevproject .settings +pip-wheel-metadata # Mac OSX .DS_Store From acfd4b349bf800e3b8b5a1d8933e0c12533f493f Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 16:09:02 +0000 Subject: [PATCH 34/44] Added long_description_content_type --- {{ cookiecutter.package_name }}/setup.cfg | 1 + 1 file changed, 1 insertion(+) diff --git a/{{ cookiecutter.package_name }}/setup.cfg b/{{ cookiecutter.package_name }}/setup.cfg index 69558403..64bf9224 100644 --- a/{{ cookiecutter.package_name }}/setup.cfg +++ b/{{ cookiecutter.package_name }}/setup.cfg @@ -7,6 +7,7 @@ license_file = licenses/LICENSE.rst url = {{ cookiecutter.project_url }} description = {{ cookiecutter.short_description }} long_description = file: README.rst +long_description_content_type = text/x-rst edit_on_github = {{ cookiecutter.edit_on_github_extension }} github_project = {{ cookiecutter.github_project }} From ef9573da29fc3b7ee7e296d308da09dabaf7993d Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Wed, 29 Jan 2020 16:09:48 +0000 Subject: [PATCH 35/44] Added trailing slash in .gitignore for directory Co-Authored-By: P. L. Lim <2090236+pllim@users.noreply.github.com> --- {{ cookiecutter.package_name }}/.gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{ cookiecutter.package_name }}/.gitignore b/{{ cookiecutter.package_name }}/.gitignore index c841f0cf..7c60f757 100644 --- a/{{ cookiecutter.package_name }}/.gitignore +++ b/{{ cookiecutter.package_name }}/.gitignore @@ -55,7 +55,7 @@ distribute-*.tar.gz .project .pydevproject .settings -pip-wheel-metadata +pip-wheel-metadata/ # Mac OSX .DS_Store From d62621cb5518792af1bbb95e3c65020bc47d8659 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Thu, 30 Jan 2020 10:46:41 +0000 Subject: [PATCH 36/44] Fixes/improvements to APE 17 migration guide --- docs/ape17.rst | 58 +++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 7bfb760d..11c8608b 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -46,7 +46,7 @@ To remove the astropy-helpers submodule, first, run:: if ``astropy_helpers`` was the only submodule in your repository, the ``.gitmodules`` file will be empty, you can remove this if you wish:: - git rm .gitmodules + git rm -f .gitmodules Next you should remove the ``ah_bootstrap.py`` file:: @@ -63,9 +63,12 @@ The next step is to update make sure that you have a `setup.cfg `_ file that contains meta-data about the package. If you already have this file, you will likely need to update it, and if you don’t already have this file, you -will need to create it. +will need to create it by copying over the ``setup.cfg`` file generated in +:ref:`Step 0 `. If you are updating an existing file, you may +also find it easier to start from the file generated in :ref:`Step 0 ` +and add back any customizations. -This file should contain at least the following entries:: +In any case this file should contain at least the following entries:: [metadata] name = my-package @@ -160,15 +163,13 @@ The ``pyproject.toml`` file is used to declare dependencies needed to run ``setup.py`` and build the package. Copy the ``pyproject.toml`` file you generated in :ref:`Step 0 ` and replace your existing one. -If your package doesn’t have any compiled extensions, the file should contain: +If your package doesn’t have any compiled extensions, the file should contain:: -.. code:: toml - - [build-system] - requires = ["setuptools", - "setuptools_scm", - "wheel"] - build-backend = 'setuptools.build_meta' + [build-system] + requires = ["setuptools", + "setuptools_scm", + "wheel"] + build-backend = 'setuptools.build_meta' Step 7 - Handling C/Cython extensions ------------------------------------- @@ -254,18 +255,16 @@ extensions, you will need to also add an entry for Cython, pinning it to a recent version. Provided you indicated when you generated the template in :ref:`Step 0 ` that you wanted to use compiled extensions, you should be good to go as both ``oldest-supported-numpy`` and ``cython`` should be in the ``pyproject.toml`` -file. In this case your ``pyproject.toml`` file will look like: - -.. code:: toml +file. In this case your ``pyproject.toml`` file will look like:: - [build-system] - requires = ["setuptools", - "setuptools_scm", - "wheel", - "extension-helpers", - "oldest-supported-numpy", - "cython==0.29.14"] - build-backend = 'setuptools.build_meta' + [build-system] + requires = ["setuptools", + "setuptools_scm", + "wheel", + "extension-helpers", + "oldest-supported-numpy", + "cython==0.29.14"] + build-backend = 'setuptools.build_meta' Whenever a new major Python version is released, you will likely need to update the Cython pinning to use the most recent Cython version available. @@ -293,8 +292,10 @@ In addition to these, we recommend that you define ``setup_requires`` inside the setup_requires = setuptools_scm ... -This is not strictly necessary but will make it possible for ``python setup.py --version`` -to work without having to install ``setuptools_scm`` manually. +This will already be the case if you copied the ``setup.cfg`` generated in +:ref:`Step 0 `. Having ``setup_requires`` is not strictly +necessary but will make it possible for ``python setup.py --version`` to work +without having to install ``setuptools_scm`` manually. Next, check your ``.gitignore`` and make sure that you have a line containing:: @@ -328,8 +329,9 @@ To make sure that pytest works properly, you can set a few options in a text_file_format = rst addopts = --doctest-rst -For the ``testpaths`` line, make sure you replace ``my_package`` with -the name of your package. +For the ``testpaths`` line, make sure you replace ``my_package`` with the name +of your package. This section will already exist if you copied the ``setup.cfg`` +generated in :ref:`Step 0 `. The remaining options ensure that the output from pytest includes a header that lists dependencies and system information, and also ensure @@ -533,7 +535,9 @@ to keep track of. Add the following to the bottom of your ``setup.cfg``:: Make sure to replace ``my_package`` by your module name. If you had any customizations in ``coveragerc`` you can include them here, but otherwise the -above should be sufficient. +above should be sufficient and you should now be able to remove the old file:: + + git rm my_package/tests/coveragerc Step 16 - conftest.py file updates ---------------------------------- From 970fe945438539c1cfb0306088639e5840c75b25 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Thu, 30 Jan 2020 10:47:00 +0000 Subject: [PATCH 37/44] Make coverage testing opt-in --- {{ cookiecutter.package_name }}/.travis.yml | 6 +++--- {{ cookiecutter.package_name }}/tox.ini | 7 ++++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/{{ cookiecutter.package_name }}/.travis.yml b/{{ cookiecutter.package_name }}/.travis.yml index 0108512e..06cd246b 100644 --- a/{{ cookiecutter.package_name }}/.travis.yml +++ b/{{ cookiecutter.package_name }}/.travis.yml @@ -64,13 +64,13 @@ matrix: stage: Cron tests env: PYTHON_VERSION=3.7 TOXENV=py37-test - # Do a regular build on Linux with Python 3.8. + # Do a regular build on Linux with Python 3.8, with cov # For Linux we use language: python to avoid using conda. - os: linux python: 3.8 - name: Python 3.8 with required dependencies + name: Python 3.8 with required dependencies and measure coverage stage: Initial tests - env: TOXENV=py38-test + env: TOXENV=py38-test-cov # Check for sphinx doc build warnings - os: linux diff --git a/{{ cookiecutter.package_name }}/tox.ini b/{{ cookiecutter.package_name }}/tox.ini index b5ac2869..7ff04353 100644 --- a/{{ cookiecutter.package_name }}/tox.ini +++ b/{{ cookiecutter.package_name }}/tox.ini @@ -1,6 +1,6 @@ [tox] envlist = - py{36,37,38}-test{,-alldeps,-devdeps} + py{36,37,38}-test{,-alldeps,-devdeps}{,-cov} py{36,37,38}-test-numpy{116,117,118} py{36,37,38}-test-astropy{30,40,lts} build_docs @@ -16,7 +16,7 @@ isolated_build = true passenv = HOME WINDIR LC_ALL LC_CTYPE CC CI TRAVIS # Run the tests in a temporary directory to make sure that we don't import -# astropy from the source tree +# this package from the source tree changedir = .tmp/{envname} # tox environments are constructued with so-called 'factors' (or terms) @@ -61,7 +61,8 @@ extras = commands = pip freeze - pytest --pyargs {{ cookiecutter.module_name }} {toxinidir}/docs --cov {{ cookiecutter.module_name }} --cov-config={toxinidir}/setup.cfg {posargs} + !cov: pytest --pyargs {{ cookiecutter.module_name }} {toxinidir}/docs {posargs} + cov: pytest --pyargs {{ cookiecutter.module_name }} {toxinidir}/docs --cov {{ cookiecutter.module_name }} --cov-config={toxinidir}/setup.cfg {posargs} [testenv:build_docs] changedir = docs From c9ff2c4ee016be1d8f6fecb9d40eb56165ab5a94 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 10:09:34 +0000 Subject: [PATCH 38/44] Always use master branch for edit_on_github --- {{ cookiecutter.package_name }}/docs/conf.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/{{ cookiecutter.package_name }}/docs/conf.py b/{{ cookiecutter.package_name }}/docs/conf.py index 16d1e353..a3e9af02 100644 --- a/{{ cookiecutter.package_name }}/docs/conf.py +++ b/{{ cookiecutter.package_name }}/docs/conf.py @@ -156,15 +156,12 @@ # -- Options for the edit_on_github extension --------------------------------- -if eval(setup_cfg.get('edit_on_github')): +if setup_cfg.get('edit_on_github').lower() == 'true': + extensions += ['sphinx_astropy.ext.edit_on_github'] - versionmod = import_module(setup_cfg['name'] + '.version') edit_on_github_project = setup_cfg['github_project'] - if versionmod.release: - edit_on_github_branch = "v" + versionmod.version - else: - edit_on_github_branch = "master" + edit_on_github_branch = "master" edit_on_github_source_root = "" edit_on_github_doc_root = "docs" From f14c67313dd574aa1842f341930745ff66578fb4 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 10:11:56 +0000 Subject: [PATCH 39/44] Use root __version__ instead version --- .../{{ cookiecutter.module_name }}/conftest.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index 5fe7787a..25e85df3 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -21,9 +21,9 @@ def pytest_configure(config): PYTEST_HEADER_MODULES.pop('Pandas', None) PYTEST_HEADER_MODULES['scikit-image'] = 'skimage' - from .version import version + from . import __version__ packagename = os.path.basename(os.path.dirname(__file__)) - TESTED_VERSIONS[packagename] = version + TESTED_VERSIONS[packagename] = __version__ # Uncomment the last two lines in this block to treat all DeprecationWarnings as # exceptions. For Astropy v2.0 or later, there are 2 additional keywords, From 3f9a571c6c40f69fb72c637ad1335759a50da2ce Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 10:15:10 +0000 Subject: [PATCH 40/44] Made pytest-astropy-header optional --- .../conftest.py | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index 25e85df3..dbcd2d38 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -9,21 +9,27 @@ from astropy.tests.pytest_plugins import * # noqa del pytest_report_header else: - from pytest_astropy_header.display import PYTEST_HEADER_MODULES, TESTED_VERSIONS + try: + from pytest_astropy_header.display import PYTEST_HEADER_MODULES, TESTED_VERSIONS + ASTROPY_HEADER = True + except ImportError: + ASTROPY_HEADER = False def pytest_configure(config): - config.option.astropy_header = True + if ASTROPY_HEADER: - # Customize the following lines to add/remove entries from the list of - # packages for which version numbers are displayed when running the tests. - PYTEST_HEADER_MODULES.pop('Pandas', None) - PYTEST_HEADER_MODULES['scikit-image'] = 'skimage' + config.option.astropy_header = True - from . import __version__ - packagename = os.path.basename(os.path.dirname(__file__)) - TESTED_VERSIONS[packagename] = __version__ + # Customize the following lines to add/remove entries from the list of + # packages for which version numbers are displayed when running the tests. + PYTEST_HEADER_MODULES.pop('Pandas', None) + PYTEST_HEADER_MODULES['scikit-image'] = 'skimage' + + from . import __version__ + packagename = os.path.basename(os.path.dirname(__file__)) + TESTED_VERSIONS[packagename] = __version__ # Uncomment the last two lines in this block to treat all DeprecationWarnings as # exceptions. For Astropy v2.0 or later, there are 2 additional keywords, From 9da0a1c1023958e6bd238a7b62b436a4a076a40b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 10:18:45 +0000 Subject: [PATCH 41/44] Added a note about why the conftest.py file needs to be in the source tree --- .../{{ cookiecutter.module_name }}/conftest.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index dbcd2d38..f36cfbdc 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -1,5 +1,8 @@ # This file is used to configure the behavior of pytest when using the Astropy -# test infrastructure. +# test infrastructure. It needs to live inside the package in order for it to +# get picked up when running the tests inside an interpreter using +# packagename.test + import os from astropy.version import version as astropy_version From 2b0155c8b467dedb0a1b912e38fa6189fdf10a2b Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 10:29:24 +0000 Subject: [PATCH 42/44] Added a note on release procedures and conda-forge --- docs/ape17.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/ape17.rst b/docs/ape17.rst index 11c8608b..1c9b9c5b 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -564,3 +564,48 @@ You should also add ``pip-wheel-metadata`` to your ``.gitignore`` file. **Once you are done, if you would like us to help by reviewing your changes, you can open a pull request to your package and mention @astrofrog or @Cadair to ask for a review.** + +Note on releasing your package +------------------------------ + +As a result of the changes above, there are some tweaks to the procedure to +follow for releasing your package - see the `latest instructions +`_ +in the astropy documentation. The two main changes are that you no longer need +to manually update the version number in files, instead the version number +is based on the latest git tag, and in addition the source file should be +built using the `pep517 `_ package. + +Note on conda recipes and pyproject.toml +---------------------------------------- + +While not something you can do until you release your updated package, you will +need to take care to update conda recipes (e.g. in conda-forge) for your +package. In particular, since conda ignores ``pyproject.toml`` files, +you will need to make sure that the build dependencies present in ``pyproject.toml`` +are explicitly listed as build dependencies in the conda recipe. For +packages with compiled extensions and Cython, this would look like:: + + build: + - {{ compiler('c') }} + host: + - pip + - python + - setuptools + - setuptools_scm + - numpy + - cython + - extension-helpers + run: + ... + +while for pure-Python packages you will still need to make sure +``setuptools_scm`` is included in the build dependencies:: + + host: + - pip + - python + - setuptools + - setuptools_scm + run: + ... From 1b812efb0636a263ab652ec64e24b2c9f45e6138 Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 14:11:43 +0000 Subject: [PATCH 43/44] Add missing ASTROPY_HEADER --- .../{{ cookiecutter.module_name }}/conftest.py | 1 + 1 file changed, 1 insertion(+) diff --git a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py index f36cfbdc..672b2733 100644 --- a/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py +++ b/{{ cookiecutter.package_name }}/{{ cookiecutter.module_name }}/conftest.py @@ -11,6 +11,7 @@ if astropy_version < '3.0': from astropy.tests.pytest_plugins import * # noqa del pytest_report_header + ASTROPY_HEADER = True else: try: from pytest_astropy_header.display import PYTEST_HEADER_MODULES, TESTED_VERSIONS From 46622bb32a7451e28cad65d3657953b671a65f0e Mon Sep 17 00:00:00 2001 From: Thomas Robitaille Date: Fri, 31 Jan 2020 14:37:49 +0000 Subject: [PATCH 44/44] Fix missing comma Co-Authored-By: P. L. Lim <2090236+pllim@users.noreply.github.com> --- docs/ape17.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ape17.rst b/docs/ape17.rst index 1c9b9c5b..02807a6f 100644 --- a/docs/ape17.rst +++ b/docs/ape17.rst @@ -580,7 +580,7 @@ Note on conda recipes and pyproject.toml ---------------------------------------- While not something you can do until you release your updated package, you will -need to take care to update conda recipes (e.g. in conda-forge) for your +need to take care to update conda recipes (e.g., in conda-forge) for your package. In particular, since conda ignores ``pyproject.toml`` files, you will need to make sure that the build dependencies present in ``pyproject.toml`` are explicitly listed as build dependencies in the conda recipe. For