supports github releases
Project description
setuptools-github
Quick start
setuptools-github helps to implement a simple project life cycle aimed at delivering packages into PyPI. Basically:
- beta packages are built from a /beta/N.M.O branch generating a project-name-N.M.ObX into PyPI
- tagging with /release/N.M.O a /beta/N.M.O branch commit will release project-name-N.M.O
This integrates well with the standard release logic in PyPI (see example)
NOTE for a pyproject.tom / hatch enabled version of this, please use hatch-ci plugin
Table of Contents
Prerequisites
We make few assumption in the rest of this document:
- the project is hosted under https://www.github.com//
- the github project is named <project-name>
- the main project branch is <master>
- you have coverage.io account https://app.codecov.io/gh//
NOTE: Please change project-name, username and master according to your project.
Install setuptools-github
Install the package with:
pip install setuptools-github
or
conda install -c conda-forge setuptools-github
Add secrets
Github stores secrets for the <project-name> repository under:
https://github.com///settings/secrets/actions
These are the needed secrets for the PyPI index and codecov services:
- TWINE_PASSWORD
- TWINE_USERNAME
- CODECOV_TOKEN
Project setup
Layout
We assume this layout:
project-name/
├── .github
│ └── workflows
│ ├── beta.yml
│ ├── master.yml
│ └── tags.yml
├── pyproject.toml
├── src
│ └── project_name <- project name
│ └── __init__.py <- initfile
└── tests <- tests (pytest)
├── conftest.py
└── requirements.txt <- requirement file for tests
- it is rooted under <project-name>/src directory
- the python package is project_name
- an initfile is stored under project-name/src/project_name/init.py
- tests are stored under project-name/tests
- a *requirements.txt file for tests is under project-name/tests/requirements.txt
NOTE: You need to change these values to match your project
Setup the initfile
Create a new src/project_name/__init__.py
file to store the package information:
__version__ = "N.M.O" # replace N, M and O with numerical values (eg. 0.0.0)
__hash__ = "" # leave this empty
Fix the setup.py file:
from setuptools_github import tools
initfile = pathlib.Path(__file__).parent / "project_name/__init__.py"
setup(
name="project-name",
version=tools.update_version(initfile, os.getenv("GITHUB_DUMP")),
...
Copy over the github workflow files:
Most likely you might need to change tests/requirements.txt
file.
THAT IS ALL! Now when commit to the master branch, this will trigger the github action to run tests and quality checks on the code (see the Rationale section below).
Working with the master branch
Every time there's a commit on the master branch, this will trigger the workflow under ./github/workflows/master.yml:
- Runs mypy on src/
- Runs ruff on src/
- Run all tests under tests/
On completion static and dynamic tests are supported.
Setup the beta/N.M.O branch
In order to prepare for a release a new beta/N.M.O branch should be created:
python -m setuptools_github.script make-beta src/project_name/__init__.py
or
setuptools-github make-beta src/project_name/__init__.py
Every commit on beta/N.M.O branch ASSUMING Secrets have been set properly:
- Runs mypy on src/
- Runs ruff on src/
- Run all tests under tests/
- Run coverage on tests/
- Send the coverage result into coverage
- Create a new wheel package under dist/
- (on success) Send the new wheels package-N.M.O.bX to PyPI
NOTE: the name project-N.M.O.bX contains the X: this is an incrementing counter set during build. This means project-N.M.O.bX < project-N.M.O allowing the correct package ordering.
Release the project N.M.O
To release an official package for project-N.M.O from the beta/N.M.O branch:
python -m setuptools_github.script micro src/project_name/__init__.py
or
setuptools-github make-beta micro src/project_name/__init__.py
This will tag the HEAD on beta/N.M.O branch with the release/N.M.O tag and increment the initfile with the next version N.M.O+1 (using micro).
Once done, you'll need to push it the tag.
git push release/N.M.O
This will:
- trigger a CI build that will create the project-name-N.M.O
- Create a new wheel package under dist/
- (on success) Send the new wheels project-N.M.O to PyPI
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for setuptools-github-0.3.1b66.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a3b75614d599aa82e494110d3fa85ea2388f3f828a9a0646f56a1e44537fd295 |
|
MD5 | a7df4f58076d8510686e84d72a3f5a58 |
|
BLAKE2b-256 | 67d35911887d48fe9157ce8af4789b2c050feae24eab169644dbc0666456b0af |
Hashes for setuptools_github-0.3.1b66-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a47dc44277464888b1d0af39057267d68240c63aa912735d5f2d3938c7682378 |
|
MD5 | c79a4cdb46388cff0f5c4c99c2534001 |
|
BLAKE2b-256 | 916dd9ed604834948c2f93c95806771f84e3af4002946b20143ef3ab4f78b02b |