Metadata-Version: 2.4
Name: githubtemplateastraluv
Version: 0.0.2
Summary: GitHub template for Astral-UV app.
Author: Francesco Rolando
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/Ogekuri/GitHub-Template-AstralUV
Project-URL: Repository, https://github.com/Ogekuri/GitHub-Template-AstralUV
Keywords: shell,scripts,uv,astral,uvx,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# githubtemplateastraluv/templateastraluv (0.0.2)

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/license-GPL--3.0-491?style=flat-square" alt="License: GPL-3.0">
  <img src="https://img.shields.io/badge/platform-Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
  <img src="https://img.shields.io/badge/docs-live-b31b1b" alt="Docs">
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
</p>
<p align="center">
<strong>GitHub template for Astral-UV apps published on PyPI.</strong><br>
Python CLI template with Astral uv/uvx packaging, PyPI OIDC Trusted
Publishing release automation, self-upgrade from PyPI (or the latest
GitHub tag via <code>--develop</code>), and a dual-source version report.
</p>


<p align="center">
  <a href="#quick-start">Quick Start</a> |
  <a href="#feature-highlights">Feature Highlights</a> |
  <a href="#acknowledgments">Acknowledgments</a>
</p>

<p align="center">
<br>
🚧 <strong>DRAFT</strong>: 👾 Alpha Development 👾 - Work in Progress 🏗️ 🚧<br>
⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://github.com/ogekuri/useReq"><strong>useReq/req</strong></a> 🤖✨ ⚠️<br>
<br>
<p>


## Feature Highlights
- Published on PyPI: install with `uv tool install githubtemplateastraluv`.
- Automatic online new-version check (PyPI) throttled by an idle-time cache.
- `--ver` dual-source report: installed, latest PyPI, and latest GitHub versions, with aligned columns.
- Self-upgrade from PyPI; `--upgrade --develop` pulls the latest GitHub tagged release; `--upgrade --force` forces full re-download and reinstallation.
- Colored console notifications with user-configurable colors.
- Release automation: GitHub release for every version tag; OIDC Trusted Publishing to PyPI for `master` tags only.


## Quick Start

1. Install the tool from PyPI:
```bash
uv tool install githubtemplateastraluv
```
2. Run it:
```bash
githubtemplateastraluv --help
```

## Usage

```bash
# Print the version report (aligned columns)
githubtemplateastraluv --ver
```

Output format:
```
Current Installed : X1.Y1.Z1
Latest @ PyPI     : X2.Y2.Z2
Latest @ GitHub   : X3.Y3.Z3
```

```bash
# Upgrade from PyPI (Linux; prints the manual command elsewhere)
githubtemplateastraluv --upgrade

# Force full re-download and reinstallation from PyPI
githubtemplateastraluv --upgrade --force

# Upgrade to the latest GitHub tagged release (any branch)
githubtemplateastraluv --upgrade --develop

# Force full re-download and reinstallation from GitHub
githubtemplateastraluv --upgrade --develop --force

# Uninstall (Linux; prints the manual command elsewhere)
githubtemplateastraluv --uninstall

# Full help screen
githubtemplateastraluv --help
```


## Install with Astral uv (PyPI — primary method)

#### Install
```bash
uv tool install githubtemplateastraluv
```

#### Upgrade
```bash
githubtemplateastraluv --upgrade
```

#### Uninstall
```bash
uv tool uninstall githubtemplateastraluv
```

## Live execution with uvx (alternative method)

Run githubtemplateastraluv directly from PyPI without prior installation:

```bash
uvx githubtemplateastraluv
```

You can pass options as usual, for example:

```bash
uvx githubtemplateastraluv <args>
```

## Install and upgrade from GitHub (development releases)

A dedicated, non-primary distribution channel hosts intermediate and test
releases on GitHub: `https://github.com/Ogekuri/GitHub-Template-AstralUV`.

#### Install
```bash
uv tool install githubtemplateastraluv --force --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git
```

#### Upgrade to the latest GitHub tagged release (any branch)
```bash
githubtemplateastraluv --upgrade --develop
```

#### Force full re-download and reinstallation
```bash
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
(`master`, `develop`, or any other branch). The `--ver` report shows the
GitHub latest release in the `Latest @ GitHub` row.
```


## 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.
`scripts/build.sh` delegates its pre-build cleanup to `scripts/clean.sh`,
so two consecutive builds always start from the identical state:

```bash
# Remove all execution-generated temporary artifacts
./scripts/clean.sh

# Build from the canonical cleaned state (also via clean.sh)
./scripts/build.sh
```


## Acknowledgments

TODO: fill scknowledgments section

