Merge pull request #358 from NLeSC/345_build_module

Author: sjvrijn

README.md

@@ -135,8 +135,6 @@ my-python-project/
 ├── pyproject.toml
 ├── README.dev.md
 ├── README.md
-├── setup.cfg
-├── setup.py
 ├── sonar-project.properties
 └── tests
     ├── __init__.py

tests/test_project.py

@@ -80,7 +80,7 @@ def test_tox(baked_with_development_dependencies, project_env_bin_dir):
 
 
 def test_subpackage(baked_with_development_dependencies, project_env_bin_dir):
-    """Test if subpackages end up in sdist and bdist_wheel distributions"""
+    """Test if subpackages end up in (wheel) distributions"""
     project_dir = baked_with_development_dependencies
     bin_dir = project_env_bin_dir
     subpackage = (project_dir / 'my_python_package' / 'mysub')
@@ -91,9 +91,14 @@ def test_subpackage(baked_with_development_dependencies, project_env_bin_dir):
     subsubpackage.mkdir()
     (subsubpackage / '__init__.py').write_text('FOO = "bar"\n', encoding="utf-8")
 
-    # sdist and bdist_wheel both call build command to create build/ dir
-    # So instead of looking in distribution archives we can look in build/ dir
-    result = run([f'{bin_dir}python', '-m', 'build', '--sdist', '--wheel'], project_dir)
+    # Note: we pass --wheel explicitly, because wheel has a useful side-effect
+    # of leaving a build directory after building that we can check for its
+    # contents in the asserts below. However, be aware that this behavior is
+    # not guaranteed to stay and is in fact a known bug / PEP-violation!
+    # See https://github.com/pypa/wheel/issues/447. Also, by passing --wheel
+    # explicitly (although by default build already builds a wheel as well),
+    # we omit the sdist being built, saving some seconds.
+    result = run([f'{bin_dir}python', '-m', 'build', '--wheel'], project_dir)
     assert result.returncode == 0
     assert (project_dir / 'build' / 'lib' / 'my_python_package' / 'mysub' / '__init__.py').exists()
     assert (project_dir / 'build' / 'lib' / 'my_python_package' / 'mysub' / 'mysub2' / '__init__.py').exists()

{{cookiecutter.directory_name}}/.github/workflows/build.yml

@@ -36,7 +36,7 @@ jobs:
       - name: Run unit tests
         run: python -m pytest -v
       - name: Verify that we can build the package
-        run: python setup.py sdist bdist_wheel
+        run: python -m build
 
   lint:
     name: Linting build

{{cookiecutter.directory_name}}/.github/workflows/documentation.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python 3.9
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v3
         with:
           python-version: 3.9
       - name: Python info

{{cookiecutter.directory_name}}/README.dev.md

@@ -138,35 +138,23 @@ This section describes how to make a release in 3 parts:
 
 ### (2/3) PyPI
 
-In a new terminal, without an activated virtual environment or an env directory:
+In a new terminal:
 
 ```shell
-# prepare a new directory
+# OPTIONAL: prepare a new directory with fresh git clone to ensure the release
+# has the state of origin/main branch
 cd $(mktemp -d {{ cookiecutter.package_name }}.XXXXXX)
-
-# fresh git clone ensures the release has the state of origin/main branch
 git clone {{ cookiecutter.repository }} .
 
-# prepare a clean virtual environment and activate it
-python -m venv env
-source env/bin/activate
-
-# make sure to have a recent version of pip and setuptools
-python -m pip install --upgrade pip setuptools
-
-# install runtime dependencies and publishing dependencies
-python -m pip install --no-cache-dir .
-python -m pip install --no-cache-dir .[publishing]
-
-# clean up any previously generated artefacts
-rm -rf {{ cookiecutter.package_name }}.egg-info
-rm -rf dist
+# make sure to have a recent version of pip and the publishing dependencies
+python -m pip install --upgrade pip
+python -m pip install .[publishing]
 
 # create the source distribution and the wheel
-python setup.py sdist bdist_wheel
+python -m build
 
 # upload to test pypi instance (requires credentials)
-twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+python -m twine upload --repository testpypi dist/*
 ```
 
 Visit
@@ -183,7 +171,7 @@ python -m venv env
 source env/bin/activate
 
 # make sure to have a recent version of pip and setuptools
-python -m pip install --upgrade pip setuptools
+python -m pip install --upgrade pip
 
 # install from test pypi instance:
 python -m pip -v install --no-cache-dir \
@@ -198,7 +186,7 @@ Then upload to pypi.org with:
 ```shell
 # Back to the first terminal,
 # FINAL STEP: upload to PyPI (requires credentials)
-twine upload dist/*
+python -m twine upload dist/*
 ```
 
 ### (3/3) GitHub

{{cookiecutter.directory_name}}/pyproject.toml

@@ -43,7 +43,7 @@ version = "{{ cookiecutter.version }}"
 
 [project.optional-dependencies]
 dev = [
-    "build",
+    "build",  # build is not only used in publishing (below), but also in the template's test suite
     "bump2version",
     "coverage [toml]",
     "pytest",
@@ -56,6 +56,7 @@ dev = [
     "myst_parser",
 ]
 publishing = [
+    "build",
     "twine",
     "wheel",
 ]