githubtemplateastraluv / templateastraluv (0.0.4)
GitHub template for Astral-UV apps published on PyPI.
A Python CLI application shipped as an Astral uv/uvx-installable tool with
PyPI OIDC Trusted Publishing release automation. It provides management
commands for upgrade, uninstall, and version reporting; an automatic
new-version check throttled by an idle-time cache; self-upgrade from PyPI or
from the latest GitHub tag via --develop; a dual-source version
report (installed / PyPI / GitHub); and a JSON-configurable
notification-color subsystem with validated, atomic persistence.
Feature Highlights | Quick Start | Requirements | User's Guide | Acknowledgments
🚧 STAGE: PRE-ALPHA 📝 - Proof-of-Concept 🏗️ 🚧
⚠️ IMPORTANT NOTICE: Created with PI-useReq/pi-usereq 🤖✨ ⚠️
Feature Highlights
- Published on PyPI: install with
uv tool install githubtemplateastraluv, or run on-the-fly withuvx githubtemplateastraluv. - Dual-source version report (
--ver/--version): installed, latest PyPI, and latest GitHub versions in aligned columns. - Automatic new-version check before every run, throttled by an idle-time cache so no redundant network calls are made.
- Self-upgrade from PyPI (
--upgrade), forced full re-download (--force), or the latest GitHub tagged release (--develop). - One-command removal (
--uninstall) — on non-Linux systems the exact manual command is printed instead. - Colored console notifications (bright green for availability, bright red for errors), hardcoded in the embedded internal color JSON of
src/githubtemplateastraluv/colors.py. - Configuration CLI (
--get,--set,--unset,--print,--info,--print-raw) with schema validation and atomic persistence. - Release automation: a GitHub release for every version tag and OIDC Trusted Publishing to PyPI for
mastertags.
Quick Start
-
Install the tool from PyPI:
uv tool install githubtemplateastraluv
-
Configure — optional: the application works out of the box with sensible defaults (bright green availability notes, bright red error notes). Customization is described in the User's Guide.
-
Execute:
githubtemplateastraluv --help githubtemplateastraluv --ver
Requirements
- Python >= 3.11.
- Astral
uv— required to install, upgrade, uninstall, or run the tool locally from the repository. git— required only to install the development source with--develop.- Network access — outbound HTTPS to
pypi.org(version check, upgrades) andapi.github.com(latest-release query for the--verreport and--developchannel). - Linux — required for the
--upgradeand--uninstallside effects; on any other platform the tool prints a warning and the exact manual command. - ANSI-capable terminal — required for colored notifications.
User's Guide
Install from PyPI (primary method)
uv tool install githubtemplateastraluv
Upgrade and uninstall:
githubtemplateastraluv --upgrade
uv tool uninstall githubtemplateastraluv
Live execution with uvx (alternative method)
Run directly from PyPI without a prior installation:
uvx githubtemplateastraluv
uvx githubtemplateastraluv --ver
Install and upgrade from GitHub (non-primary development channel)
A dedicated, non-primary distribution channel hosts intermediate and test
releases on GitHub: https://github.com/Ogekuri/GitHub-Template-AstralUV.
# Install from the GitHub repository
uv tool install githubtemplateastraluv --force --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git
# Upgrade to the latest GitHub tagged release (tagged on any branch)
githubtemplateastraluv --upgrade --develop
# Forced full re-download and reinstallation variants
githubtemplateastraluv --upgrade --force
githubtemplateastraluv --upgrade --develop --force
--upgrade --develop always downloads the most recent tagged build from
GitHub, regardless of the branch it was tagged on. The --ver report shows
that channel in the Latest @ GitHub row.
Run locally from the repository
./scripts/templateastraluv.sh --help
The launcher resolves the repository root and delegates to
uv run --project <root> python -m githubtemplateastraluv.
Command reference
The full help screen (printed by --help or by running the tool with no
arguments):
Usage: githubtemplateastraluv [command] [options] (0.0.4)
Management Commands:
--upgrade - Reinstall githubtemplateastraluv on Linux; print manual command elsewhere.
--uninstall - Uninstall githubtemplateastraluv on Linux; print manual command elsewhere.
--ver - Print the githubtemplateastraluv version.
--version - Print the githubtemplateastraluv version.
--help - Print the full help screen.
Configuration Commands:
--get - Print the value at Path as one JSON document.
--set - Parse Value into the schema type and persist it at Path.
--unset - Restore Path to its schema default and persist atomically.
--print - Print current values as a box-drawing tree, whole schema or at Path.
--info - Print parameter documentation with defaults, constraints, and examples.
--print-raw - Print the exact bytes of the configuration JSON file.
Options:
--develop - With --upgrade: install from the GitHub development source.
--force - With --upgrade: force full re-download and reinstallation.
Version report (--ver / --version)
Prints the three-row report with aligned version columns and always refreshes the source queries, bypassing the idle-time gate:
Current Installed : X1.Y1.Z1
Latest @ PyPI : X2.Y2.Z2
Latest @ GitHub : X3.Y3.Z3
A failed source prints unknown (<reason>) in place of the version, with a
bright red note naming that source. The GitHub row strips the v prefix from
the latest release tag.
--upgrade variants (Linux)
| Command | Executed command |
|---|---|
--upgrade |
uv tool install githubtemplateastraluv |
--upgrade --force |
uv tool install githubtemplateastraluv --force --reinstall --refresh |
--upgrade --develop |
uv tool install githubtemplateastraluv --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git |
--upgrade --develop --force |
uv tool install githubtemplateastraluv --force --reinstall --refresh --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git |
On non-Linux operating systems nothing is executed: the tool prints a warning
and the matching manual command from the table. --develop and --force are
accepted exclusively as --upgrade modifiers; any other combination falls
back to the normal dispatch behavior.
--uninstall (Linux)
githubtemplateastraluv --uninstall
Executes uv tool uninstall githubtemplateastraluv on Linux; on any other
platform it prints a warning and the manual command
uv tool uninstall githubtemplateastraluv.
Configuration
Configuration file
The global configuration lives at
$HOME/.config/githubtemplateastraluv/config.json. It is created with the
schema defaults on the first configuration command and every update is
validated against the schema and persisted atomically (the previous file is
preserved if any step fails).
Configuration commands
Configuration paths are case-sensitive, colon-separated canonical tokens
(Section, Section:Parameter); the schema currently defines no sections,
so every canonical path is rejected.
| Command | Behavior |
|---|---|
--get <Path> |
Prints the resolved value as one valid JSON document on stdout. |
--set <Path> <Value> |
Parses Value into the schema type, validates, and persists atomically. |
--unset <Path> |
Restores the targeted parameter or section to its schema default. |
--print [Path] |
Renders current values as a box-drawing tree with [Path: <canonical path>] section headings. |
--info [Path] |
Renders per-parameter type, constraints, description, default, and shell-valid --set / --unset examples. |
--print-raw |
Writes the exact bytes of the configuration JSON file to stdout. |
Examples:
githubtemplateastraluv --print
githubtemplateastraluv --info
githubtemplateastraluv --print-raw
# The schema currently defines no sections: every canonical path is
# rejected with exit status 1 and a stderr diagnostic.
githubtemplateastraluv --get Notifications:new_version_color
On any configuration failure the tool exits with code 1, prints a
diagnostic on stderr, and emits nothing on stdout.
Notification colors (hardcoded)
Notification colors are not configurable. All colors live in one embedded
internal JSON document (COLOR_CONFIG_JSON) inside
src/githubtemplateastraluv/colors.py:
notificationsassigns the new-version colorbright_green(ANSI SGR 92) and the error colorbright_red(ANSI SGR 91).palettemaps every color token to its ANSI SGR prefix:bright_green(92),bright_red(91),bright_yellow(93),bright_blue(94),bright_magenta(95),bright_cyan(96),bright_white(97).
Both colors drive the automatic version-check notifications; no CLI option, file, or environment variable can alter them.
Documentation
Automatic version check
On every invocation the tool runs an online new-version check before argument parsing. The check is throttled by an idle-time cache:
- Cache file:
$HOME/.cache/githubtemplateastraluv/check_version_idle-time.json. - The HTTPS request to
https://pypi.org/pypi/githubtemplateastraluv/jsonruns only when the cache file is absent or the cached idle-time has elapsed (2-second timeout). - A successful check refreshes the cache with a 3600-second idle-delay; a failed check (HTTP 429, 503, timeout, network error) reports a bright red error note and backs off with an 86400-second idle-delay.
--verand--versionbypass the gate and always query both sources (PyPI JSON API andhttps://api.github.com/repos/Ogekuri/GitHub-Template-AstralUV/releases/latest).
Repository tooling scripts
| Script | Purpose |
|---|---|
scripts/templateastraluv.sh |
Local-run launcher delegating to uv run --project <root> python -m githubtemplateastraluv. |
scripts/build.sh |
Release packager: cleans the generated state, removes stale dist/*.tar.gz/dist/*.whl, builds uv run --frozen --with build python -m build, and verifies the produced sdist and wheel. |
scripts/clean.sh |
Removes every repository-internal execution-generated artifact and restores the canonical startup state. |
scripts/pre-release-check.sh |
Fail-fast release verification (syntax, compileall, pytest, out-of-tree build, artifact validation) with baseline-guarded cleanup. |
scripts/clean.sh removes __pycache__/ and *.egg-info/ at any depth,
the .pytest_cache/, .ruff_cache/, .mypy_cache/, build/, and
.venv/ directories, and the .coverage/.coverage.* data files. It is
idempotent (absent targets are a successful no-op), never touches tracked
files, untracked user files, $HOME application data, or the versioned
release artifacts in dist/, and never runs destructive git commands.
# Remove all execution-generated temporary artifacts
./scripts/clean.sh
# Build from the canonical cleaned state (also via clean.sh)
./scripts/build.sh
Release automation
For every canonical version tag vX.Y.Z the release workflow
(.github/workflows/release-pypi.yml) creates a GitHub release from the
dist/ artifacts present at the tagged commit and, when the tag belongs to
master, publishes them to PyPI through OIDC Trusted Publishing. No build
step runs inside the workflow; runners are pinned to ubuntu-24.04.
Using this repository as a template
This repository doubles as the GitHub template
Ogekuri/GitHub-Template-AstralUV
for new Astral-UV applications. Template initialization extracts a skeleton
bundle into the working directory and resolves seven keywords
(%AUTHOR%, %DESCRIPTION%, %PROGRAM%, %SHORTNAME%, %SRCDIR%,
%OWNER%, %REPOSITORY%) across the repository files, then renames the
skeleton script and package directories to the substituted names. The full
procedure is specified in usereq/docs/REQUIREMENTS.md.
Development and testing
# Run the unit-test suite
uv run pytest
# Full release-readiness verification (fail-fast, leaves no artifacts)
./scripts/pre-release-check.sh
The test suite covers the help screen, version report, management-command argv variants, the gated version check and its cache, the configuration CLI, the release-workflow contract, and the packaging artifacts.
License
This project is licensed under the GNU General Public License v3.0 only
(SPDX identifier GPL-3.0-only), as declared in pyproject.toml.
The full license text is available in the LICENSE file.
Copyright (c) Francesco Rolando.
Acknowledgments
- Astral — for
uvanduvx, the packaging and distribution backbone of this template. - PI-useReq — the requirement-driven agentic workflow used to specify, implement, and document this repository.
- PyPA — for
buildand the Python packaging standards used by the release pipeline. - Shields.io — for the README badges.
Metadata
Release files for githubtemplateastraluv 0.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| githubtemplateastraluv-0.0.4.tar.gz | 56.4 kB | With provenance | Details for githubtemplateastraluv-0.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| githubtemplateastraluv-0.0.4-py3-none-any.whl | Python 3 | none | any | Details for githubtemplateastraluv-0.0.4-py3-none-any.whl |
Total release size: 100.4 kB
Release files / githubtemplateastraluv-0.0.4.tar.gz
| Download URL | githubtemplateastraluv-0.0.4.tar.gz |
|---|---|
| Size | 56.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2271d97017745da0e78a2373b9c8be146c059df82fc6ae24ff61e6fe61bc2006
|
|
BLAKE2b-256 checksum How to use checksums |
13bf5055ad492ffc81eddb99ff7e51581690c6ad984a5651db7ec623eef80a4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / githubtemplateastraluv-0.0.4-py3-none-any.whl
| Download URL | githubtemplateastraluv-0.0.4-py3-none-any.whl |
|---|---|
| Size | 44.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8f4a9dc233790d22629a0b4ff5ae940b5397078cd9c40bccfd3f3a2cfac37d4b
|
|
BLAKE2b-256 checksum How to use checksums |
e585aca96433be5103bf37141a28d14941b20de6f753bb468c95b050fe8f3070
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for githubtemplateastraluv 0.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for githubtemplateastraluv-0.0.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.