# Sample PyPI package + GitHub Actions + Versioneer
This template aims to automate the tedious and error-prone steps of tagging/versioning, building and publishing new package versions. This is achieved by syncing git tags and versions with Versioneer, and automating the build and release with GitHub Actions, so that publishing a new version is as painless as:
```console
$ git tag vX.Y.Z && git push --tags
```
The following guide assumes familiarity with `setuptools` and PyPI. For an introduction to Python packaging, see the references at the bottom.
## How to use this template
1. Click on the *Use this template* button to get a copy of this repository.
1. Rename *src/sample_package* folder to your package name — *src/* is where your package must reside.
1. Go through each of the following files and rename all instances of *sample-package* or *sample_package* to your package name. Also update the package information such as author names, URLs, etc.
1. setup.py
1. pyproject.toml
1. \_\_init\_\_.py
1. Install `versioneer` and `tomli`, and run `versioneer`:
```console
$ pip install tomli
$ pip install versioneer
$ versioneer install
```
Then *commit* the changes produced by `versioneer`. See [here](https://github.com/python-versioneer/python-versioneer/blob/master/INSTALL.md) to learn more.
1. Setup your PyPI credentials. See the section *Saving credentials on Github* of [this guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/). You should use the variable names `TEST_PYPI_API_TOKEN` and `PYPI_API_TOKEN` for the TestPyPI and PyPI tokens, respectively. See *.github/workflows/release.yaml*.
You are all set! It should now be possible to run `git tag vX.Y.Z && git push --tags` to automatically version, build and publish a new release to PyPI.
Finally, it is a good idea to [configure tag protection rules](https://docs.github.com/en/enterprise-server@3.8/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) in your repository.
## References
- Python packaging guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/
- ...and how things are changing: https://snarky.ca/what-the-heck-is-pyproject-toml/ — in particular, note that while *pyproject.toml* seems to be the future, currently Versioneer still depends on *setup.py*.
- Versioneer: https://github.com/python-versioneer/python-versioneer
- GitHub Actions: https://docs.github.com/en/actions
Raw data
{
"_id": null,
"home_page": "https://github.com/chanshing/sample-package",
"name": "sample-package-chanshing",
"maintainer": "Shing Chan",
"docs_url": null,
"requires_python": ">=3.8, <4",
"maintainer_email": "cshing.m@gmail.com",
"keywords": "example,setuptools,versioneer",
"author": "Shing Chan",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/a9/a8/976aea4218ca9879c2135b6e41798280c0a6a621cffe647bdccd5d9af468/sample-package-chanshing-0.0.0.post1.tar.gz",
"platform": null,
"description": "# Sample PyPI package + GitHub Actions + Versioneer\n\nThis template aims to automate the tedious and error-prone steps of tagging/versioning, building and publishing new package versions. This is achieved by syncing git tags and versions with Versioneer, and automating the build and release with GitHub Actions, so that publishing a new version is as painless as:\n\n```console\n$ git tag vX.Y.Z && git push --tags\n```\n\nThe following guide assumes familiarity with `setuptools` and PyPI. For an introduction to Python packaging, see the references at the bottom.\n\n## How to use this template\n\n1. Click on the *Use this template* button to get a copy of this repository.\n1. Rename *src/sample_package* folder to your package name — *src/* is where your package must reside.\n1. Go through each of the following files and rename all instances of *sample-package* or *sample_package* to your package name. Also update the package information such as author names, URLs, etc.\n 1. setup.py\n 1. pyproject.toml\n 1. \\_\\_init\\_\\_.py\n1. Install `versioneer` and `tomli`, and run `versioneer`:\n\n ```console\n $ pip install tomli\n $ pip install versioneer\n $ versioneer install\n ```\n Then *commit* the changes produced by `versioneer`. See [here](https://github.com/python-versioneer/python-versioneer/blob/master/INSTALL.md) to learn more.\n1. Setup your PyPI credentials. See the section *Saving credentials on Github* of [this guide](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/). You should use the variable names `TEST_PYPI_API_TOKEN` and `PYPI_API_TOKEN` for the TestPyPI and PyPI tokens, respectively. See *.github/workflows/release.yaml*.\n\nYou are all set! It should now be possible to run `git tag vX.Y.Z && git push --tags` to automatically version, build and publish a new release to PyPI.\n\nFinally, it is a good idea to [configure tag protection rules](https://docs.github.com/en/enterprise-server@3.8/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) in your repository.\n\n## References\n- Python packaging guide: https://packaging.python.org/en/latest/tutorials/packaging-projects/\n - ...and how things are changing: https://snarky.ca/what-the-heck-is-pyproject-toml/ — in particular, note that while *pyproject.toml* seems to be the future, currently Versioneer still depends on *setup.py*.\n- Versioneer: https://github.com/python-versioneer/python-versioneer\n- GitHub Actions: https://docs.github.com/en/actions\n",
"bugtrack_url": null,
"license": "See LICENSE file.",
"summary": "An example Python project",
"version": "0.0.0.post1",
"project_urls": {
"Download": "https://github.com/chanshing/sample-package",
"Homepage": "https://github.com/chanshing/sample-package"
},
"split_keywords": [
"example",
"setuptools",
"versioneer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e30af7c37511aa1c35382b5e157c072d6542bd8ff24f1ab1c8536cdac2a9e4c3",
"md5": "f4445d710290aae45b998f9c342aa205",
"sha256": "cb9504cc6a4184e126dbb7fdc6981302f7f0bbaa0bbb6c3744ffa839c17632d2"
},
"downloads": -1,
"filename": "sample_package_chanshing-0.0.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4445d710290aae45b998f9c342aa205",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8, <4",
"size": 4389,
"upload_time": "2023-07-19T14:47:05",
"upload_time_iso_8601": "2023-07-19T14:47:05.918531Z",
"url": "https://files.pythonhosted.org/packages/e3/0a/f7c37511aa1c35382b5e157c072d6542bd8ff24f1ab1c8536cdac2a9e4c3/sample_package_chanshing-0.0.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9a8976aea4218ca9879c2135b6e41798280c0a6a621cffe647bdccd5d9af468",
"md5": "32a853613ccb088db8bf549d0c82956f",
"sha256": "750c1a9b373d9a2f683e48c0c9f98f0e5c085a2081fd54865d1379c56827fc02"
},
"downloads": -1,
"filename": "sample-package-chanshing-0.0.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "32a853613ccb088db8bf549d0c82956f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8, <4",
"size": 24765,
"upload_time": "2023-07-19T14:47:06",
"upload_time_iso_8601": "2023-07-19T14:47:06.810364Z",
"url": "https://files.pythonhosted.org/packages/a9/a8/976aea4218ca9879c2135b6e41798280c0a6a621cffe647bdccd5d9af468/sample-package-chanshing-0.0.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-19 14:47:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chanshing",
"github_project": "sample-package",
"github_not_found": true,
"lcname": "sample-package-chanshing"
}
JSON
