Metadata-Version: 2.5
Name: simple-releaser
Version: 0.4.0
Summary: A command-line tool for preparing and publishing Python package releases.
Project-URL: repository, https://codeberg.org/newbery/simple-releaser
Project-URL: issues, https://codeberg.org/newbery/simple-releaser/issues
Author-email: Ricardo Newbery <ric@digitalmarbles.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.11
Requires-Dist: build<2.0.0,>=1.6.0
Requires-Dist: markdown-it-py<5.0.0,>=4.0.0
Requires-Dist: oslex<3.0.0,>=2.0.0
Requires-Dist: packaging<27.0,>=25.0
Requires-Dist: python-dotenv<2.0.0,>=1.1.0
Requires-Dist: rich-argparse<2.0.0,>=1.7.0
Requires-Dist: rich<15.0.0,>=14.0.0
Requires-Dist: twine<8.0.0,>=7.0.0
Requires-Dist: urllib3<3.0.0,>=2.8.0
Description-Content-Type: text/markdown

> ⚠️ **Warning** ⚠️   
> Simple Releaser is beta software and still being tested.
> Expect rough edges and breaking changes.


# Simple Releaser

Simple Releaser is a configurable command-line tool for validating, building,
tagging, and publishing Python package releases.

The PyPI distribution is named `simple-releaser`. Once installed, it can be
invoked as either `simple-releaser` or `release`.

Simple Releaser grew out of a direct copy of the release workflow used by the
[QRtsy Project](https://codeberg.org/newbery/qrtsy), which was itself just
a copy of similar tooling that I've used in several other projects. This version
of the tool has since been updated significantly to generalize it in order to
accommodate different release workflows. While Simple Releaser is very configurable,
it is deliberately designed to be ***simple*** and is unlikely to grow much beyond
this initial vision. If you've got more complex needs, you may wish to
[consider some alternatives](https://codeberg.org/newbery/simple-releaser/src/branch/master/docs/alternative-release-tools.md).


## Project assumptions

Run Simple Releaser from a directory containing the releaser configuration
(`releaser.toml` by default). This directory may also be the project root,
or the releaser configuration may point at a separate project directory.

The project being released is expected to have:

- Project configuration, including name and version, in `pyproject.toml`.
- A changelog file named `CHANGELOG.md`, with `Unreleased` and version sections.
- A Git repo with an `origin` remote (or configure `repo_remote` to select
  a different remote).

When publishing a repository release, the project is also expected to have:

- A repository hosted by Codeberg, Forgejo, Gitea, GitHub, or GitLab,
  including supported self-hosted instances.
- Publication credentials configured through the publisher, environment,
  or system keyring, as appropriate for the destination.


## Installation

A convenient way to install Simple Releaser as a standalone command-line
tool is with [`pipx`](https://pipx.pypa.io/):

```console
pipx install simple-releaser
```

Once installed, Simple Releaser can then be invoked as either:

```console
release
```

or:

```console
simple-releaser
```


## Commands

The available CLI commands are:

```console
$ release --help

Simple Releaser

Validate, build, and publish Python project releases.

Usage:
  release [options] COMMAND [arguments]

Main command:
  run              Run the complete release workflow

Release steps:
  validate         Validate release readiness
  check            Run configured project quality checks
  build            Build and archive the current version
  tag              Create and push the release tag
  to_repo          Publish the repository release
  to_index         Publish distributions to a package index

Setup and inspection:
  init             Initialize Simple Releaser configuration
  show             Show resolved configuration and project information
  is_clean         Check for a clean Git repository
  auth             Manage publication authentication
  help             Show help for Simple Releaser or a command

Options:
  -h, --help       show this help message and exit
  -V, --version    show the version number and exit
  --dry-run        show what would be done without making changes
```


### Initialization

Simple Releaser requires a configuration file in the current working directory.
By default it is named `releaser.toml`. To use a different filename, set the
`RELEASER_CONFIG` environment variable to the desired name.

Run `release init` from the directory where the releaser configuration should
live:

```console
release init
```

If that directory contains the `pyproject.toml` for a project, Simple Releaser
creates a minimal `releaser.toml` for that project. Otherwise it prompts for
the project directory and then records the given `project_path` in the generated
configuration. Relative paths are used when possible. An existing releaser
configuration is never overwritten.

The `init` command also creates a text file with configuration examples that
is named with the same prefix as the releaser configuration file so both files
will always be generated near each other. Default is `releaser-examples.txt`.


## Configuration

While the existence of a configuration file is required, its contents are optional
unless overrides to default configuration are desired. An exception is when
the current working directory does not also contain the project's `pyproject.toml`.
If the project lives elsewhere, `project_path` is required and must identify a
directory containing `pyproject.toml`. Relative paths are resolved from the
directory containing the releaser configuration; absolute paths are also
accepted. In this case, the minimum configuration might be:

```toml
project_path = "../my-project"
```

Set `auto_confirm = true` at the top level to allow package-index publication
without an interactive confirmation prompt, for example in a deliberately
unattended release workflow. It defaults to `false`.

By default, `subprocess_output = "live"` lets external commands display output
as they run, including progress bars and error messages. Set
`subprocess_output = "errors"` to hide successful subprocess output and show
captured diagnostics only when a command fails. In `errors` mode, Simple
Releaser redacts managed authentication tokens from those diagnostics. In
`live` mode, external tools write directly to the terminal and are responsible
for protecting any credentials they use. Simple Releaser's own status messages
are displayed in either mode.

Build artifacts are archived under `_releases/<version>/` beside the releaser
configuration file. If `_releases` is in the project directory, Simple Releaser
creates a `.gitignore` file to exclude it from Git. Set
`gitignore_releases = false` at the top level to disable this behavior.


### Configuration default values

For reference, the default values for the configuration settings are as follows:

```toml
project_path = "."
tag_prefix = "v"
auto_confirm = false
subprocess_output = "live"
gitignore_releases = true
index_upload_url = "https://upload.pypi.org/legacy/"  # PyPI default

[commands]
check = ""
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload {dist_dir}/*"
run = "validate check build tag to_repo to_index"

[auth]
keyring = "keyring"

[auth.repo]
source = "environment"

[auth.index]
source = "publisher"
```

See later sections of this readme for more details about each of these settings.
See the examples file generated by `init` for authentication settings and examples.


### Configurable `commands`

The `[commands]` section currently supports `check`, `build`, `publish`, and `run`.
A value may be either a shell-like string or a TOML array of argument strings.
The following forms are equivalent:

```toml
check = "uv run pytest"
check = ["uv", "run", "pytest"]
```

Quoting in a string may be used to preserve spaces within one argument:

```toml
check = 'python -c "print(1 + 1)"'
```

Command strings use POSIX quoting on macOS/Linux and Windows argument quoting
on Windows. Simple Releaser executes commands directly without a shell, so shell
features such as pipes or command chaining require an explicitly invoked shell.
For complex arguments, TOML arrays avoid platform-specific quoting. For example,
on Windows:

```toml
[commands]
check = ['C:\Program Files\Python\python.exe', "-m", "pytest"]
```

An empty string or empty array disables the task associated with that configured
command. For example:

```toml
[commands]
check = ""    # disables 'check' task
build = ""    # disables 'build' task
publish = ""  # disables 'to_index' task
run = ""      # disables the entire pipeline
```


### Configuring `check`

The configured `check` command is the project's generic handoff to its own
release-readiness policy. Tests, linters, type checks, documentation checks,
project-specific validation, or any other prerequisite can live behind this one
command. Since that policy is project-specific, `check` is disabled by default
and must be customized for the project:

```toml
[commands]
check = ""
```

A useful pattern is to point `check` at a project task runner, so the same
`check` task can be used during development, in CI, and during a release
without duplicating workflow configuration.

The Simple Releaser project [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food)
its own tooling for releases of itself and uses [Poe the Poet](https://poethepoet.natn.io/)
as the task runner for its `check` task. This is defined in the project's
`releaser.toml` like so:

```toml
[commands]
check = "hatch run poe check"
```
See the project's `pyproject.toml` for the `poe check` task configuration to see
what it runs as part of its pre-release project check.

[Poe the Poet](https://poethepoet.natn.io/) is optional. See [Project Checks and Task Runners](https://codeberg.org/newbery/simple-releaser/src/branch/master/docs/task-runners.md)
for a discussion of various other task runners that can be used for this.


### Configuring `build` and `publish`

By default, Simple Releaser builds its release artifacts with [build](https://build.pypa.io)
and publishes with [twine](https://twine.readthedocs.io):

```toml
[commands]
build = "{python} -m build --outdir {output}"
publish = "{python} -m twine upload {dist_dir}/*"
```

Custom build and publish commands may also use `{python}`, which expands to the
absolute path of the Python interpreter running Simple Releaser. This lets
an override deliberately use a tool installed alongside Simple Releaser rather
than whichever `python` happens to be on `PATH`.

The `{output}` placeholder in `build` is replaced with the temporary staging
`dist/` directory where the build command must write its distributions. A
non-empty custom build command must include `{output}`. Publish commands may use
`{release_dir}` for the release archive root and `{dist_dir}` for its distribution
subdirectory.

Custom publish commands may use `{index_url}` to insert the configured upload URL
or specify the destination directly in the command. Otherwise, Simple Releaser
attempts to automatically identify the appropriate environment variable for the
publisher and uses it to direct uploads to the configured package index.
See `releaser-examples.txt` for examples.

Use `releaser show` to inspect the package index destination and urls selected
by Simple Releaser. The default package index is PyPI but this can be overridden
via the `index_upload_url` config setting.

For TestPyPI, use its upload URL (and use a separate TestPyPI token):

```toml
index_upload_url = "https://test.pypi.org/legacy/"
```

For a custom index, provide its HTTPS upload endpoint. Project-page and
PyPI-compatible JSON-API endpoints are optional. The optional JSON-API endpoint
is used to check whether the release was already published to the index.

```toml
index_upload_url = "https://packages.example.com/legacy/"
# index_project_base_url = "https://packages.example.com/project"
# index_api_base_url = "https://packages.example.com/pypi"  # only for compatible JSON APIs
```


The default build and publish commands work with most standards-compliant build
backends declared in the `[build-system]` section of a project's `pyproject.toml`
configuration. Users that prefer their project-management tool's native build
and publish commands can override the defaults. Typical equivalents are:

```toml
# Poetry
build = "poetry build --output {output}"
publish = "poetry publish --repository releaser --dist-dir {dist_dir}"

# Hatch
build = "hatch build {output}"
publish = "hatch publish --no-prompt {dist_dir}"

# uv
build = "uv build --no-sources --out-dir {output}"
publish = "uv publish {dist_dir}/*"

# PDM
build = "pdm build --dest {output}"
publish = "pdm publish --no-build --dest {dist_dir}"
```

For these publishers, Simple Releaser automatically supplies the configured
upload URL using the following environment variables:

| Publisher | Auto-detected environment variable | Notes |
| ---       | ---                                | --- |
| Twine     | `TWINE_REPOSITORY_URL`             | URL takes precedence over `.pypirc` |
| Poetry    | `POETRY_REPOSITORIES_RELEASER_URL` | Command selects `--repository releaser` |
| Hatch     | `HATCH_INDEX_REPO`                 | Upload URL for the publisher |
| uv        | `UV_PUBLISH_URL`                   | Upload URL for the publisher |
| PDM       | `PDM_PUBLISH_REPO`                 | Upload URL for the publisher |

For an unrecognized publisher, configure `publish_index_env` to the environment
variable expected by the publisher, or use `{index_url}` directly in the command,
or include the destination explicitly in the custom command like so:

```toml
[commands]
publish = "uv publish --publish-url https://packages.example.com/legacy/ {dist_dir}/*"
```

This last "explicit-url-in-command" option disables Simple Releaser's index-aware
verification features so it's recommended to only use this option as a last resort.

The default PyPI publisher uses Twine's normal authentication mechanisms, including
keyring, `.pypirc`, and `TWINE_*` environment variables. PyPI and TestPyPI have
separate accounts and tokens; repository-specific `.pypirc` or keyring entries
are the clearest way to keep those credentials distinct. For repository-host
settings, Simple Releaser checks the process environment first and then falls
back to the `.env` file beside the releaser configuration.

Run `release auth check` to check whether configured tokens can be retrieved
and meet basic format requirements. This does not verify token validity against
the destination service or check publication permissions. Publisher-managed
tokens cannot be retrieved directly by Simple Releaser, so they cannot be checked.

To store a token with Simple Releaser, install the `keyring` CLI separately,
then run `release auth set {repo,index}`. This command stores the token and then
prints a configuration snippet to add to `releaser.toml`.
`release auth delete {repo,index}` deletes the token from the keyring.


### Configuring `run`

The `commands.run` setting specifies the sequence of tasks executed by the `run`
command. Its default value is:

```toml
[commands]
run = "validate check build tag to_repo to_index"
```

The available tasks are `validate`, `check`, `is_clean`, `build`, `tag`,
`to_repo`, and `to_index`.

`validate` checks release readiness, including the project version and release
notes. It is the first task in the default sequence, but custom sequences may
omit it. **Omitting `validate` skips these release readiness checks and may
allow an invalid release to proceed.**

`is_clean` is an optional task that checks that the Git working tree is clean.
This check is already performed when building a new release, so including
`is_clean` in the `run` sequence is usually unnecessary.


#### Release archives and interrupted releases

A successful `build` creates `_releases/<version>/`, containing a `dist/`
subdirectory for distributions, `RELEASE.md` with the release notes,
`SHA256SUMS` for distribution checksums, and `BUILD_COMMIT` identifying the Git
commit used to build the archive. A release can contain multiple wheels and at
most one source distribution (`.tar.gz`).

If a `run` sequence is interrupted after the archive is built, running it again
reuses the verified archive instead of rebuilding. In that case, `check` and
`build` are skipped, even if they appear in `commands.run`. The remaining tasks
still execute, including `validate` if configured. The archived commit is used
for tagging, so later changes to `HEAD` or the working tree do not change which
source revision is released. An existing archive must pass verification before
it can be reused.

To force a new build, invoke `release build` directly. Replacing an existing
archive requires interactive confirmation and is refused if the release tag
already exists. You can choose whether to retain the previous archive in
`_releases/.backups/` after a successful replacement. An interrupted installation
may also leave a backup in the same location for manual recovery.


#### Local and CI release strategies

The `run` sequence also determines where the release process stops.

The default run sequence performs the complete release locally:

```toml
[commands]
run = "validate check build tag to_repo to_index"
```

An alternative common release pattern, especially when more than one developer
is empowered to create releases, is to delegate release tasks to a remote CI/CD
platform. Simple Releaser easily supports the remote CI/CD release pattern.

For a project with a remote CI/CD that publishes after a release tag is pushed,
omit the local publication tasks from the run sequence:

```toml
[commands]
run = "validate check build tag"
```

Here the local `build` acts as a packaging preflight. Simple Releaser verifies
that the distributions can be built and archived before `tag` creates and pushes
the release tag. The remote workflow may then rebuild the tagged source and
publish its own artifacts.

Projects with expensive, platform-specific, or otherwise CI-authoritative builds
may omit the local build as well:

```toml
[commands]
run = "validate check tag"
```

In this release sequence, Simple Releaser first performs its built-in release
validation before running the project's configured `check` command and then
creates and pushes the release tag. The remote workflow is responsible for both
building and publishing. This avoids a duplicate local build but a packaging
failure will not be discovered until after the release tag has been pushed.

For a concrete **GitHub Actions CI/CD workflow** using PyPI Trusted Publishing, see
[GitHub Actions and PyPI Trusted Publishing](https://codeberg.org/newbery/simple-releaser/src/branch/master/docs/github-trusted-publishing.md).


### Repository host

Simple Releaser normally determines the repository host and repository identifier
from the project's Git `origin` by default. HTTPS and SSH remotes on
`codeberg.org`, `gitea.com`, `github.com`, and `gitlab.com` are recognized.

When automatic detection is insufficient, the following settings can override it:

- `repo_remote` selects the Git remote for release tag lookups and pushes
  (default: `origin`). For example, `repo_remote = "upstream"`.
- `repo_host` selects the hosting service: `codeberg`, `forgejo`, `gitea`, `github`,
  or `gitlab`.
- `repo_base_url` overrides the server URL derived from the selected Git remote.
  This is primarily useful for self-hosted instances. Specify the web URL, not
  the API URL. Simple Releaser constructs API URLs automatically.
- `<HOST>_REPOSITORY` environment variable specifies the repository receiving
  the release, overriding the repository identifier derived from Git. For example,
  `GITLAB_REPOSITORY=group/project`.

> [!NOTE]
> When resolving a release repository, Simple Releaser verifies that **all effective
> fetch and push URLs** of the selected Git remote identify the same repository as
> the hosting API destination. This includes Git URL rewrites and separately
> configured `pushurl` values. A differing repository override or push destination
> is an error; select the matching Git remote or correct the configuration. SSH and
> HTTPS URLs for the same host and repository are supported.
> I'm not entirely sure this is the best way to deal with multi-remote repos
> so I'm open to alternative suggestions.

For example, to use a self-hosted GitLab instance:

```toml
repo_host = "gitlab"
repo_base_url = "https://git.example.org"
```

Repository overrides may be set as environment variables or in the
`.env` file beside `releaser.toml`; an exported environment variable takes
precedence over the same `.env` entry.

To publish to a Codeberg repository, set `CODEBERG_TOKEN`. Set
`CODEBERG_REPOSITORY=owner/repo` to override the repository identifier derived
from the Git `origin`.

To publish to a Forgejo repository, set `FORGEJO_TOKEN` and configure
`repo_host = "forgejo"`. Simple Releaser derives the instance URL from the Git
selected Git remote unless `repo_base_url` overrides it. Set
`FORGEJO_REPOSITORY=owner/repo` to override the derived repository identifier.

To publish to a Gitea repository, set `GITEA_TOKEN`. Set
`GITEA_REPOSITORY=owner/repo` to override the derived repository identifier.
For self-hosted Gitea, configure `repo_host = "gitea"`; use `repo_base_url` only when
the instance URL cannot be inferred correctly from the Git `origin`.

To publish to a GitHub repository, set `GITHUB_TOKEN`. Set
`GITHUB_REPOSITORY=owner/repo` to override the derived repository identifier.
The GitHub token must have permission to create releases and upload release
assets.

To publish to a GitLab.com repository, set `GITLAB_TOKEN`. Set
`GITLAB_REPOSITORY=namespace/repo` to override the derived repository
identifier. Nested namespaces such as `group/subgroup/repo` are supported.
The GitLab token must have permission to create releases, upload project files,
and create release asset links.


### Package index

The `to_index` task publishes to production PyPI by default. To publish to
TestPyPI, which requires a separate account and token, configure:

```toml
index_upload_url = "https://test.pypi.org/legacy/"
```

Custom package indexes are supported through an HTTPS `index_upload_url`.
See the preceding publishing section for full examples. The URL is supplied to
supported publishers via an automatically selected environment variable,
a `publish_index_env` override, or the `{index_url}` command placeholder,
so a custom command does not need to embed a fixed destination.

Before uploading, Simple Releaser checks for an existing release when the
index supports **PyPI's [JSON API](https://docs.pypi.org/api/json/)**.
It compares published filenames and SHA-256 checksums with the archived
distributions to identify matches, missing files, or conflicts.

Pre-upload checks are supported automatically for PyPI and TestPyPI. For a
custom package index, enable by setting `index_api_base_url`, but only if it
implements the PyPI-style endpoint. Note that the PyPI-style JSON API is different
from the standardized **Simple Repository API** (PEP 503/691), which package
installers typically use.

Support for the Simple Repository API is planned but, for now, if your index doesn't
support PyPI's JSON API, just leave `index_api_base_url` unset. Simple Releaser
will then skip the pre-upload check. This pre-upload check is optional and isn't
required for a successful release.


## Development

For development purposes, some project checks and a test runner are defined
as [Poe tasks](https://poethepoet.natn.io/):

```console
poe lint
poe format-check
poe typecheck
poe test

# Run all of the above
poe check 
```

The test suite can also be run across the matrix of supported Python versions,
which currently includes Python 3.11, 3.12, 3.13, and 3.14, using another Poe task:

```console
poe test-matrix
```

A separate packaging smoke test creates isolated test environments, installs
the Simple Releaser wheel and sdist package artifacts, and performs some basic
checks to verify that the packages are actually installable. This test can be
invoked with another Poe task:

```console
poe package-smoke
```

Finally, a more thorough check meant for CI runs the linters, type checks,
tests across all supported Python versions, and the packaging smoke test.
It can also be invoked locally via a Poe task:

```console
poe ci
```
