simple-releaser 0.0.1__tar.gz

simple_releaser-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# virtual environments / tool state
+/.venv
+/.pytest_cache
+/.ruff_cache
+/.coverage
+/dist/
+.env
+
+# Ignore my dev stash directories
+/_*

simple_releaser-0.0.1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+
+## Unreleased
+
+### Changed
+
+
+## 0.0.1 - 2026-09-08
+
+### Added & Changed
+
+- Read the project check command from `releaser.toml`.
+- Read the project build command from `releaser.toml`, with an `{output}`
+  placeholder for the temporary artifact directory.
+- Read the project publish command from `releaser.toml`, with placeholders for
+  the archived release directory, wheel, and source distribution.
+- Add GitHub support and use `repo_host` as the general configuration term for
+  services like Codeberg and GitHub.
+- Split repository-host implementations into `simple_releaser.codeberg` and
+  `simple_releaser.github`.
+- Split command-line handling, release workflow, and release exceptions into
+  `simple_releaser.cli`, `simple_releaser.releaser`, and
+  `simple_releaser.exceptions`.
+- Discover Codeberg or GitHub automatically from the Git `origin`, while
+  retaining `repo_host` as an explicit override for unusual layouts.
+- Read the Git release tag prefix from `releaser.toml`, defaulting to `v`.
+- Require `releaser.toml` in the invocation directory and allow it to select a
+  separate Python project with `project_path`.
+- Allow the `releaser.toml` filename to be overridden with `RELEASER_CONFIG`.
+- Rename the publishing CLI tasks to `to_pypi` and `to_repo`, and expose
+  `clean` as a direct clean-repository check.
+- Allow configured commands to be written as shell-like strings as well as TOML
+  arrays of argument strings.
+- Make `commands.run` an ordered, configurable task sequence.
+- Allow empty configurable commands to skip their corresponding tasks.
+- Expose `clean` and `validate` as task names that may be included in a
+  configured run sequence, and prevent `run` from recursively invoking itself.
+- Add global `--dry-run` support that performs release preflight while describing
+  configured commands, archive creation, tagging, and publication without making
+  changes.
+- Use PyPA `build` and Twine for the default build and PyPI publish commands, and
+  expose `{python}` as the Python interpreter running Simple Releaser for command
+  overrides.
+- Add `show-config` to display the current configuration and project metadata.
+- Require confirmation before publishing distributions to PyPI, with an
+  `auto_confirm` configuration option for unattended releases.
+- Print PyPI and repository release-page links around publication so the
+  published state is easy to inspect.
+- Implement `init` to create minimal releaser configuration.
+- Add documentation about GitHub Actions and PyPI Trusted Publishing.
+- Add documentation about alternative release orchestration tools.
+
+
+## 0.0.0 - 2026-08-27 (Unreleased)
+
+### Added
+
+- Initial copy from QRtsy project, https://codeberg.org/newbery/qrtsy
+

simple_releaser-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Newbery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simple_releaser-0.0.1/PKG-INFO

@@ -0,0 +1,401 @@
+Metadata-Version: 2.5
+Name: simple-releaser
+Version: 0.0.1
+Summary: A small tool for prepping 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 :: 3 - Alpha
+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: packaging<27.0,>=25.0
+Requires-Dist: python-dotenv<2.0.0,>=1.1.0
+Requires-Dist: twine<8.0.0,>=7.0.0
+Description-Content-Type: text/markdown
+
+> ⚠️ **Warning** ⚠️   
+> Simple Releaser is alpha software and probably not yet ready for general use.
+> Expect rough edges, breaking changes, and an occasional gremlin.
+
+
+# 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) with significant changes
+to generalize it to accommodate different release workflows. Simple Releaser
+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](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.
+
+When publishing a repository release locally, the project is also expected
+to have:
+
+- A repository hosted by Codeberg or GitHub.
+- A .env file beside the releaser configuration when a host token or repository
+  override is needed.
+
+
+## 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 -h
+usage: release [-h] [--dry-run] {init,show-config,clean,validate,build,tag,to_pypi,to_repo,run} ...
+
+Validate, build, archive, and publish Python project releases.
+
+A simple project release policy:
+  - Validate that release is ready
+  - Run any project-specific checks
+  - Build package and archive it
+  - Create release tag
+  - Publish package to PyPI
+  - Publish release and assets to repository host
+
+positional arguments:
+  {init,show-config,clean,validate,build,tag,to_pypi,to_repo,run}
+    init                initialize Simple Releaser configuration
+    show-config         show resolved configuration and project metadata
+    clean               check if project is a clean git repository
+    validate            validate that a new release is ready
+    build               build and archive the current version
+    tag                 create and push the current release tag
+    to_pypi             publish the archived distributions to PyPI
+    to_repo             publish the release to repository host
+    run                 run the configured release process
+
+options:
+  -h, --help            show this help message and exit
+  --dry-run             show what would be done without making changes
+```
+
+### Dry run
+
+Pass `--dry-run` before or after a command to perform the normal read-only
+preflight and describe the release actions without making changes. For example:
+
+```console
+release run --dry-run
+release --dry-run tag
+```
+
+Dry-run mode still reads project/repository metadata, checks that the Git working
+tree is clean, validates the version and changelog, and inspects existing Git
+tags. It does not run configured project commands, create the release archive,
+create or push Git tags, publish to PyPI, or call the Codeberg/GitHub release
+APIs. Because the build is simulated, later dry-run tasks use descriptive
+artifact placeholders rather than requiring `_releases/<version>` to already
+exist.
+
+The read-only `show-config`, `clean`, and `validate` commands behave the same
+with or without `--dry-run`.
+
+
+### Initialization
+
+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.
+
+`release init --dry-run` performs the same project discovery but only reports
+where the configuration would be created.
+
+
+## Configuration
+
+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.
+
+When the directory also contains the project's `pyproject.toml`, no project path
+is needed:
+
+```toml
+tag_prefix = "v"
+auto_confirm = false
+
+[commands]
+run = "check build tag to_pypi to_repo"
+```
+
+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. For example:
+
+```toml
+project_path = "../my-project"
+repo_host = "github"
+tag_prefix = "v"
+auto_confirm = false
+
+[commands]
+run = "check build tag to_pypi to_repo"
+```
+
+Set `auto_confirm = true` at the top level to allow PyPI publication without an
+interactive confirmation prompt, for example in a deliberately unattended
+release workflow. It defaults to `false`; even with automatic confirmation,
+Simple Releaser still prints the project/version/artifact summary and PyPI URL
+before running the publish command.
+
+
+### 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)"'
+```
+
+An empty string or empty array disables the task associated with that configured
+command. For example:
+
+```toml
+[commands]
+check = ""
+publish = ""
+```
+
+causes the `check` and `to_pypi` tasks to be skipped. The `publish` configuration
+name controls the `to_pypi` task.
+
+
+### Configuring `check`
+
+The configured `check` command is the project's own test, lint, and quality
+check. Since this is very project-specific, by default the `check` command
+is disabled and must be customized for the project:
+
+```toml
+[commands]
+check = ""
+```
+
+The `simple-releaser` project also uses its own tooling for releasing itself.
+See the project's `releaser.toml` file for the configuration that it uses.
+For this project, the releaser `check` command has been customized like so:
+
+```toml
+[commands]
+check = "hatch run poe check"
+```
+
+
+### Configuring `build` and `publish`
+
+By default, Simple Releaser builds with `build` and publishes with `twine`:
+
+```toml
+[commands]
+build = "{python} -m build --outdir {output}"
+publish = "{python} -m twine upload --skip-existing {wheel} {sdist}"
+```
+
+Build and publish commands may 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 default publisher uses Twine's normal authentication mechanisms, including
+keyring, `.pypirc`, and `TWINE_*` environment variables. The `.env` file read by
+Simple Releaser for repository-host settings is not exported to subprocesses.
+
+The `{output}` placeholder in `build` is replaced with the temporary directory
+where the build command must write the wheel and source distribution. A
+non-empty custom build command must include `{output}`. Publish commands may use
+`{release_dir}`, `{wheel}`, and `{sdist}` to refer to the verified archived
+release and its two distribution files. A custom publish command does not have
+to use a placeholder when the command already knows how to locate the artifacts
+it should publish.
+
+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. Projects that prefer their project-management tool's native build
+and publish commands can override the defaults. Typical equivalents are:
+
+```toml
+# Poetry
+build = "poetry build --clean --output {output}"
+publish = "poetry publish --skip-existing --dist-dir {release_dir}"
+
+# Hatch
+build = "hatch build --clean {output}"
+publish = "hatch publish --no-prompt {wheel} {sdist}"
+
+# uv
+build = "uv build --no-sources --out-dir {output}"
+publish = "uv publish {wheel} {sdist}"
+
+# PDM
+build = "pdm build --dest {output}"
+publish = "pdm publish --no-build --skip-existing --dest {release_dir}"
+```
+
+
+### Configuring `run`
+
+The `run` command is an ordered list of task names. Its default value is:
+
+```toml
+[commands]
+run = "check build tag to_pypi to_repo"
+```
+
+The available run task names are `check`, `clean`, `validate`, `build`, `tag`,
+`to_pypi`, and `to_repo`.
+
+- `clean` is available for release flows that want an explicit clean-repository
+  check at a particular point, but this is usually unnecessary because release
+  validation already checks the working tree and tasks that require cleanliness
+  enforce it themselves.
+- `validate` may also be included explicitly, but again this is usually unnecessary
+  since validation is already automatically done before `run` begins.
+
+Both of these are included as options for custom release plans where revalidation
+or additional clean checks might be useful.
+
+
+#### Local and CI release strategies
+
+The `run` sequence also determines where the release process stops.
+
+The default sequence performs the complete release locally:
+
+```toml
+[commands]
+run = "check build tag to_pypi to_repo"
+```
+
+For a project whose remote CI publishes after a release tag is pushed, omit the
+local publication tasks:
+
+```toml
+[commands]
+run = "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 = "check tag"
+```
+
+In this form, Simple Releaser runs 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.
+
+The configured `check` in these examples remains the project's own quality-check
+command, such as its tests, linters, and type checks. It is separate from Simple
+Releaser's release validation, which the CLI performs before the `run` sequence
+begins.
+
+Because `tag` pushes the tag to `origin`, it can serve directly as the handoff to
+a tag-triggered CI workflow. Simple Releaser does not need to know which CI
+system handles the tag or how that system builds and publishes the release.
+
+For a concrete GitHub Actions workflow using PyPI Trusted Publishing, see
+[GitHub Actions and PyPI Trusted Publishing](docs/github-trusted-publishing.md).
+
+
+### Repository host
+
+The repository host and `owner/repo` coordinates are normally derived from the
+configured project's Git `origin`. HTTPS and SSH origins on `codeberg.org` and
+`github.com` are recognized automatically. `tag_prefix` controls the text
+prepended to the project version when creating and locating Git tags; it defaults
+to `"v"`. Set it to an empty string to use bare version tags such as `1.2.3`.
+
+For unusual arrangements where the Git `origin` is not the repository that
+receives releases, `repo_host` may explicitly select `codeberg` or `github`; pair
+it with the corresponding repository override in `.env`.
+
+For local Codeberg publication, set `CODEBERG_TOKEN` in `.env`. Set
+`CODEBERG_REPOSITORY=owner/repo` to override the repository coordinates derived
+from the Git `origin`.
+
+For local GitHub publication, set `GITHUB_TOKEN` in `.env`. Set
+`GITHUB_REPOSITORY=owner/repo` to override the derived repository coordinates.
+The GitHub token must have permission to create releases and upload release
+assets.