Skip to main content

githubtemplateastraluv / templateastraluv (0.0.4)

Python 3.11+ License: GPL-3.0 Platforms Docs uv

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 with uvx 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 master tags.

Quick Start

  1. Install the tool from PyPI:

    uv tool install githubtemplateastraluv
    
  2. 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.

  3. 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) and api.github.com (latest-release query for the --ver report and --develop channel).
  • Linux — required for the --upgrade and --uninstall side 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:

  • notifications assigns the new-version color bright_green (ANSI SGR 92) and the error color bright_red (ANSI SGR 91).
  • palette maps 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/json runs 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.
  • --ver and --version bypass the gate and always query both sources (PyPI JSON API and https://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 uv and uvx, 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 build and 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)

Source distribution for githubtemplateastraluv 0.0.4
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)

Table of built distributions (wheels) for githubtemplateastraluv 0.0.4
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.0.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page