Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 30 additions & 11 deletions .github/workflows/test-release-candidate.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
# In addition, the package is built as a wheel on each OS/Python job, and these
# are stored as artifacts to use for your distribution process. There is an
# extra job (disabled by default) which can be enabled to push to Test PyPI.
# If your package is pure-Python, all these wheels are identical and a single
# one will be published. If your package includes compiled extensions, note
# that PyPI does not accept plain linux_* wheels; you will need to build
# manylinux wheels instead (e.g. with cibuildwheel).

name: release candidate tests

Expand Down Expand Up @@ -52,8 +56,6 @@ jobs:
include:
- os: macos-latest
python-version: "3.12"
- os: macos-latest
python-version: "3.12"
env:
OS: ${{ matrix.os }}
PYTHON: ${{ matrix.python-version }}
Expand Down Expand Up @@ -96,10 +98,10 @@ jobs:
env_vars: OS,PYTHON
name: Python ${{ matrix.python-version }} on ${{ runner.os }}

- name: Build wheels
- name: Build wheel
run: |
python -m pip install --upgrade setuptools wheel twine
python setup.py sdist bdist_wheel
python -m pip install --upgrade build
python -m build --wheel

- name: Store wheel artifacts
uses: actions/upload-artifact@v4
Expand All @@ -122,24 +124,41 @@ jobs:
needs: test-build

runs-on: ubuntu-latest
# Uses PyPI Trusted Publishing, which needs no API token. Before enabling
# this job, add this repository and workflow as a trusted publisher in
# your Test PyPI project settings. See
# https://docs.pypi.org/trusted-publishers/
environment: testpypi
permissions:
id-token: write

steps:
- uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Build sdist
run: |
python -m pip install --upgrade build
python -m build --sdist

- name: Download wheel artifacts
uses: actions/download-artifact@v4
with:
name: wheel-*
pattern: wheel-*
path: dist/
merge-multiple: true

- name: Store aggregated wheel artifacts
- name: Store aggregated distribution artifacts
uses: actions/upload-artifact@v4
with:
name: wheels
name: dist
path: dist/*

- name: Publish package to Test PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
user: __token__
password: ${{ secrets.TEST_PYPI_API_TOKEN }}
repository_url: https://test.pypi.org/legacy/
repository-url: https://test.pypi.org/legacy/
2 changes: 1 addition & 1 deletion .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ on:
push:
pull_request:
schedule:
# Scheduled runs always use the default branch
- cron: "0 0 * * 1"
branches: [ $default-branch ]

jobs:
test:
Expand Down
61 changes: 28 additions & 33 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -139,15 +139,15 @@ When creating a new repository from this template, these are the steps to follow

.. highlight:: python

- In ``setup.py``, `L54 <https://github.com/scottclowe/python-template-repo/blob/master/setup.py#L54>`__::
- In ``setup.py``::

exec(read("package_name/__meta__.py"), meta)

- In ``docs/source/conf.py``, `L27 <https://github.com/scottclowe/python-template-repo/blob/master/docs/source/conf.py#L27>`__::
- In ``docs/source/conf.py``::

from package_name import __meta__ as meta # noqa: E402 isort:skip

- In ``.github/workflows/test.yaml``, `L64 <https://github.com/scottclowe/python-template-repo/blob/master/.github/workflows/test.yaml#L64>`__, and ``.github/workflows/test-release-candidate.yaml``, `L90 <https://github.com/scottclowe/python-template-repo/blob/master/.github/workflows/test-release-candidate.yaml#L90>`__::
- In ``.github/workflows/test.yaml`` and ``.github/workflows/test-release-candidate.yaml``::

python -m pytest --cov=package_name --cov-report term --cov-report xml --cov-config .coveragerc --junitxml=testresults.xml

Expand Down Expand Up @@ -240,10 +240,8 @@ For a given block of code, a fixed version of black will always produce the same
However, you should note that different versions of black will produce different outputs.
If you want to upgrade to a newer version of black, you must change the version everywhere it is specified:

- requirements-dev.txt, `L1 <https://github.com/scottclowe/python-template-repo/blob/master/requirements-dev.txt#L1>`__
- .pre-commit-config.yaml, `L14 <https://github.com/scottclowe/python-template-repo/blob/master/.pre-commit-config.yaml#L14>`__,
`L29 <https://github.com/scottclowe/python-template-repo/blob/master/.pre-commit-config.yaml#L29>`__, and
`L48 <https://github.com/scottclowe/python-template-repo/blob/master/.pre-commit-config.yaml#L48>`__
- requirements-dev.txt (``black==...``)
- .pre-commit-config.yaml (the ``rev`` of the black-pre-commit-mirror repo, and the ``black==...`` entries in ``additional_dependencies`` for the blacken-docs and nbqa-black hooks)

.. _black: https://github.com/psf/black

Expand Down Expand Up @@ -277,7 +275,7 @@ The pre-commit stack which comes with the template is highly opinionated, and in

- Code is reformatted to use the black_ style.
Any code inside docstrings will be formatted to black using blackendocs_.
All code cells in Jupyter notebooks are also formatted to black using black_nbconvert_.
All code cells in Jupyter notebooks are also formatted to black (and have their imports sorted and checked with flake8) using nbQA_.

- All Jupyter notebooks are cleared using nbstripout_.

Expand All @@ -296,10 +294,10 @@ The pre-commit stack which comes with the template is highly opinionated, and in
Once it is set up, the pre-commit stack will run locally on every commit.
The pre-commit stack will also run on github with one of the action workflows, which ensures PRs are checked without having to rely on contributors to enable the pre-commit locally.

.. _black_nbconvert: https://github.com/dfm/black_nbconvert
.. _blackendocs: https://github.com/asottile/blacken-docs
.. _flake8: https://gitlab.com/pycqa/flake8
.. _isort: https://github.com/timothycrosley/isort
.. _nbQA: https://github.com/nbQA-dev/nbQA
.. _nbstripout: https://github.com/kynan/nbstripout
.. _PEP-8: https://www.python.org/dev/peps/pep-0008/
.. _pre-commit: https://pre-commit.com/
Expand Down Expand Up @@ -412,18 +410,10 @@ Your package can be installed from source with::

pip install .

or alternatively with::

python setup.py install

But do remember that as a developer, you should install your package in editable mode, using either::
But do remember that as a developer, you should install your package in editable mode, using::

pip install --editable .

or::

python setup.py develop

which will mean changes to the source will affect your installed package immediately without you having to reinstall it.

By default, when the package is installed only the main requirements, listed in ``requirements.txt`` will be installed with it.
Expand All @@ -437,12 +427,21 @@ etc.
Any additional files named ``requirements-EXTRANAME.txt`` will also be collected automatically and made available with the corresponding name ``EXTRANAME``.
Another extra named ``all`` captures all of these optional dependencies.

Your README file is automatically included in the metadata when you use setup.py build wheels for PyPI.
To build an sdist and wheel for distribution on PyPI, use build_::

pip install build
python -m build

Note that invoking ``setup.py`` directly (e.g. ``python setup.py install``, ``python setup.py sdist``) is `deprecated <setuptools-deprecated_>`_ and should not be used.

Your README file is automatically included in the metadata of the built distributions.
The rest of the metadata comes from ``package_name/__meta__.py``.

Our template setup.py file is based on the `example from setuptools documentation <setuptools-setup.py_>`_, and the comprehensive example from `Kenneth Reitz <kennethreitz/setup.py_>`_ (released under `MIT License <https://github.com/kennethreitz/setup.py/blob/master/LICENSE>`__), with further features added.

.. _build: https://build.pypa.io/
.. _kennethreitz/setup.py: https://github.com/kennethreitz/setup.py
.. _setuptools-deprecated: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
.. _setuptools-setup.py: https://setuptools.readthedocs.io/en/latest/setuptools.html#basic-use


Expand All @@ -461,7 +460,7 @@ GitHub features the ability to run various workflows whenever code is pushed to
This is one service of several services that can be used to continually run the unit tests and ensure changes can be integrated together without issue.
It is also useful to ensure that style guides are adhered to

Five workflows are included:
Four workflows are included:

docs
The docs workflow ensures the documentation builds correctly, and presents any errors and warnings nicely as annotations.
Expand All @@ -471,10 +470,6 @@ pre-commit
Runs the pre-commit stack.
Ensures all contributions are compliant, even if a contributor has not set up pre-commit on their local machine.

lint
Checks the code uses the black_ style and tests for flake8_ errors.
If you are using the pre-commit hooks, the lint workflow is superfluous and can be deleted.

test
Runs the unit tests, and pushes coverage reports to Codecov_.
You'll need to sign up at Codecov_ with your GitHub account in order for this integration to work.
Expand All @@ -483,31 +478,31 @@ release candidate tests
The release candidate tests workflow runs the unit tests on more Python versions and operating systems than the regular test workflow.
This runs on all tags, plus pushes and PRs to branches named like "v1.2.x", etc.
Wheels are built for all the tested systems, and stored as artifacts for your convenience when shipping a new distribution.
If your package is pure-Python, these wheels will all be the same; if it includes compiled extensions, you will get a wheel for each platform and Python version.

If you enable the ``publish`` job on the release candidate tests workflow, you can also push built release candidates to the `Test PyPI <testpypi_>`_ server.
For this to work, you'll also need to add your Test `PyPI API token <pypi-api-token_>`_ to your `GitHub secrets <github-secrets_>`_.
The job uses `Trusted Publishing <trusted-publishing_>`_, so no API token is needed.
Instead, you'll need to add your repository as a trusted publisher in your project's settings on Test PyPI, specifying the workflow file ``test-release-candidate.yaml`` and the environment name ``testpypi``.
Checkout the `pypa/gh-action-pypi-publish <pypi-publish_>`_ GitHub action, and `PyPI's guide on distributing from CI <ci-packaging_>`_ for more information on this.
With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since releases on PyPI can not easily be yanked.
If your package includes compiled extensions, note that PyPI will not accept the plain ``linux_*`` wheels built by this workflow, and you should build manylinux wheels instead (for instance with cibuildwheel_).
With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since once a version number has been uploaded to PyPI it can never be reused, even if that release is deleted.

.. _Codecov: https://codecov.io/
.. _ci-packaging: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
.. _github-secrets: https://docs.github.com/en/actions/reference/encrypted-secrets
.. _pypi-api-token: https://pypi.org/help/#apitoken
.. _cibuildwheel: https://cibuildwheel.pypa.io/
.. _pypi-publish: https://github.com/pypa/gh-action-pypi-publish
.. _testpypi: https://test.pypi.org/
.. _trusted-publishing: https://docs.pypi.org/trusted-publishers/


Other CI/CD options
~~~~~~~~~~~~~~~~~~~

Alternative CI/CD services are also available for running tests.

- `Travis CI <https://travis-ci.org/>`_ offers a free trial service.

- `Circle CI <https://circleci.com>`_ is another option with a limited `free option <https://circleci.com/pricing/#build-linux>`_.
- `GitLab CI/CD <https://docs.gitlab.com/ee/ci/>`_ is the natural choice if your repository is hosted on GitLab.

- `Appveyor <https://www.appveyor.com>`_ useful for testing on Windows.
This offers an alternative to GitHub Actions if you need to `build Windows wheel files to submit to PyPI <https://github.com/ogrisel/python-appveyor-demo>`_.
- `CircleCI <https://circleci.com>`_ is another option with a limited `free plan <https://circleci.com/pricing/>`_.

- `Jenkins <https://jenkins.io/>`_ is useful if you want to run your CI test suite locally or on your own private server instead of in the cloud.

Expand Down
62 changes: 1 addition & 61 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,8 @@

import glob
import os
import sys
from shutil import rmtree

from setuptools import Command, find_packages, setup
from setuptools.command.test import test as TestCommand
from setuptools import find_packages, setup


def read(fname):
Expand Down Expand Up @@ -84,58 +81,6 @@ def read(fname):
long_description_content_type = "text/plain"


class PyTest(TestCommand):
"""Support setup.py test."""

def finalize_options(self):
TestCommand.finalize_options(self)
self.test_args = []
self.test_suite = True

def run_tests(self):
import pytest

pytest.main(self.test_args)


class UploadCommand(Command):
"""Support setup.py upload."""

description = "Build and publish the package."
user_options = []

@staticmethod
def status(s):
"""Print things in bold."""
print("\033[1m{0}\033[0m".format(s))

def initialize_options(self):
pass

def finalize_options(self):
pass

def run(self):
try:
self.status("Removing previous builds...")
here = os.path.abspath(os.path.dirname(__file__))
rmtree(os.path.join(here, "dist"))
except OSError:
pass

self.status("Building Source and Wheel (universal) distribution...")
os.system("{0} setup.py sdist bdist_wheel --universal".format(sys.executable))

self.status("Uploading the package to PyPI via Twine...")
os.system("twine upload dist/*")

self.status("Pushing git tags...")
os.system("git tag v{0}".format(meta["version"]))
os.system("git push --tags")

sys.exit()


setup(
# Essential details on the package and its dependencies
name=meta["name"],
Expand Down Expand Up @@ -168,9 +113,4 @@ def run(self):
"Programming Language :: Python :: 3.12",
],
# Could also include keywords, download_url, project_urls, etc.
# Custom commands
cmdclass={
"test": PyTest,
"upload": UploadCommand,
},
)
Loading