githubtemplateastraluv 0.0.2__tar.gz → 0.0.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. githubtemplateastraluv-0.0.4/PKG-INFO +362 -0
  2. githubtemplateastraluv-0.0.4/README.md +342 -0
  3. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/pyproject.toml +1 -1
  4. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/__init__.py +1 -1
  5. githubtemplateastraluv-0.0.4/src/githubtemplateastraluv/colors.py +67 -0
  6. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/config.py +93 -108
  7. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/config_render.py +20 -10
  8. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/management.py +38 -11
  9. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/version_check.py +23 -24
  10. githubtemplateastraluv-0.0.4/src/githubtemplateastraluv.egg-info/PKG-INFO +362 -0
  11. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv.egg-info/SOURCES.txt +1 -0
  12. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/tests/test_githubtemplateastraluv.py +69 -9
  13. githubtemplateastraluv-0.0.2/PKG-INFO +0 -196
  14. githubtemplateastraluv-0.0.2/README.md +0 -176
  15. githubtemplateastraluv-0.0.2/src/githubtemplateastraluv.egg-info/PKG-INFO +0 -196
  16. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/LICENSE +0 -0
  17. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/setup.cfg +0 -0
  18. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/__main__.py +0 -0
  19. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv/core.py +0 -0
  20. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv.egg-info/dependency_links.txt +0 -0
  21. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv.egg-info/entry_points.txt +0 -0
  22. {githubtemplateastraluv-0.0.2 → githubtemplateastraluv-0.0.4}/src/githubtemplateastraluv.egg-info/top_level.txt +0 -0
@@ -0,0 +1,362 @@
1
+ Metadata-Version: 2.4
2
+ Name: githubtemplateastraluv
3
+ Version: 0.0.4
4
+ Summary: GitHub template for Astral-UV app.
5
+ Author: Francesco Rolando
6
+ License-Expression: GPL-3.0-only
7
+ Project-URL: Homepage, https://github.com/Ogekuri/GitHub-Template-AstralUV
8
+ Project-URL: Repository, https://github.com/Ogekuri/GitHub-Template-AstralUV
9
+ Keywords: shell,scripts,uv,astral,uvx,cli
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: Utilities
16
+ Requires-Python: >=3.11
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ > [!CAUTION]
22
+ > **STRICTLY EXPERIMENTAL**: this project is a proof-of-concept template under
23
+ > active development. Interfaces, commands, packaging metadata, and release
24
+ > channels may change at any time without notice. Do not rely on it for
25
+ > production workloads.
26
+
27
+ # githubtemplateastraluv / templateastraluv (0.0.4)
28
+
29
+ <p align="center">
30
+ <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
31
+ <img src="https://img.shields.io/badge/license-GPL--3.0-491?style=flat-square" alt="License: GPL-3.0">
32
+ <img src="https://img.shields.io/badge/platform-Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
33
+ <img src="https://img.shields.io/badge/docs-live-b31b1b" alt="Docs">
34
+ <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
35
+ </p>
36
+ <p align="center">
37
+ <strong>GitHub template for Astral-UV apps published on PyPI.</strong><br>
38
+ A Python CLI application shipped as an Astral uv/uvx-installable tool with
39
+ PyPI OIDC Trusted Publishing release automation. It provides management
40
+ commands for upgrade, uninstall, and version reporting; an automatic
41
+ new-version check throttled by an idle-time cache; self-upgrade from PyPI or
42
+ from the latest GitHub tag via <code>--develop</code>; a dual-source version
43
+ report (installed / PyPI / GitHub); and a JSON-configurable
44
+ notification-color subsystem with validated, atomic persistence.
45
+ </p>
46
+
47
+ <p align="center">
48
+ <a href="#feature-highlights">Feature Highlights</a> |
49
+ <a href="#quick-start">Quick Start</a> |
50
+ <a href="#requirements">Requirements</a> |
51
+ <a href="#users-guide">User's Guide</a> |
52
+ <a href="#acknowledgments">Acknowledgments</a>
53
+ </p>
54
+
55
+ <p align="center">
56
+ 🚧 <strong>STAGE:</strong> PRE-ALPHA 📝 - Proof-of-Concept 🏗️ 🚧<br>
57
+ ⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://github.com/Ogekuri/PI-useReq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️
58
+ </p>
59
+
60
+ # Feature Highlights
61
+
62
+ - **Published on PyPI**: install with `uv tool install githubtemplateastraluv`, or run on-the-fly with `uvx githubtemplateastraluv`.
63
+ - **Dual-source version report** (`--ver` / `--version`): installed, latest PyPI, and latest GitHub versions in aligned columns.
64
+ - **Automatic new-version check** before every run, throttled by an idle-time cache so no redundant network calls are made.
65
+ - **Self-upgrade** from PyPI (`--upgrade`), forced full re-download (`--force`), or the latest GitHub tagged release (`--develop`).
66
+ - **One-command removal** (`--uninstall`) — on non-Linux systems the exact manual command is printed instead.
67
+ - **Colored console notifications** (bright green for availability, bright red for errors), hardcoded in the embedded internal color JSON of `src/githubtemplateastraluv/colors.py`.
68
+ - **Configuration CLI** (`--get`, `--set`, `--unset`, `--print`, `--info`, `--print-raw`) with schema validation and atomic persistence.
69
+ - **Release automation**: a GitHub release for every version tag and OIDC Trusted Publishing to PyPI for `master` tags.
70
+
71
+ # Quick Start
72
+
73
+ 1. **Install** the tool from PyPI:
74
+
75
+ ```bash
76
+ uv tool install githubtemplateastraluv
77
+ ```
78
+
79
+ 2. **Configure** — optional: the application works out of the box with
80
+ sensible defaults (bright green availability notes, bright red error
81
+ notes). Customization is described in the [User's Guide](#users-guide).
82
+
83
+ 3. **Execute**:
84
+
85
+ ```bash
86
+ githubtemplateastraluv --help
87
+ githubtemplateastraluv --ver
88
+ ```
89
+
90
+ # Requirements
91
+
92
+ - **Python >= 3.11**.
93
+ - **Astral `uv`** — required to install, upgrade, uninstall, or run the tool locally from the repository.
94
+ - **`git`** — required only to install the development source with `--develop`.
95
+ - **Network access** — outbound HTTPS to `pypi.org` (version check, upgrades) and `api.github.com` (latest-release query for the `--ver` report and `--develop` channel).
96
+ - **Linux** — required for the `--upgrade` and `--uninstall` side effects; on any other platform the tool prints a warning and the exact manual command.
97
+ - **ANSI-capable terminal** — required for colored notifications.
98
+
99
+ # User's Guide
100
+
101
+ ## Install from PyPI (primary method)
102
+
103
+ ```bash
104
+ uv tool install githubtemplateastraluv
105
+ ```
106
+
107
+ Upgrade and uninstall:
108
+
109
+ ```bash
110
+ githubtemplateastraluv --upgrade
111
+ uv tool uninstall githubtemplateastraluv
112
+ ```
113
+
114
+ ## Live execution with uvx (alternative method)
115
+
116
+ Run directly from PyPI without a prior installation:
117
+
118
+ ```bash
119
+ uvx githubtemplateastraluv
120
+ uvx githubtemplateastraluv --ver
121
+ ```
122
+
123
+ ## Install and upgrade from GitHub (non-primary development channel)
124
+
125
+ A dedicated, non-primary distribution channel hosts intermediate and test
126
+ releases on GitHub: `https://github.com/Ogekuri/GitHub-Template-AstralUV`.
127
+
128
+ ```bash
129
+ # Install from the GitHub repository
130
+ uv tool install githubtemplateastraluv --force --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git
131
+
132
+ # Upgrade to the latest GitHub tagged release (tagged on any branch)
133
+ githubtemplateastraluv --upgrade --develop
134
+
135
+ # Forced full re-download and reinstallation variants
136
+ githubtemplateastraluv --upgrade --force
137
+ githubtemplateastraluv --upgrade --develop --force
138
+ ```
139
+
140
+ `--upgrade --develop` always downloads the most recent tagged build from
141
+ GitHub, regardless of the branch it was tagged on. The `--ver` report shows
142
+ that channel in the `Latest @ GitHub` row.
143
+
144
+ ## Run locally from the repository
145
+
146
+ ```bash
147
+ ./scripts/templateastraluv.sh --help
148
+ ```
149
+
150
+ The launcher resolves the repository root and delegates to
151
+ `uv run --project <root> python -m githubtemplateastraluv`.
152
+
153
+ ## Command reference
154
+
155
+ The full help screen (printed by `--help` or by running the tool with no
156
+ arguments):
157
+
158
+ ```text
159
+ Usage: githubtemplateastraluv [command] [options] (0.0.4)
160
+
161
+ Management Commands:
162
+ --upgrade - Reinstall githubtemplateastraluv on Linux; print manual command elsewhere.
163
+ --uninstall - Uninstall githubtemplateastraluv on Linux; print manual command elsewhere.
164
+ --ver - Print the githubtemplateastraluv version.
165
+ --version - Print the githubtemplateastraluv version.
166
+ --help - Print the full help screen.
167
+
168
+ Configuration Commands:
169
+ --get - Print the value at Path as one JSON document.
170
+ --set - Parse Value into the schema type and persist it at Path.
171
+ --unset - Restore Path to its schema default and persist atomically.
172
+ --print - Print current values as a box-drawing tree, whole schema or at Path.
173
+ --info - Print parameter documentation with defaults, constraints, and examples.
174
+ --print-raw - Print the exact bytes of the configuration JSON file.
175
+
176
+ Options:
177
+ --develop - With --upgrade: install from the GitHub development source.
178
+ --force - With --upgrade: force full re-download and reinstallation.
179
+ ```
180
+
181
+ ### Version report (`--ver` / `--version`)
182
+
183
+ Prints the three-row report with aligned version columns and always refreshes
184
+ the source queries, bypassing the idle-time gate:
185
+
186
+ ```text
187
+ Current Installed : X1.Y1.Z1
188
+ Latest @ PyPI : X2.Y2.Z2
189
+ Latest @ GitHub : X3.Y3.Z3
190
+ ```
191
+
192
+ A failed source prints `unknown (<reason>)` in place of the version, with a
193
+ bright red note naming that source. The GitHub row strips the `v` prefix from
194
+ the latest release tag.
195
+
196
+ ### `--upgrade` variants (Linux)
197
+
198
+ | Command | Executed command |
199
+ | --- | --- |
200
+ | `--upgrade` | `uv tool install githubtemplateastraluv` |
201
+ | `--upgrade --force` | `uv tool install githubtemplateastraluv --force --reinstall --refresh` |
202
+ | `--upgrade --develop` | `uv tool install githubtemplateastraluv --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git` |
203
+ | `--upgrade --develop --force` | `uv tool install githubtemplateastraluv --force --reinstall --refresh --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git` |
204
+
205
+ On non-Linux operating systems nothing is executed: the tool prints a warning
206
+ and the matching manual command from the table. `--develop` and `--force` are
207
+ accepted exclusively as `--upgrade` modifiers; any other combination falls
208
+ back to the normal dispatch behavior.
209
+
210
+ ### `--uninstall` (Linux)
211
+
212
+ ```bash
213
+ githubtemplateastraluv --uninstall
214
+ ```
215
+
216
+ Executes `uv tool uninstall githubtemplateastraluv` on Linux; on any other
217
+ platform it prints a warning and the manual command
218
+ `uv tool uninstall githubtemplateastraluv`.
219
+
220
+ ## Configuration
221
+
222
+ ### Configuration file
223
+
224
+ The global configuration lives at
225
+ `$HOME/.config/githubtemplateastraluv/config.json`. It is created with the
226
+ schema defaults on the first configuration command and every update is
227
+ validated against the schema and persisted atomically (the previous file is
228
+ preserved if any step fails).
229
+
230
+ ### Configuration commands
231
+
232
+ Configuration paths are case-sensitive, colon-separated canonical tokens
233
+ (`Section`, `Section:Parameter`); the schema currently defines no sections,
234
+ so every canonical path is rejected.
235
+
236
+ | Command | Behavior |
237
+ | --- | --- |
238
+ | `--get <Path>` | Prints the resolved value as one valid JSON document on stdout. |
239
+ | `--set <Path> <Value>` | Parses `Value` into the schema type, validates, and persists atomically. |
240
+ | `--unset <Path>` | Restores the targeted parameter or section to its schema default. |
241
+ | `--print [Path]` | Renders current values as a box-drawing tree with `[Path: <canonical path>]` section headings. |
242
+ | `--info [Path]` | Renders per-parameter type, constraints, description, default, and shell-valid `--set` / `--unset` examples. |
243
+ | `--print-raw` | Writes the exact bytes of the configuration JSON file to stdout. |
244
+
245
+ Examples:
246
+
247
+ ```bash
248
+ githubtemplateastraluv --print
249
+ githubtemplateastraluv --info
250
+ githubtemplateastraluv --print-raw
251
+
252
+ # The schema currently defines no sections: every canonical path is
253
+ # rejected with exit status 1 and a stderr diagnostic.
254
+ githubtemplateastraluv --get Notifications:new_version_color
255
+ ```
256
+
257
+ On any configuration failure the tool exits with code `1`, prints a
258
+ diagnostic on stderr, and emits nothing on stdout.
259
+
260
+ ### Notification colors (hardcoded)
261
+
262
+ Notification colors are not configurable. All colors live in one embedded
263
+ internal JSON document (`COLOR_CONFIG_JSON`) inside
264
+ `src/githubtemplateastraluv/colors.py`:
265
+
266
+ - `notifications` assigns the new-version color `bright_green` (ANSI SGR 92)
267
+ and the error color `bright_red` (ANSI SGR 91).
268
+ - `palette` maps every color token to its ANSI SGR prefix: `bright_green`
269
+ (92), `bright_red` (91), `bright_yellow` (93), `bright_blue` (94),
270
+ `bright_magenta` (95), `bright_cyan` (96), `bright_white` (97).
271
+
272
+ Both colors drive the automatic version-check notifications; no CLI option,
273
+ file, or environment variable can alter them.
274
+
275
+ # Documentation
276
+
277
+ ## Automatic version check
278
+
279
+ On every invocation the tool runs an online new-version check **before**
280
+ argument parsing. The check is throttled by an idle-time cache:
281
+
282
+ - Cache file: `$HOME/.cache/githubtemplateastraluv/check_version_idle-time.json`.
283
+ - The HTTPS request to `https://pypi.org/pypi/githubtemplateastraluv/json` runs
284
+ only when the cache file is absent or the cached idle-time has elapsed
285
+ (2-second timeout).
286
+ - A successful check refreshes the cache with a 3600-second idle-delay; a
287
+ failed check (HTTP 429, 503, timeout, network error) reports a bright red
288
+ error note and backs off with an 86400-second idle-delay.
289
+ - `--ver` and `--version` bypass the gate and always query both sources
290
+ (PyPI JSON API and `https://api.github.com/repos/Ogekuri/GitHub-Template-AstralUV/releases/latest`).
291
+
292
+ ## Repository tooling scripts
293
+
294
+ | Script | Purpose |
295
+ | --- | --- |
296
+ | `scripts/templateastraluv.sh` | Local-run launcher delegating to `uv run --project <root> python -m githubtemplateastraluv`. |
297
+ | `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. |
298
+ | `scripts/clean.sh` | Removes every repository-internal execution-generated artifact and restores the canonical startup state. |
299
+ | `scripts/pre-release-check.sh` | Fail-fast release verification (syntax, compileall, pytest, out-of-tree build, artifact validation) with baseline-guarded cleanup. |
300
+
301
+ `scripts/clean.sh` removes `__pycache__/` and `*.egg-info/` at any depth,
302
+ the `.pytest_cache/`, `.ruff_cache/`, `.mypy_cache/`, `build/`, and
303
+ `.venv/` directories, and the `.coverage`/`.coverage.*` data files. It is
304
+ idempotent (absent targets are a successful no-op), never touches tracked
305
+ files, untracked user files, `$HOME` application data, or the versioned
306
+ release artifacts in `dist/`, and never runs destructive git commands.
307
+
308
+ ```bash
309
+ # Remove all execution-generated temporary artifacts
310
+ ./scripts/clean.sh
311
+
312
+ # Build from the canonical cleaned state (also via clean.sh)
313
+ ./scripts/build.sh
314
+ ```
315
+
316
+ ## Release automation
317
+
318
+ For every canonical version tag `vX.Y.Z` the release workflow
319
+ (`.github/workflows/release-pypi.yml`) creates a GitHub release from the
320
+ `dist/` artifacts present at the tagged commit and, when the tag belongs to
321
+ `master`, publishes them to PyPI through OIDC Trusted Publishing. No build
322
+ step runs inside the workflow; runners are pinned to `ubuntu-24.04`.
323
+
324
+ ## Using this repository as a template
325
+
326
+ This repository doubles as the GitHub template
327
+ [`Ogekuri/GitHub-Template-AstralUV`](https://github.com/Ogekuri/GitHub-Template-AstralUV)
328
+ for new Astral-UV applications. Template initialization extracts a skeleton
329
+ bundle into the working directory and resolves seven keywords
330
+ (`%AUTHOR%`, `%DESCRIPTION%`, `%PROGRAM%`, `%SHORTNAME%`, `%SRCDIR%`,
331
+ `%OWNER%`, `%REPOSITORY%`) across the repository files, then renames the
332
+ skeleton script and package directories to the substituted names. The full
333
+ procedure is specified in `usereq/docs/REQUIREMENTS.md`.
334
+
335
+ ## Development and testing
336
+
337
+ ```bash
338
+ # Run the unit-test suite
339
+ uv run pytest
340
+
341
+ # Full release-readiness verification (fail-fast, leaves no artifacts)
342
+ ./scripts/pre-release-check.sh
343
+ ```
344
+
345
+ The test suite covers the help screen, version report, management-command
346
+ argv variants, the gated version check and its cache, the configuration CLI,
347
+ the release-workflow contract, and the packaging artifacts.
348
+
349
+ # License
350
+
351
+ This project is licensed under the **GNU General Public License v3.0 only**
352
+ (SPDX identifier `GPL-3.0-only`), as declared in `pyproject.toml`.
353
+ The full license text is available in the [`LICENSE`](LICENSE) file.
354
+
355
+ Copyright (c) Francesco Rolando.
356
+
357
+ # Acknowledgments
358
+
359
+ - **[Astral](https://github.com/astral-sh/uv)** — for `uv` and `uvx`, the packaging and distribution backbone of this template.
360
+ - **[PI-useReq](https://github.com/Ogekuri/PI-useReq)** — the requirement-driven agentic workflow used to specify, implement, and document this repository.
361
+ - **[PyPA](https://github.com/pypa)** — for `build` and the Python packaging standards used by the release pipeline.
362
+ - **[Shields.io](https://shields.io)** — for the README badges.