Semantic Release Python (with Poetry Support)
> **A semantic-release plugin for PyPi.org that supports both regular and Poetry projects**
## Table of Contents
- [Overview](#overview)
- [Requirements](#requirements)
- [Developer Requirements](#developer-requirements)
- [Lifecycle Hooks](#lifecycle-hooks)
- [Environment Variables](#environment-variables)
- [Options](#options)
- [Examples](#examples)
- [Basic Example Using `setup.cfg`](#basic-example-using-setupcfg)
- [Example Using Poetry](#example-using-poetry)
- [Post-Install Hook](#post-install-hook)
- [Running Without Poetry](#running-without-poetry)
- [Bypassing the Post-Install Hook](#bypassing-the-post-install-hook)
- [Contributing](#contributing)
- [License](#license)
## Overview
**Semantic Release Python** is a [semantic-release](https://semantic-release.gitbook.io/semantic-release/) plugin that brings support for managing the publication of PyPi packages. It supports traditional Python projects with a `setup.cfg` file and also **supports Poetry projects**.
This plugin requires both Python 3 and a recent version of Node.js to be present. After installing the plugin, a few supporting Python packages will automatically be installed into a `virtualenv` located at `.venv`. Using a virtualenv helps to prevent incompatibilities with your current installed software. Before you run any configuration that contains, you must source the virtualenv by running `. venv/bin/activate` or install the dependencies in this project's `requirements.txt` through other means prior to utilizing the plugin.
## Requirements
If you are simply including this library in your project, all you need is a recent version of Node.js. **[Node.js >14.18.0](repository.project.node)** is sometimes required and is the only version range we actively support. Albeit, it is highly probable that lower versions will work as well depending on the requirements that this project imports.
### Developer Requirements
The following versions of Node.js and Python are required for development:
- **[Node.js >14.18.0](repository.project.node)**
- **[Python >3.10.0](repository.project.python)**
Other versions may work, but only the above versions are supported. Most development dependencies are installed automatically by our `Taskfile.yml` set-up (even Node.js and Python). Run `bash start.sh` to install **[Bodega](https://github.com/ProfessorManhattan/Bodega)** (an improved fork of [go-task](https://github.com/go-task/task)) and run the initialization sequence. The taskfiles will automatically install dependencies as they are needed, based on what development tasks you are running. For more information, check out the [CONTRIBUTING.md](https://github.com/ProfessorManhattan/semantic-release-python/blob/main/docs/CONTRIBUTING.md) or simply run:
```shell
npm run help
```
`npm run help` will ensure Bodega is installed and then open an interactive dialog where you can explore and learn about various developer commands.
## Lifecycle Hooks
| Step | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verifyConditions` | - Verify the environment variable `PYPI_TOKEN`
- Verify `PYPI_TOKEN` is authorized to publish on the specified repository
- If the project is not a [Poetry](https://python-poetry.org/) project (i.e. it has a `setup.cfg`), then verify that `version` is not set inside `setup.py` (version will be set in `setup.cfg`)
- If it is not Poetry project, check if the packages `setuptools`, `wheel` and `twine` are installed
- If it is a Poetry project (i.e. contains `pyproject.toml` instead of `setup.cfg`), ensure Poetry is installed
|
| `prepare` | Update the version in `setup.cfg` and create the distribution packages if it is not a Poetry project. But, if it is a Poetry project, then just update the version. |
| `publish` | Build the project if it is a Poetry project and then publish the Python package to the `PYPI_REPO_URL` |
## Environment Variables
| Variable | Description | Required | Default |
| --------------- | -------------------------------------------------------------------------------------------------------- | -------- | --------------------------------- |
| `PYPI_TOKEN` | [API token](https://test.pypi.org/help/#apitoken) for PyPi (or password if `PYPI_USERNAME` is specified) | true |
| `PYPI_USERNAME` | PyPi username (only required if you are using a password instead of an API token) | false | `__token__` |
| `PYPI_REPO_URL` | URL of remote Python package repository | false | `https://upload.pypi.org/legacy/` |
## Options
| Option | Type | Default | Description |
| ------------- | ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setupPy` | string | `./setup.py` | Location of `setup.py` (or any file in the root of the project for a Poetry project) |
| `distDir` | string | `dist` | Directory to put the source distribution archive(s) in, relative to the directory of `setup.py` (this variable is not used in Poetry projects) |
| `repoUrl` | string | `https://upload.pypi.org/legacy/` | The repository to upload the package to |
| `pypiPublish` | boolean | `true` | Whether to publish the Python package to the PyPi registry. If false, the package version will still be updated. |
| `gpgSign` | boolean | `false` | Whether to sign the package using GPG. A valid PGP key must already be installed and configured on the host. Our implementation for Poetry projects currently do not support this feature. |
| `gpgIdentity` | string | `null` | When `gpgSign` is true, set the GPG identify to use when signing files. Leave empty to use the default identity. Our implementation for Poetry projects currently do not support this feature. |
## Examples
This plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration). For a full example of a configuration used for multiple project types, check out the [shareable configuration we use for all our of projects](https://github.com/ProfessorManhattan/release-config).
### Basic Example Using `setup.cfg`
```json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"semantic-release-python"
]
}
```
### Example Using Poetry
```json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-python",
{
"setupPy": "./pyproject.toml"
}
]
]
}
```
## Post-Install Hook
Whenever this package is installed, it will run a bash script that ensures [Bodega](https://github.com/ProfessorManhattan/Bodega) is installed and then install dependencies using a task defined in the Taskfiles included in the modules source. It attempts to use Poetry if it is installed but falls back to a regular venv if Poetry is not available.
Using Poetry might be the easier route. It will be easier to figure out exactly how this plugin can be used (by looking at [semantic-release-config](https://github.com/ProfessorManhattan/semantic-release-config) and our [`semantic-release` task](https://gitlab.com/megabyte-labs/common/shared/-/blob/master/common/.config/taskfiles/publish/Taskfile.yml) which is run by Bodega, a fork of [go-task/task](https://github.com/go-task/task)).
### Running Without Poetry
If you do not use Poetry, then before running semantic-release you should ensure that you activate the virtual environment that the post-install hook should automatically install (as long as Python 3 is installed). You can activate the Python virtual environment by running:
```shell
. .venv/bin/activate
```
After you run that, you enter a shell where you will have access to the dependencies that the post-install hook installed. You can then run the semantic-release CLI.
### Bypassing the Post-Install Hook
There may be some cases where you do not want the dependencies to be installed automatically by the plugin. For instance, you may want to bypass the post-install hook when running in a CI environment where it does not make a difference when using Python virtual environments. To disable the post-install hook, run the following somewhere before the installation:
```shell
export SEMANTIC_PYTHON_POST_INSTALL=false
```
If `SEMANTIC_PYTHON_POST_INSTALL` is set to `false`, then the post-install hook will be skipped. This allows you to permit other NPM packages to run post-install hooks without having to disable all scripts by running `npm i --ignore-scripts`.
## Contributing
Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/ProfessorManhattan/semantic-release-python/issues). If you would like to contribute, please take a look at the [contributing guide](https://github.com/ProfessorManhattan/semantic-release-python/blob/master/docs/CONTRIBUTING.md).
Sponsorship
Dear Awesome Person,
I create open source projects out of love. Although I have a job, shelter, and as much fast food as I can handle, it would still be pretty cool to be appreciated by the community for something I have spent a lot of time and money on. Please consider sponsoring me! Who knows? Maybe I will be able to quit my job and publish open source full time.
Sincerely,
**_Brian Zalewski_**
## License
Copyright © 2020-2021 [Megabyte LLC](https://megabyte.space). This project is [MIT](https://gitlab.com/megabyte-labs/npm/plugin/semantic-release-python/-/blob/master/LICENSE) licensed.
