Skip to content

Commit 1d64429

Browse files
committed
Prepare v1.3.0 Python and PyPI release
1 parent d8a9f47 commit 1d64429

31 files changed

Lines changed: 1232 additions & 20 deletions

‎.dockerignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,15 @@
66
.codex
77
.agents
88
.tmp
9+
.venv
10+
venv
11+
ai-kit
12+
__pycache__
13+
.ruff_cache
14+
.coverage
15+
.coverage.*
16+
htmlcov
17+
*.egg-info
918

1019
# Source and test artifacts are not part of the production image.
1120
docs

‎.github/dependabot.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,12 @@ updates:
1414
schedule:
1515
interval: weekly
1616
open-pull-requests-limit: 5
17+
18+
- package-ecosystem: pip
19+
directory: /
20+
schedule:
21+
interval: weekly
22+
open-pull-requests-limit: 5
23+
groups:
24+
python-tooling:
25+
patterns: ["*"]

‎.github/workflows/pypi-publish.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Publish Python package
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
repository:
7+
description: 'Trusted-publisher destination (run only from a release tag)'
8+
type: choice
9+
options: [testpypi, pypi]
10+
default: testpypi
11+
required: true
12+
13+
permissions:
14+
contents: read
15+
16+
concurrency:
17+
group: python-publish-${{ inputs.repository }}
18+
cancel-in-progress: false
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-24.04
23+
steps:
24+
- uses: actions/checkout@v7
25+
- uses: actions/setup-python@v6
26+
with:
27+
python-version: '3.11'
28+
- name: Require a confirmed matching release tag
29+
shell: bash
30+
run: |
31+
set -Eeuo pipefail
32+
version="$(sed -n 's/^readonly BACKFORT_VERSION="\([^"]*\)"$/\1/p' backfort.sh)"
33+
[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
34+
[[ "$GITHUB_REF" == "refs/tags/v${version}" ]]
35+
[[ "$(python run_backfort.py --version)" == "Backfort ${version}" ]]
36+
grep -Fqx "## ${version}" CHANGELOG.md
37+
- name: Install development dependencies
38+
run: python -m pip install '.[dev]'
39+
- name: Test launcher
40+
run: python -m coverage run -m unittest discover -s tests -p 'test_python_*.py' -v
41+
- name: Check coverage
42+
run: python -m coverage report
43+
- name: Build distributions
44+
run: python -m build
45+
- name: Validate distributions
46+
shell: bash
47+
run: |
48+
python -m twine check --strict dist/*
49+
python tests/python_package.py
50+
- uses: actions/upload-artifact@v4
51+
with:
52+
name: python-release-distributions
53+
path: |
54+
dist/*.whl
55+
dist/*.tar.gz
56+
if-no-files-found: error
57+
58+
publish:
59+
if: github.repository == 'shellharbor/backfort'
60+
needs: build
61+
runs-on: ubuntu-24.04
62+
environment:
63+
name: ${{ inputs.repository }}
64+
url: ${{ inputs.repository == 'pypi' && 'https://pypi.org/p/backfort' || 'https://test.pypi.org/p/backfort' }}
65+
permissions:
66+
id-token: write
67+
steps:
68+
- uses: actions/download-artifact@v4
69+
with:
70+
name: python-release-distributions
71+
path: dist
72+
- name: Publish through the configured trusted publisher
73+
uses: pypa/gh-action-pypi-publish@release/v1
74+
with:
75+
repository-url: ${{ inputs.repository == 'pypi' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Python package
2+
3+
on:
4+
push:
5+
pull_request:
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
concurrency:
12+
group: python-package-${{ github.workflow }}-${{ github.ref }}
13+
cancel-in-progress: true
14+
15+
jobs:
16+
package:
17+
name: Python ${{ matrix.python }} on ${{ matrix.os }}
18+
runs-on: ${{ matrix.os }}
19+
strategy:
20+
fail-fast: false
21+
matrix:
22+
os: [ubuntu-24.04]
23+
python: ['3.11', '3.12', '3.13', '3.14']
24+
include:
25+
- os: windows-latest
26+
python: '3.12'
27+
steps:
28+
- uses: actions/checkout@v7
29+
- uses: actions/setup-python@v6
30+
with:
31+
python-version: ${{ matrix.python }}
32+
- name: Install development dependencies
33+
run: python -m pip install '.[dev]'
34+
- name: Lint Python sources
35+
run: python -m ruff check .
36+
- name: Check formatting
37+
run: python -m ruff format --check .
38+
- name: Test launcher branches
39+
run: python -m coverage run -m unittest discover -s tests -p 'test_python_*.py' -v
40+
- name: Require complete launcher branch coverage
41+
run: python -m coverage report
42+
- name: Build source distribution and wheel
43+
run: python -m build
44+
- name: Validate PyPI metadata and README
45+
shell: bash
46+
run: python -m twine check --strict dist/*
47+
- name: Check isolated installation and rebuild from sdist
48+
run: python tests/python_package.py
49+
- name: Install Linux round-trip prerequisites
50+
if: matrix.os == 'ubuntu-24.04' && matrix.python == '3.11'
51+
shell: bash
52+
run: |
53+
go install github.com/mikefarah/yq/v4@v4.45.1
54+
echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
55+
- name: Test real installed-package backup and recovery
56+
if: matrix.os == 'ubuntu-24.04' && matrix.python == '3.11'
57+
run: python tests/python_package.py --round-trip
58+
- name: Preserve distributions
59+
if: matrix.os == 'ubuntu-24.04' && matrix.python == '3.11'
60+
uses: actions/upload-artifact@v4
61+
with:
62+
name: backfort-python-distributions
63+
path: |
64+
dist/*.whl
65+
dist/*.tar.gz
66+
if-no-files-found: error

‎CHANGELOG.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,38 @@
33
All notable changes are documented here. Backfort follows semantic versioning
44
once a release is tagged.
55

6+
## 1.3.0
7+
8+
### Added
9+
10+
- Optional Python 3.11+ Linux distribution with `backfort`, `python -m backfort`
11+
and checkout-local `run_backfort.py` entry points. The package bundles the
12+
canonical Bash engine and example YAML; it has no Python runtime dependencies
13+
and does not replace or download system tools.
14+
- Standalone `--print-example-config` for emitting the bundled reference YAML,
15+
including on Windows/macOS. Backup execution remains Linux-only.
16+
- Hatchling wheel/sdist builds with one Bash-derived version, explicit source
17+
archive contents, canonical-resource integrity checks, isolated installation
18+
and sdist rebuild tests, plus a real installed-package Linux backup, full
19+
verification and staged recovery round trip.
20+
- Python CI for 3.11–3.14 on Linux and the native-Windows compatibility boundary,
21+
with complete launcher branch coverage, Ruff and strict Twine validation.
22+
- Separate manual TestPyPI/PyPI publishing using GitHub OIDC trusted publishers,
23+
matching release-tag/version/Changelog checks and index-specific environments.
24+
Ordinary CI never publishes packages; no permanent PyPI API token is required.
25+
- Python installation, dependency and privilege guidance in the README,
26+
dedicated PyPI project description, Wiki runbook and distribution ADR.
27+
28+
### Changed
29+
30+
- Synchronized the CLI, Python package metadata, Helm application version,
31+
Docker Compose image reference and current documentation examples to 1.3.0.
32+
The native CLI, YAML schema and backup/recovery format are unchanged.
33+
- Extended Dependabot to Python build/development dependencies and excluded
34+
local Python build environments and caches from Docker build contexts.
35+
- Included upstream maintenance updates since 1.2.0: rclone 1.75.2 and refreshed
36+
GitHub Actions supply-chain scanning dependencies.
37+
638
## 1.2.0
739

840
- Fixed file-source tar transforms rewriting symbolic-link targets with the

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,12 @@ When available, also run ShellCheck:
3434
shellcheck backfort.sh tests/*.sh
3535
```
3636

37+
For the optional Python/PyPI distribution, follow
38+
[Python package development](wiki/Python-and-PyPI.md#build-and-test).
39+
Keep the root Bash engine as the only source and package its exact bytes;
40+
do not commit generated shell copies. Artifact checks include an isolated
41+
install, sdist rebuild and real Linux backup/recovery round trip.
42+
3743
Run the focused test for the changed surface. The suite includes quick backup,
3844
rclone, Docker Compose and its restore assistant, crypto/signing, watchdog,
3945
diff, pins, date-range deletion, interactive restore selection, notifications,

‎README.md‎

Lines changed: 57 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ explicit, verified backup and exits—no daemon to babysit, no hidden discovery
1010
of files or databases, and no risky in-place restore switch.
1111

1212
[![CI](https://github.com/shellharbor/backfort/actions/workflows/ci.yml/badge.svg)](https://github.com/shellharbor/backfort/actions/workflows/ci.yml)
13+
[![Python package](https://github.com/shellharbor/backfort/actions/workflows/python-package.yml/badge.svg)](https://github.com/shellharbor/backfort/actions/workflows/python-package.yml)
1314
[![Kubernetes](https://github.com/shellharbor/backfort/actions/workflows/kubernetes.yml/badge.svg)](https://github.com/shellharbor/backfort/actions/workflows/kubernetes.yml)
1415
[![Documentation](https://github.com/shellharbor/backfort/actions/workflows/documentation.yml/badge.svg)](https://github.com/shellharbor/backfort/actions/workflows/documentation.yml)
1516
[![CodeQL](https://github.com/shellharbor/backfort/actions/workflows/codeql.yml/badge.svg)](https://github.com/shellharbor/backfort/actions/workflows/codeql.yml)
@@ -22,6 +23,7 @@ of files or databases, and no risky in-place restore switch.
2223
[![GitHub stars](https://img.shields.io/github/stars/shellharbor/backfort?style=flat)](https://github.com/shellharbor/backfort/stargazers)
2324

2425
**[Get started](#first-backup--durable-setup)** ·
26+
**[Install with Python](#run-backfort-through-python-or-install-a-pypi-package)** ·
2527
**[Run in Docker](#run-backfort-in-docker)** ·
2628
**[Run in Kubernetes](#run-backfort-in-kubernetes)** ·
2729
**[Examples](examples/README.md)** ·
@@ -37,6 +39,7 @@ Canonical repository: [github.com/shellharbor/backfort](https://github.com/shell
3739
| --- | --- | --- |
3840
| Protect files and directories on a schedule | [First backup](#first-backup--durable-setup) | A strict YAML job for cron or a systemd timer. |
3941
| Take a fast snapshot before a risky change | [Quick file backup](#quick-file-backup) | A one-command backup plus a reusable non-secret recovery config. |
42+
| Install the CLI with pip or pipx | [Python installation](#run-backfort-through-python-or-install-a-pypi-package) | The canonical Bash engine, bundled with a dependency-free Python launcher. |
4043
| Run Backfort as a containerized job | [Run in Docker](#run-backfort-in-docker) | The same YAML plan and recovery format, with explicit persistent mounts. |
4144
| Protect files on Kubernetes PVCs | [Run in Kubernetes](#run-backfort-in-kubernetes) | Helm Job/CronJob deployment with explicit read-only sources, durable state and isolated recovery. |
4245
| Back up a Docker Compose stack | [Docker Compose sources](#docker-compose-sources) | Explicit project files, bind mounts, named volumes, and database dumps. |
@@ -74,6 +77,8 @@ destinations as a file backup.
7477
## Features
7578

7679
- One Bash 4.3+ executable and one YAML configuration
80+
- Optional Python 3.11+ launcher with pip/pipx packaging, `backfort` and
81+
`python -m backfort` entry points; no Python runtime dependencies
7782
- Strict configuration validation with unknown-key detection
7883
- Full-file and directory backups with GNU tar include roots and excludes
7984
- Helm deployment for Kubernetes PVC-file backups, manual recovery Jobs and
@@ -125,6 +130,51 @@ sudo apt-get install bash coreutils findutils gzip tar util-linux
125130
Install Mike Farah `yq` v4 using its official release or package. The Python
126131
package with the same name is not compatible.
127132

133+
## Run Backfort through Python or install a PyPI package
134+
135+
The optional Python package bundles the same Bash engine and reference YAML.
136+
It requires **Python 3.11+ on Linux**, plus the native Bash/GNU/yq prerequisites
137+
above. It is not a Python rewrite or a Windows port; use Linux Python inside
138+
WSL or the Docker image on Windows.
139+
140+
Version **1.3.0** adds Python packaging without changing the native CLI or
141+
backup format. Install the published release into an isolated environment:
142+
143+
```bash
144+
pipx install 'backfort==1.3.0'
145+
backfort --version
146+
backfort --print-example-config > backfort.example.yaml
147+
```
148+
149+
Alternatively, use pip inside a virtual environment:
150+
151+
```bash
152+
python3 -m venv .venv
153+
.venv/bin/python -m pip install 'backfort==1.3.0'
154+
.venv/bin/backfort --version
155+
.venv/bin/python -m backfort --help
156+
```
157+
158+
Choose a new output filename (shell redirection overwrites files), edit the
159+
config, then run `doctor` and a dry run before backing up. If `1.3.0` has not
160+
reached your package index yet, run `.venv/bin/python -m pip install .` from
161+
a trusted `v1.3.0` checkout instead. For privileged backups use a protected
162+
installation; never run a user-writable virtual environment as root.
163+
164+
Direct execution from a checkout needs no Python package installation:
165+
166+
```bash
167+
python3 run_backfort.py --version
168+
python3 run_backfort.py -c /etc/backfort/config.yaml doctor
169+
```
170+
171+
The launcher preserves arguments, environment, terminal, signals and engine
172+
exit codes. It never downloads an engine or installs system tools. Native
173+
Bash and Docker/Helm remain usable without Python. See
174+
[Python and PyPI](wiki/Python-and-PyPI.md) for examples, tests, building and the
175+
manual maintainer publishing procedure. Local build files are not evidence
176+
that a package is already published.
177+
128178
## Run Backfort in Docker
129179

130180
The container image is an additional distribution method, not a second backup
@@ -133,8 +183,8 @@ creates the same portable bundles as a native installation. Images are
133183
published for `linux/amd64` and `linux/arm64` to GitHub Container Registry:
134184

135185
```bash
136-
docker pull ghcr.io/shellharbor/backfort:1.2.0
137-
docker run --rm ghcr.io/shellharbor/backfort:1.2.0 --version
186+
docker pull ghcr.io/shellharbor/backfort:1.3.0
187+
docker run --rm ghcr.io/shellharbor/backfort:1.3.0 --version
138188
```
139189

140190
For a durable setup, copy the sample Compose file and its matching config into
@@ -176,8 +226,8 @@ mounted read-only. Use it only for a trusted Compose job and never for a
176226
normal files-only backup. The complete deployment, secret, recovery and
177227
upgrade guidance is in [Docker deployment](wiki/Docker-Deployment.md).
178228

179-
Release tags are immutable exact versions such as `1.2.0`. Stable releases
180-
also move `1.2`, `1`, and `latest`; pin an exact version or digest for a
229+
Release tags are immutable exact versions such as `1.3.0`. Stable releases
230+
also move `1.3`, `1`, and `latest`; pin an exact version or digest for a
181231
repeatable run and retain the `backfort-state` volume during upgrades. Docker
182232
Hub publication is optional and occurs only when the repository has both
183233
`DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` release secrets; GHCR is the
@@ -1461,12 +1511,14 @@ Backfort's badges point to checks that are actually tracked in the repository:
14611511
| Guardrail | What it protects |
14621512
| --- | --- |
14631513
| [CI](.github/workflows/ci.yml) | Bash syntax and runtime on Bash 4.3, ShellCheck, YAML examples, the hermetic suite, and a real PostgreSQL/MySQL Compose backup-and-recovery round trip. |
1514+
| [Python package](.github/workflows/python-package.yml) | Python 3.11–3.14/Linux and the Windows boundary, complete launcher branch coverage, wheel/sdist metadata, isolated installation and real installed-package backup/recovery. |
14641515
| [Kubernetes](.github/workflows/kubernetes.yml) | Helm rendering/safety gates and real-image PVC backup, full verification, metadata recovery, cross-Job locking and non-root operation in an isolated kind cluster. |
14651516
| [Documentation](.github/workflows/documentation.yml) | Internal Markdown links across the README, Wiki sources, examples, and community documents, plus whitespace in changed files. |
14661517
| [CodeQL](.github/workflows/codeql.yml) | GitHub Actions workflow analysis on pull requests, `main`, and a weekly schedule. |
14671518
| [OpenSSF Scorecard](.github/workflows/scorecard.yml) | A weekly supply-chain review published to GitHub code scanning. |
14681519
| [Release metadata](.github/workflows/release-metadata.yml) | A `vX.Y.Z` tag must match the CLI version and the Changelog before release work proceeds. |
1469-
| [Dependabot](.github/dependabot.yml) | Weekly grouped GitHub Actions updates and Docker base-image updates. |
1520+
| [Publish Python package](.github/workflows/pypi-publish.yml) | Manual, matching-tag-only TestPyPI/PyPI publishing with OIDC and separate named environments; ordinary CI never uploads a release. |
1521+
| [Dependabot](.github/dependabot.yml) | Weekly grouped GitHub Actions, Docker base-image and Python build/development dependency updates. |
14701522

14711523
Every push and pull request runs CI on Ubuntu. Documentation-only changes also
14721524
run the lightweight link check. CI, Kubernetes, Documentation, CodeQL, and Scorecard can be

‎backfort.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ IFS=$'\n\t'
55
LC_ALL=C
66
umask 077
77

8-
readonly BACKFORT_VERSION="1.2.0"
8+
readonly BACKFORT_VERSION="1.3.0"
99

1010
CONFIG_FILE="/etc/backfort/config.yaml"
1111
CONFIG_FILE_EXPLICIT=false

‎charts/backfort/Chart.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: backfort
33
description: One-shot Backfort backup, retention and recovery jobs for mounted PVCs
44
type: application
55
version: 0.1.0
6-
appVersion: "1.2.0"
6+
appVersion: "1.3.0"
77
kubeVersion: ">=1.31.0-0"
88
home: https://github.com/shellharbor/backfort
99
sources:

‎docker-compose.example.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
# restart must never create an unexpected additional backup.
99
services:
1010
backfort:
11-
image: ghcr.io/shellharbor/backfort:1.2.0
11+
image: ghcr.io/shellharbor/backfort:1.3.0
1212
restart: "no"
1313
init: true
1414
read_only: true

0 commit comments

Comments
 (0)