githubtemplateastraluv 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl
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.
- githubtemplateastraluv/__init__.py +1 -1
- githubtemplateastraluv/colors.py +67 -0
- githubtemplateastraluv/config.py +93 -108
- githubtemplateastraluv/config_render.py +20 -10
- githubtemplateastraluv/management.py +38 -11
- githubtemplateastraluv/version_check.py +23 -24
- githubtemplateastraluv-0.0.4.dist-info/METADATA +362 -0
- githubtemplateastraluv-0.0.4.dist-info/RECORD +14 -0
- githubtemplateastraluv-0.0.2.dist-info/METADATA +0 -196
- githubtemplateastraluv-0.0.2.dist-info/RECORD +0 -13
- {githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/WHEEL +0 -0
- {githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/entry_points.txt +0 -0
- {githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/licenses/LICENSE +0 -0
- {githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/top_level.txt +0 -0
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
# checks; single source of truth consumed by core.main dispatch
|
|
9
9
|
# and mirrored in pyproject.toml, scripts/templateastraluv.sh,
|
|
10
10
|
# README.md, and uv.lock per .g.conf ver_rules.
|
|
11
|
-
__version__ = "0.0.
|
|
11
|
+
__version__ = "0.0.4"
|
|
12
12
|
|
|
13
13
|
from githubtemplateastraluv.core import main # noqa: F401
|
|
14
14
|
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
## @file colors.py
|
|
3
|
+
# @brief Hardcoded notification-color registry embedded as one internal
|
|
4
|
+
# JSON document.
|
|
5
|
+
# @details Single source of truth for every notification color (REQ-040):
|
|
6
|
+
# the embedded JSON assigns the new-version and error color
|
|
7
|
+
# tokens (REQ-041) and maps every color token to its ANSI SGR
|
|
8
|
+
# prefix. No CLI option, file, or environment surface can alter
|
|
9
|
+
# these values; parsing happens once at import and cannot fail
|
|
10
|
+
# at runtime.
|
|
11
|
+
import json
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
## @brief Embedded internal JSON document with the hardcoded color
|
|
15
|
+
# configuration (REQ-040).
|
|
16
|
+
# @details Object shape: `notifications` maps `new_version_color` and
|
|
17
|
+
# `error_color` to palette tokens (REQ-041 assignment:
|
|
18
|
+
# `bright_green` / `bright_red`); `palette` maps every color
|
|
19
|
+
# token to its ANSI SGR prefix `ESC [ <code> m`. Escape
|
|
20
|
+
# sequences use the JSON `\u001b` form so the source stays
|
|
21
|
+
# pure printable ASCII. `json.loads` preserves object order, so
|
|
22
|
+
# palette iteration order equals declaration order.
|
|
23
|
+
COLOR_CONFIG_JSON = (
|
|
24
|
+
"{\n"
|
|
25
|
+
' "notifications": {\n'
|
|
26
|
+
' "new_version_color": "bright_green",\n'
|
|
27
|
+
' "error_color": "bright_red"\n'
|
|
28
|
+
" },\n"
|
|
29
|
+
' "palette": {\n'
|
|
30
|
+
' "bright_green": "\\u001b[92m",\n'
|
|
31
|
+
' "bright_red": "\\u001b[91m",\n'
|
|
32
|
+
' "bright_yellow": "\\u001b[93m",\n'
|
|
33
|
+
' "bright_blue": "\\u001b[94m",\n'
|
|
34
|
+
' "bright_magenta": "\\u001b[95m",\n'
|
|
35
|
+
' "bright_cyan": "\\u001b[96m",\n'
|
|
36
|
+
' "bright_white": "\\u001b[97m"\n'
|
|
37
|
+
" }\n"
|
|
38
|
+
"}"
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
## @brief Parsed embedded color configuration (REQ-040).
|
|
42
|
+
# @details Shape: `{"notifications": {"new_version_color": str,
|
|
43
|
+
# "error_color": str}, "palette": {token: ANSI SGR prefix}}`.
|
|
44
|
+
COLOR_CONFIG: dict[str, Any] = json.loads(COLOR_CONFIG_JSON)
|
|
45
|
+
|
|
46
|
+
## @brief Ordered palette of color token to ANSI SGR prefix.
|
|
47
|
+
# @details Shared registry view of `COLOR_CONFIG["palette"]` consumed by
|
|
48
|
+
# the renderer documentation tables; insertion order equals the
|
|
49
|
+
# embedded JSON declaration order.
|
|
50
|
+
PALETTE: dict[str, str] = COLOR_CONFIG["palette"]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def notification_colors() -> dict[str, str]:
|
|
54
|
+
"""@brief Resolve the hardcoded ANSI prefixes for notifications.
|
|
55
|
+
|
|
56
|
+
@details Selects `PALETTE` entries through the
|
|
57
|
+
`COLOR_CONFIG["notifications"]` assignment (REQ-041);
|
|
58
|
+
hardcoded values need no I/O and cannot fail (REQ-026).
|
|
59
|
+
@return {dict[str, str]} Mapping with `new_version_color` and
|
|
60
|
+
`error_color` ANSI SGR prefix strings.
|
|
61
|
+
@satisfies REQ-026 REQ-040 REQ-041
|
|
62
|
+
"""
|
|
63
|
+
assignments = COLOR_CONFIG["notifications"]
|
|
64
|
+
return {
|
|
65
|
+
"new_version_color": PALETTE[assignments["new_version_color"]],
|
|
66
|
+
"error_color": PALETTE[assignments["error_color"]],
|
|
67
|
+
}
|
githubtemplateastraluv/config.py
CHANGED
|
@@ -18,21 +18,6 @@ from dataclasses import dataclass
|
|
|
18
18
|
from pathlib import Path
|
|
19
19
|
from typing import Any
|
|
20
20
|
|
|
21
|
-
## @brief Ordered mapping of Selection enum token to ANSI SGR prefix.
|
|
22
|
-
# @details Insertion order defines enum display order (REQ-025).
|
|
23
|
-
COLOR_ANSI: dict[str, str] = {
|
|
24
|
-
"bright_green": "\033[92m",
|
|
25
|
-
"bright_red": "\033[91m",
|
|
26
|
-
"bright_yellow": "\033[93m",
|
|
27
|
-
"bright_blue": "\033[94m",
|
|
28
|
-
"bright_magenta": "\033[95m",
|
|
29
|
-
"bright_cyan": "\033[96m",
|
|
30
|
-
"bright_white": "\033[97m",
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
## @brief Ordered Selection enum tokens shared by both parameters (REQ-025).
|
|
34
|
-
_SELECTION_ENUM: tuple[str, ...] = tuple(COLOR_ANSI)
|
|
35
|
-
|
|
36
21
|
## @brief Global configuration directory segments relative to `$HOME`.
|
|
37
22
|
_CONFIG_DIR_SEGMENTS: tuple[str, ...] = (
|
|
38
23
|
".config",
|
|
@@ -59,7 +44,7 @@ class ParamSpec:
|
|
|
59
44
|
description: str
|
|
60
45
|
## @brief Schema default value restored by `--unset` (REQ-018).
|
|
61
46
|
default: str
|
|
62
|
-
## @brief Ordered allowed values for Selection parameters
|
|
47
|
+
## @brief Ordered allowed values for Selection parameters.
|
|
63
48
|
enum: tuple[str, ...]
|
|
64
49
|
|
|
65
50
|
@property
|
|
@@ -98,30 +83,12 @@ class SectionSpec:
|
|
|
98
83
|
return None
|
|
99
84
|
|
|
100
85
|
|
|
101
|
-
## @brief Canonical configuration schema (DES-010
|
|
102
|
-
# @details Insertion order defines canonical display order.
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
params=(
|
|
108
|
-
ParamSpec(
|
|
109
|
-
token="new_version_color",
|
|
110
|
-
type_label="Selection",
|
|
111
|
-
description="ANSI color of the new-version availability note.",
|
|
112
|
-
default="bright_green",
|
|
113
|
-
enum=_SELECTION_ENUM,
|
|
114
|
-
),
|
|
115
|
-
ParamSpec(
|
|
116
|
-
token="error_color",
|
|
117
|
-
type_label="Selection",
|
|
118
|
-
description="ANSI color of the version-check failure note.",
|
|
119
|
-
default="bright_red",
|
|
120
|
-
enum=_SELECTION_ENUM,
|
|
121
|
-
),
|
|
122
|
-
),
|
|
123
|
-
),
|
|
124
|
-
)
|
|
86
|
+
## @brief Canonical configuration schema (DES-010).
|
|
87
|
+
# @details Insertion order defines canonical display order. The schema
|
|
88
|
+
# currently defines no sections: notification colors are
|
|
89
|
+
# hardcoded in the embedded internal color JSON of `colors.py`
|
|
90
|
+
# (REQ-040), so every canonical path is rejected (REQ-022).
|
|
91
|
+
SCHEMA: tuple[SectionSpec, ...] = ()
|
|
125
92
|
|
|
126
93
|
## @brief Schema token to SectionSpec index for O(1) path resolution.
|
|
127
94
|
_SECTIONS_BY_TOKEN: dict[str, SectionSpec] = {
|
|
@@ -170,8 +137,8 @@ def validate_config(payload: Any) -> None:
|
|
|
170
137
|
|
|
171
138
|
@details Strict validation: JSON object root, exact section key set,
|
|
172
139
|
exact parameter key set per section, and Selection values
|
|
173
|
-
restricted to the
|
|
174
|
-
|
|
140
|
+
restricted to the parameter enum. Raises without mutation;
|
|
141
|
+
callers reject the operation on error.
|
|
175
142
|
@param payload {Any} Parsed JSON configuration payload.
|
|
176
143
|
@return {None}
|
|
177
144
|
@throws {ConfigError} On root-type, section-key, parameter-key, or
|
|
@@ -275,10 +242,9 @@ def atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
|
|
|
275
242
|
def ensure_bootstrapped() -> None:
|
|
276
243
|
"""@brief Create missing directories and initialize missing defaults.
|
|
277
244
|
|
|
278
|
-
@details Applicable configuration commands call this before
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
errors.
|
|
245
|
+
@details Applicable configuration commands call this before
|
|
246
|
+
executing. Never overwrites an existing file, valid or
|
|
247
|
+
not; strict loaders surface invalid files as errors.
|
|
282
248
|
@return {None}
|
|
283
249
|
@throws {ConfigError} When directories cannot be created or the
|
|
284
250
|
default file cannot be written.
|
|
@@ -294,15 +260,15 @@ def ensure_bootstrapped() -> None:
|
|
|
294
260
|
raise ConfigError(f"cannot initialize configuration: {error}")
|
|
295
261
|
|
|
296
262
|
|
|
297
|
-
def
|
|
298
|
-
"""@brief
|
|
263
|
+
def _read_payload() -> Any:
|
|
264
|
+
"""@brief Read and parse the persisted configuration JSON document.
|
|
299
265
|
|
|
300
|
-
@details
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
@return {
|
|
304
|
-
@throws {ConfigError} When the file is absent, unreadable,
|
|
305
|
-
JSON
|
|
266
|
+
@details Resolves `config_path`, requires an existing file, reads it
|
|
267
|
+
as UTF-8 text, and parses the JSON document; every failure
|
|
268
|
+
raises without returning a partial result (REQ-023).
|
|
269
|
+
@return {Any} Parsed JSON payload.
|
|
270
|
+
@throws {ConfigError} When the file is absent, unreadable, or
|
|
271
|
+
malformed JSON.
|
|
306
272
|
"""
|
|
307
273
|
path = config_path()
|
|
308
274
|
if not path.exists():
|
|
@@ -312,26 +278,61 @@ def load_strict() -> dict[str, dict[str, str]]:
|
|
|
312
278
|
except OSError as error:
|
|
313
279
|
raise ConfigError(f"cannot read configuration file: {error}")
|
|
314
280
|
try:
|
|
315
|
-
|
|
281
|
+
return json.loads(text)
|
|
316
282
|
except ValueError as error:
|
|
317
283
|
raise ConfigError(f"invalid JSON in {path}: {error}")
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def load_strict() -> dict[str, dict[str, str]]:
|
|
287
|
+
"""@brief Load and strictly validate the global configuration.
|
|
288
|
+
|
|
289
|
+
@details Reads the file selected by `config_path`, parses JSON, and
|
|
290
|
+
applies `validate_config`; every failure raises instead of
|
|
291
|
+
partially succeeding (REQ-022, REQ-023).
|
|
292
|
+
@return {dict[str, dict[str, str]]} Validated configuration payload.
|
|
293
|
+
@throws {ConfigError} When the file is absent, unreadable, malformed
|
|
294
|
+
JSON, or schema-invalid.
|
|
295
|
+
"""
|
|
296
|
+
payload = _read_payload()
|
|
318
297
|
validate_config(payload)
|
|
319
298
|
return payload
|
|
320
299
|
|
|
321
300
|
|
|
322
|
-
def
|
|
323
|
-
"""@brief Load the
|
|
324
|
-
|
|
325
|
-
@details
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
301
|
+
def load_display() -> dict[str, dict[str, str]]:
|
|
302
|
+
"""@brief Load the schema-shaped display view of the configuration.
|
|
303
|
+
|
|
304
|
+
@details Read-only loader of the schema-driven `--print` and `--info`
|
|
305
|
+
renderers (DES-010, DES-012): requires a JSON-object root,
|
|
306
|
+
then projects the payload onto the schema. Content persisted
|
|
307
|
+
by an older schema version never blocks rendering (TST-008):
|
|
308
|
+
unknown sections and parameters are dropped, and schema
|
|
309
|
+
branches or parameters missing from the file fall back to
|
|
310
|
+
their schema defaults, so the result is always safe for the
|
|
311
|
+
renderers' direct payload indexing. Unreadable, malformed,
|
|
312
|
+
and non-object files remain hard failures (REQ-023).
|
|
313
|
+
@return {dict[str, dict[str, str]]} Schema-shaped payload: section
|
|
314
|
+
token to parameter token to current value (schema default
|
|
315
|
+
when absent from the file).
|
|
316
|
+
@throws {ConfigError} When the file is absent, unreadable, malformed
|
|
317
|
+
JSON, or its root is not a JSON object.
|
|
318
|
+
@satisfies DES-010 TST-008 REQ-019 REQ-023
|
|
330
319
|
"""
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
320
|
+
payload = _read_payload()
|
|
321
|
+
if not isinstance(payload, dict):
|
|
322
|
+
raise ConfigError(
|
|
323
|
+
"configuration root must be a JSON object; "
|
|
324
|
+
f"got {type(payload).__name__}"
|
|
325
|
+
)
|
|
326
|
+
display: dict[str, dict[str, str]] = {}
|
|
327
|
+
for section in SCHEMA:
|
|
328
|
+
branch = payload.get(section.token)
|
|
329
|
+
if not isinstance(branch, dict):
|
|
330
|
+
branch = {}
|
|
331
|
+
display[section.token] = {
|
|
332
|
+
param.token: branch.get(param.token, param.default)
|
|
333
|
+
for param in section.params
|
|
334
|
+
}
|
|
335
|
+
return display
|
|
335
336
|
|
|
336
337
|
|
|
337
338
|
def resolve_segments(path: str) -> tuple[str, ...]:
|
|
@@ -357,9 +358,12 @@ def resolve_segments(path: str) -> tuple[str, ...]:
|
|
|
357
358
|
)
|
|
358
359
|
section = _SECTIONS_BY_TOKEN.get(segments[0])
|
|
359
360
|
if section is None:
|
|
361
|
+
valid = ", ".join(_SECTIONS_BY_TOKEN) or (
|
|
362
|
+
"none (the schema defines no sections)"
|
|
363
|
+
)
|
|
360
364
|
raise ConfigError(
|
|
361
365
|
f"unknown configuration section {segments[0]!r} in path "
|
|
362
|
-
f"{path!r}; valid sections: {
|
|
366
|
+
f"{path!r}; valid sections: {valid}"
|
|
363
367
|
)
|
|
364
368
|
if len(segments) == 1:
|
|
365
369
|
return segments
|
|
@@ -478,24 +482,6 @@ def unset_value(
|
|
|
478
482
|
return updated
|
|
479
483
|
|
|
480
484
|
|
|
481
|
-
def notification_colors() -> dict[str, str]:
|
|
482
|
-
"""@brief Resolve configured ANSI color prefixes for notifications.
|
|
483
|
-
|
|
484
|
-
@details Tolerant read (REQ-026): any load or validation failure
|
|
485
|
-
selects schema defaults, keeping the version check non-fatal
|
|
486
|
-
and silent about configuration problems.
|
|
487
|
-
@return {dict[str, str]} Mapping with `new_version_color` and
|
|
488
|
-
`error_color` ANSI SGR prefix strings.
|
|
489
|
-
"""
|
|
490
|
-
payload = load_tolerant()
|
|
491
|
-
return {
|
|
492
|
-
"new_version_color": COLOR_ANSI[
|
|
493
|
-
payload["Notifications"]["new_version_color"]
|
|
494
|
-
],
|
|
495
|
-
"error_color": COLOR_ANSI[payload["Notifications"]["error_color"]],
|
|
496
|
-
}
|
|
497
|
-
|
|
498
|
-
|
|
499
485
|
def operand_values(
|
|
500
486
|
args: list[str],
|
|
501
487
|
flag: str,
|
|
@@ -534,37 +520,36 @@ def operand_values(
|
|
|
534
520
|
def _usage_examples(flag: str) -> str:
|
|
535
521
|
"""@brief Build schema-valid usage examples for one config flag.
|
|
536
522
|
|
|
537
|
-
@details Examples
|
|
538
|
-
real schema-valid values
|
|
523
|
+
@details Examples derive from the first schema section so they always
|
|
524
|
+
carry complete canonical paths and real schema-valid values
|
|
525
|
+
(REQ-022); with an empty schema the generic `<Path>`
|
|
526
|
+
placeholder documents that every path is rejected.
|
|
539
527
|
@param flag {str} Exact flag token (e.g. `--set`).
|
|
540
528
|
@return {str} Semicolon-separated example command tails.
|
|
541
529
|
"""
|
|
530
|
+
section = SCHEMA[0] if SCHEMA else None
|
|
531
|
+
if section is None:
|
|
532
|
+
if flag in ("--print", "--info", "--print-raw"):
|
|
533
|
+
return f"'{flag}'"
|
|
534
|
+
return f"'{flag} <Path>'; the schema defines no sections"
|
|
535
|
+
if not section.params:
|
|
536
|
+
if flag in ("--print", "--info"):
|
|
537
|
+
return f"'{flag}' or '{flag} {section.token}'"
|
|
538
|
+
return f"'{flag} {section.token}'"
|
|
539
|
+
parameter_path = f"{section.token}:{section.params[0].token}"
|
|
542
540
|
if flag == "--get":
|
|
543
|
-
return
|
|
544
|
-
"'--get Notifications' or "
|
|
545
|
-
"'--get Notifications:new_version_color'"
|
|
546
|
-
)
|
|
541
|
+
return f"'--get {section.token}' or '--get {parameter_path}'"
|
|
547
542
|
if flag == "--set":
|
|
548
|
-
|
|
549
|
-
"
|
|
550
|
-
'{"new_version_color":"bright_green",'
|
|
551
|
-
'"error_color":"bright_red"}'
|
|
543
|
+
sample = json.dumps(
|
|
544
|
+
default_config()[section.token], separators=(",", ":")
|
|
552
545
|
)
|
|
553
546
|
return (
|
|
554
|
-
"'--set
|
|
555
|
-
f"'{
|
|
547
|
+
f"'--set {parameter_path} {section.params[0].default}' or "
|
|
548
|
+
f"'--set {section.token} {sample}'"
|
|
556
549
|
)
|
|
557
550
|
if flag == "--unset":
|
|
558
|
-
return
|
|
559
|
-
|
|
560
|
-
"'--unset Notifications'"
|
|
561
|
-
)
|
|
562
|
-
if flag in ("--print", "--info"):
|
|
563
|
-
return (
|
|
564
|
-
f"'{flag}' or '{flag} Notifications' or "
|
|
565
|
-
f"'{flag} Notifications:new_version_color'"
|
|
566
|
-
)
|
|
567
|
-
return f"'{flag}'"
|
|
551
|
+
return f"'--unset {parameter_path}' or '--unset {section.token}'"
|
|
552
|
+
return f"'{flag}' or '{flag} {section.token}'"
|
|
568
553
|
|
|
569
554
|
|
|
570
555
|
def _fail(error: ConfigError) -> int:
|
|
@@ -15,7 +15,7 @@ import unicodedata
|
|
|
15
15
|
from dataclasses import dataclass, field
|
|
16
16
|
from typing import Any
|
|
17
17
|
|
|
18
|
-
from githubtemplateastraluv import config
|
|
18
|
+
from githubtemplateastraluv import colors, config
|
|
19
19
|
|
|
20
20
|
## @brief Ancestor continuation segment: vertical bar plus three spaces.
|
|
21
21
|
_PREFIX_CONTINUE = "│ "
|
|
@@ -216,10 +216,10 @@ def _selection_rows(param: config.ParamSpec, current: str) -> list[list[str]]:
|
|
|
216
216
|
def _color_meaning(token: str) -> str:
|
|
217
217
|
"""@brief Build the Meaning cell text for one enum color token.
|
|
218
218
|
|
|
219
|
-
@param token {str} Selection enum token present in `
|
|
219
|
+
@param token {str} Selection enum token present in `colors.PALETTE`.
|
|
220
220
|
@return {str} Text naming the ANSI SGR code and human-readable color.
|
|
221
221
|
"""
|
|
222
|
-
sgr =
|
|
222
|
+
sgr = colors.PALETTE[token][2:-1]
|
|
223
223
|
return f"ANSI SGR {sgr} ({token.replace('_', ' ')})"
|
|
224
224
|
|
|
225
225
|
|
|
@@ -438,16 +438,21 @@ def _fail(error: config.ConfigError) -> int:
|
|
|
438
438
|
def handle_print(args: list[str]) -> int:
|
|
439
439
|
"""@brief Execute `--print [Path]` (REQ-019).
|
|
440
440
|
|
|
441
|
-
@details Bootstraps storage, loads
|
|
442
|
-
|
|
443
|
-
|
|
441
|
+
@details Bootstraps storage, loads the schema-shaped display view via
|
|
442
|
+
`config.load_display` so content persisted by an older
|
|
443
|
+
schema version never blocks rendering (DES-010, TST-008),
|
|
444
|
+
builds the display tree, and prints the rendering on stdout;
|
|
445
|
+
genuine failures (absent, unreadable, malformed JSON, or
|
|
446
|
+
non-object file; invalid operands or paths) print nothing
|
|
447
|
+
on stdout and report one stderr diagnostic with exit 1
|
|
448
|
+
(REQ-023).
|
|
444
449
|
@param args {list[str]} CLI argument tokens excluding program name.
|
|
445
450
|
@return {int} 0 on success; 1 on failure.
|
|
446
451
|
"""
|
|
447
452
|
try:
|
|
448
453
|
operands = config.operand_values(args, "--print", 0, 1)
|
|
449
454
|
config.ensure_bootstrapped()
|
|
450
|
-
payload = config.
|
|
455
|
+
payload = config.load_display()
|
|
451
456
|
root = build_print_root(payload, operands[0] if operands else None)
|
|
452
457
|
except config.ConfigError as error:
|
|
453
458
|
return _fail(error)
|
|
@@ -458,15 +463,20 @@ def handle_print(args: list[str]) -> int:
|
|
|
458
463
|
def handle_info(args: list[str]) -> int:
|
|
459
464
|
"""@brief Execute `--info [Path]` (REQ-020).
|
|
460
465
|
|
|
461
|
-
@details Shares the renderer with `--print
|
|
462
|
-
|
|
466
|
+
@details Shares the renderer with `--print` and loads the same
|
|
467
|
+
schema-shaped display view via `config.load_display` so
|
|
468
|
+
content persisted by an older schema version never blocks
|
|
469
|
+
rendering (DES-010, TST-008); renders schema documentation
|
|
470
|
+
with defaults and complete command examples; genuine
|
|
471
|
+
failures print nothing on stdout and report one stderr
|
|
472
|
+
diagnostic with exit 1 (REQ-023).
|
|
463
473
|
@param args {list[str]} CLI argument tokens excluding program name.
|
|
464
474
|
@return {int} 0 on success; 1 on failure.
|
|
465
475
|
"""
|
|
466
476
|
try:
|
|
467
477
|
operands = config.operand_values(args, "--info", 0, 1)
|
|
468
478
|
config.ensure_bootstrapped()
|
|
469
|
-
payload = config.
|
|
479
|
+
payload = config.load_display()
|
|
470
480
|
root = build_info_root(payload, operands[0] if operands else None)
|
|
471
481
|
except config.ConfigError as error:
|
|
472
482
|
return _fail(error)
|
|
@@ -99,12 +99,12 @@ def is_linux() -> bool:
|
|
|
99
99
|
|
|
100
100
|
|
|
101
101
|
def _management_entry(flag: str, description: str) -> str:
|
|
102
|
-
"""@brief Render one aligned
|
|
102
|
+
"""@brief Render one aligned help-screen entry line.
|
|
103
103
|
|
|
104
|
-
@param flag {str} Command flag (e.g. `--upgrade`).
|
|
104
|
+
@param flag {str} Command or option flag (e.g. `--upgrade`).
|
|
105
105
|
@param description {str} Description text placed after the dash.
|
|
106
106
|
@return {str} Line matching the REQ-001 template alignment.
|
|
107
|
-
@satisfies REQ-001
|
|
107
|
+
@satisfies REQ-001 REQ-039
|
|
108
108
|
"""
|
|
109
109
|
return f" {flag:<{_FLAG_COLUMN_WIDTH}} - {description}"
|
|
110
110
|
|
|
@@ -135,12 +135,14 @@ def build_help_text(version: str) -> str:
|
|
|
135
135
|
"""@brief Render the full help screen text (REQ-001 template).
|
|
136
136
|
|
|
137
137
|
@details The literal `(x.y.z)` slot of the template receives the
|
|
138
|
-
installed version (A-01); the `
|
|
139
|
-
|
|
140
|
-
|
|
138
|
+
installed version (A-01); the `Management Commands:` section
|
|
139
|
+
lists every management command, the `Configuration Commands:`
|
|
140
|
+
section lists every configuration command (REQ-039), and the
|
|
141
|
+
`Options:` section documents the `--develop` and `--force`
|
|
142
|
+
modifiers of `--upgrade`.
|
|
141
143
|
@param version {str} Installed version in `x.y.z` format.
|
|
142
144
|
@return {str} Help text without trailing newline; the caller prints it.
|
|
143
|
-
@satisfies REQ-001 A-01 A-02
|
|
145
|
+
@satisfies REQ-001 REQ-039 A-01 A-02
|
|
144
146
|
"""
|
|
145
147
|
entries = [
|
|
146
148
|
_management_entry(
|
|
@@ -155,10 +157,34 @@ def build_help_text(version: str) -> str:
|
|
|
155
157
|
),
|
|
156
158
|
_management_entry("--ver", f"Print the {PROGRAM_NAME} version."),
|
|
157
159
|
_management_entry("--version", f"Print the {PROGRAM_NAME} version."),
|
|
160
|
+
_management_entry("--help", "Print the full help screen."),
|
|
161
|
+
]
|
|
162
|
+
configuration_entries = [
|
|
163
|
+
_management_entry(
|
|
164
|
+
"--get",
|
|
165
|
+
"Print the value at Path as one JSON document.",
|
|
166
|
+
),
|
|
167
|
+
_management_entry(
|
|
168
|
+
"--set",
|
|
169
|
+
"Parse Value into the schema type and persist it at Path.",
|
|
170
|
+
),
|
|
171
|
+
_management_entry(
|
|
172
|
+
"--unset",
|
|
173
|
+
"Restore Path to its schema default and persist atomically.",
|
|
174
|
+
),
|
|
175
|
+
_management_entry(
|
|
176
|
+
"--print",
|
|
177
|
+
"Print current values as a box-drawing tree, "
|
|
178
|
+
"whole schema or at Path.",
|
|
179
|
+
),
|
|
180
|
+
_management_entry(
|
|
181
|
+
"--info",
|
|
182
|
+
"Print parameter documentation with defaults, "
|
|
183
|
+
"constraints, and examples.",
|
|
184
|
+
),
|
|
158
185
|
_management_entry(
|
|
159
|
-
"--
|
|
160
|
-
"Print the
|
|
161
|
-
"command.",
|
|
186
|
+
"--print-raw",
|
|
187
|
+
"Print the exact bytes of the configuration JSON file.",
|
|
162
188
|
),
|
|
163
189
|
]
|
|
164
190
|
option_entries = [
|
|
@@ -175,9 +201,10 @@ def build_help_text(version: str) -> str:
|
|
|
175
201
|
lines = (
|
|
176
202
|
[header, "", "Management Commands:"]
|
|
177
203
|
+ entries
|
|
204
|
+
+ ["", "Configuration Commands:"]
|
|
205
|
+
+ configuration_entries
|
|
178
206
|
+ ["", "Options:"]
|
|
179
207
|
+ option_entries
|
|
180
|
-
+ ["", "Commands:", " ..."]
|
|
181
208
|
)
|
|
182
209
|
return "\n".join(lines)
|
|
183
210
|
|
|
@@ -6,11 +6,10 @@
|
|
|
6
6
|
# gated availability check, throttled through an idle-time JSON
|
|
7
7
|
# cache under `$HOME`, and renders the aligned three-row report
|
|
8
8
|
# (`--ver`) fetching both PyPI and the GitHub releases API.
|
|
9
|
-
# Notifications use the colors
|
|
10
|
-
#
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
# off 86400 s.
|
|
9
|
+
# Notifications use the hardcoded ANSI colors of the embedded
|
|
10
|
+
# internal color JSON (`colors.notification_colors`, REQ-026,
|
|
11
|
+
# REQ-040). Success refreshes the cache with a 3600 s
|
|
12
|
+
# idle-delay; any failure backs off 86400 s.
|
|
14
13
|
import json
|
|
15
14
|
import os
|
|
16
15
|
import time
|
|
@@ -19,7 +18,7 @@ import urllib.request
|
|
|
19
18
|
from pathlib import Path
|
|
20
19
|
from typing import Any
|
|
21
20
|
|
|
22
|
-
from githubtemplateastraluv import
|
|
21
|
+
from githubtemplateastraluv import colors
|
|
23
22
|
|
|
24
23
|
## @brief PyPI JSON API endpoint returning latest published version
|
|
25
24
|
# metadata (REQ-009, REQ-028).
|
|
@@ -44,9 +43,9 @@ _CACHE_RELATIVE_PATH = (
|
|
|
44
43
|
"check_version_idle-time.json",
|
|
45
44
|
)
|
|
46
45
|
## @brief ANSI SGR reset suffix closing colored notifications.
|
|
47
|
-
# @details Notification prefix colors
|
|
48
|
-
#
|
|
49
|
-
#
|
|
46
|
+
# @details Notification prefix colors come from the hardcoded embedded
|
|
47
|
+
# color JSON (`colors.notification_colors`, REQ-026); only the
|
|
48
|
+
# reset suffix stays local.
|
|
50
49
|
_ANSI_RESET = "\033[0m"
|
|
51
50
|
## @brief Report row label for the installed version (REQ-027).
|
|
52
51
|
_REPORT_LABEL_INSTALLED = "Current Installed"
|
|
@@ -261,7 +260,7 @@ def _report_failure(
|
|
|
261
260
|
) -> None:
|
|
262
261
|
"""@brief Emit the failure note and write the 86400 s cache.
|
|
263
262
|
|
|
264
|
-
@details The note renders with the
|
|
263
|
+
@details The note renders with the hardcoded error color (REQ-026).
|
|
265
264
|
@param check_epoch {float} Epoch seconds of the failed attempt.
|
|
266
265
|
@param error {BaseException} Encountered error rendered in the note.
|
|
267
266
|
@param color {str} ANSI SGR prefix for the failure note.
|
|
@@ -277,21 +276,21 @@ def run_version_check(installed_version: str, force: bool = False) -> None:
|
|
|
277
276
|
|
|
278
277
|
@details Flow: cache read -> gate evaluation (skipped when `force`) ->
|
|
279
278
|
PyPI JSON fetch -> version compare -> notify -> cache write.
|
|
280
|
-
Notification colors come from the
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
279
|
+
Notification colors come from the hardcoded embedded color
|
|
280
|
+
JSON (REQ-026, REQ-040). Success always refreshes the cache
|
|
281
|
+
with the 3600 s idle-delay (REQ-013, A-04); fetch or parse
|
|
282
|
+
failures print the hardcoded error note and back off 86400 s
|
|
283
|
+
(REQ-014, REQ-015, A-05). The call always returns normally;
|
|
284
|
+
callers continue parsing (A-06).
|
|
286
285
|
@param installed_version {str} Installed version in `x.y.z` format.
|
|
287
286
|
@param force {bool} True bypasses the idle-time gate (REQ-002,
|
|
288
287
|
REQ-007).
|
|
289
288
|
@return {None}
|
|
290
289
|
@satisfies REQ-007 REQ-008 REQ-009 REQ-010 REQ-011 REQ-012 REQ-013
|
|
291
|
-
REQ-014 REQ-015 REQ-
|
|
290
|
+
REQ-014 REQ-015 REQ-026
|
|
292
291
|
"""
|
|
293
292
|
check_epoch = time.time()
|
|
294
|
-
|
|
293
|
+
palette = colors.notification_colors()
|
|
295
294
|
cache = _read_cache(_cache_path())
|
|
296
295
|
if not force and not _gate_allows_request(cache, check_epoch):
|
|
297
296
|
return
|
|
@@ -305,11 +304,11 @@ def run_version_check(installed_version: str, force: bool = False) -> None:
|
|
|
305
304
|
OSError,
|
|
306
305
|
ValueError,
|
|
307
306
|
) as error:
|
|
308
|
-
_report_failure(check_epoch, error,
|
|
307
|
+
_report_failure(check_epoch, error, palette["error_color"])
|
|
309
308
|
return
|
|
310
309
|
if available > installed:
|
|
311
310
|
_print_colored(
|
|
312
|
-
|
|
311
|
+
palette["new_version_color"],
|
|
313
312
|
f"New version available: {latest_version} "
|
|
314
313
|
f"(installed version: {installed_version})",
|
|
315
314
|
)
|
|
@@ -321,7 +320,7 @@ def run_version_report(installed_version: str) -> None:
|
|
|
321
320
|
|
|
322
321
|
@details Flow: fetch PyPI -> fetch GitHub -> emit the three aligned
|
|
323
322
|
rows. Each failed fetch emits one bright red note naming the
|
|
324
|
-
failed source with the
|
|
323
|
+
failed source with the hardcoded error color (REQ-030) and
|
|
325
324
|
its row prints `unknown (<reason>)`, carrying the actually
|
|
326
325
|
encountered error, in place of the version (REQ-030). Rows
|
|
327
326
|
print in order: installed, PyPI, GitHub; version columns
|
|
@@ -336,7 +335,7 @@ def run_version_report(installed_version: str) -> None:
|
|
|
336
335
|
@return {None}
|
|
337
336
|
@satisfies REQ-002 REQ-027 REQ-028 REQ-029 REQ-030 REQ-031 REQ-026
|
|
338
337
|
"""
|
|
339
|
-
|
|
338
|
+
palette = colors.notification_colors()
|
|
340
339
|
check_epoch = time.time()
|
|
341
340
|
pypi_version: str | None = None
|
|
342
341
|
github_version: str | None = None
|
|
@@ -352,7 +351,7 @@ def run_version_report(installed_version: str) -> None:
|
|
|
352
351
|
) as error:
|
|
353
352
|
pypi_reason = str(error)
|
|
354
353
|
_print_colored(
|
|
355
|
-
|
|
354
|
+
palette["error_color"], f"Version check failed @ PyPI: {error}"
|
|
356
355
|
)
|
|
357
356
|
try:
|
|
358
357
|
github_version = _fetch_latest_github_version()
|
|
@@ -364,7 +363,7 @@ def run_version_report(installed_version: str) -> None:
|
|
|
364
363
|
) as error:
|
|
365
364
|
github_reason = str(error)
|
|
366
365
|
_print_colored(
|
|
367
|
-
|
|
366
|
+
palette["error_color"], f"Version check failed @ GitHub: {error}"
|
|
368
367
|
)
|
|
369
368
|
print(_format_report_row(_REPORT_LABEL_INSTALLED, installed_version))
|
|
370
369
|
print(
|
|
@@ -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.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
githubtemplateastraluv/__init__.py,sha256=lAw4lfMSVPfq0POTuafu4dSDVTeol4kA4b_4WFirEwo,850
|
|
2
|
+
githubtemplateastraluv/__main__.py,sha256=I0zvcbC04AWVVNmpzMbI07EjM2uHAsEpKP_tbmIp8TA,497
|
|
3
|
+
githubtemplateastraluv/colors.py,sha256=XCAcBGjpXeLe7TMKIhSi--zQQo_ntHJR-0aNhFhUkZw,2858
|
|
4
|
+
githubtemplateastraluv/config.py,sha256=anecxGQdthYznVZEgk2Am5TgZw7TH2bxddJ_amvYmg4,25428
|
|
5
|
+
githubtemplateastraluv/config_render.py,sha256=EyOkx-ROaTy9Bdw9Mh4we87mEE-tc_eOJ0YPgxmYe-A,18828
|
|
6
|
+
githubtemplateastraluv/core.py,sha256=5S64FY60FuipgyYfvg2cbXBvIsmCyLrescWj-v-niXA,3451
|
|
7
|
+
githubtemplateastraluv/management.py,sha256=0KaHY1MMCGQI_70PeGCF5xFZJLcga5dHj-eNZyNG4Ck,10716
|
|
8
|
+
githubtemplateastraluv/version_check.py,sha256=dHruE_8lU4UARpoSbDgvD_H5hPniSH1QLcCeh8GyMx8,15505
|
|
9
|
+
githubtemplateastraluv-0.0.4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
|
|
10
|
+
githubtemplateastraluv-0.0.4.dist-info/METADATA,sha256=GszHliOsbWVLd8oIKtryp-Sqgl6fLJ3voNdRJvQ4zvc,15570
|
|
11
|
+
githubtemplateastraluv-0.0.4.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
12
|
+
githubtemplateastraluv-0.0.4.dist-info/entry_points.txt,sha256=XH-1vjNI8srhhc8lbZSokz38NevfJvmhGA7yBwlD2sk,136
|
|
13
|
+
githubtemplateastraluv-0.0.4.dist-info/top_level.txt,sha256=NqyMg91W-TpzrQONNj83-3I1K46fe5MsYnan2RUY7mg,23
|
|
14
|
+
githubtemplateastraluv-0.0.4.dist-info/RECORD,,
|
|
@@ -1,196 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: githubtemplateastraluv
|
|
3
|
-
Version: 0.0.2
|
|
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
|
-
# githubtemplateastraluv/templateastraluv (0.0.2)
|
|
22
|
-
|
|
23
|
-
<p align="center">
|
|
24
|
-
<img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
|
|
25
|
-
<img src="https://img.shields.io/badge/license-GPL--3.0-491?style=flat-square" alt="License: GPL-3.0">
|
|
26
|
-
<img src="https://img.shields.io/badge/platform-Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
|
|
27
|
-
<img src="https://img.shields.io/badge/docs-live-b31b1b" alt="Docs">
|
|
28
|
-
<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
|
|
29
|
-
</p>
|
|
30
|
-
<p align="center">
|
|
31
|
-
<strong>GitHub template for Astral-UV apps published on PyPI.</strong><br>
|
|
32
|
-
Python CLI template with Astral uv/uvx packaging, PyPI OIDC Trusted
|
|
33
|
-
Publishing release automation, self-upgrade from PyPI (or the latest
|
|
34
|
-
GitHub tag via <code>--develop</code>), and a dual-source version report.
|
|
35
|
-
</p>
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
<p align="center">
|
|
39
|
-
<a href="#quick-start">Quick Start</a> |
|
|
40
|
-
<a href="#feature-highlights">Feature Highlights</a> |
|
|
41
|
-
<a href="#acknowledgments">Acknowledgments</a>
|
|
42
|
-
</p>
|
|
43
|
-
|
|
44
|
-
<p align="center">
|
|
45
|
-
<br>
|
|
46
|
-
🚧 <strong>DRAFT</strong>: 👾 Alpha Development 👾 - Work in Progress 🏗️ 🚧<br>
|
|
47
|
-
⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://github.com/ogekuri/useReq"><strong>useReq/req</strong></a> 🤖✨ ⚠️<br>
|
|
48
|
-
<br>
|
|
49
|
-
<p>
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
## Feature Highlights
|
|
53
|
-
- Published on PyPI: install with `uv tool install githubtemplateastraluv`.
|
|
54
|
-
- Automatic online new-version check (PyPI) throttled by an idle-time cache.
|
|
55
|
-
- `--ver` dual-source report: installed, latest PyPI, and latest GitHub versions, with aligned columns.
|
|
56
|
-
- Self-upgrade from PyPI; `--upgrade --develop` pulls the latest GitHub tagged release; `--upgrade --force` forces full re-download and reinstallation.
|
|
57
|
-
- Colored console notifications with user-configurable colors.
|
|
58
|
-
- Release automation: GitHub release for every version tag; OIDC Trusted Publishing to PyPI for `master` tags only.
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
## Quick Start
|
|
62
|
-
|
|
63
|
-
1. Install the tool from PyPI:
|
|
64
|
-
```bash
|
|
65
|
-
uv tool install githubtemplateastraluv
|
|
66
|
-
```
|
|
67
|
-
2. Run it:
|
|
68
|
-
```bash
|
|
69
|
-
githubtemplateastraluv --help
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## Usage
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
# Print the version report (aligned columns)
|
|
76
|
-
githubtemplateastraluv --ver
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
Output format:
|
|
80
|
-
```
|
|
81
|
-
Current Installed : X1.Y1.Z1
|
|
82
|
-
Latest @ PyPI : X2.Y2.Z2
|
|
83
|
-
Latest @ GitHub : X3.Y3.Z3
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
# Upgrade from PyPI (Linux; prints the manual command elsewhere)
|
|
88
|
-
githubtemplateastraluv --upgrade
|
|
89
|
-
|
|
90
|
-
# Force full re-download and reinstallation from PyPI
|
|
91
|
-
githubtemplateastraluv --upgrade --force
|
|
92
|
-
|
|
93
|
-
# Upgrade to the latest GitHub tagged release (any branch)
|
|
94
|
-
githubtemplateastraluv --upgrade --develop
|
|
95
|
-
|
|
96
|
-
# Force full re-download and reinstallation from GitHub
|
|
97
|
-
githubtemplateastraluv --upgrade --develop --force
|
|
98
|
-
|
|
99
|
-
# Uninstall (Linux; prints the manual command elsewhere)
|
|
100
|
-
githubtemplateastraluv --uninstall
|
|
101
|
-
|
|
102
|
-
# Full help screen
|
|
103
|
-
githubtemplateastraluv --help
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
## Install with Astral uv (PyPI — primary method)
|
|
108
|
-
|
|
109
|
-
#### Install
|
|
110
|
-
```bash
|
|
111
|
-
uv tool install githubtemplateastraluv
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
#### Upgrade
|
|
115
|
-
```bash
|
|
116
|
-
githubtemplateastraluv --upgrade
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
#### Uninstall
|
|
120
|
-
```bash
|
|
121
|
-
uv tool uninstall githubtemplateastraluv
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
## Live execution with uvx (alternative method)
|
|
125
|
-
|
|
126
|
-
Run githubtemplateastraluv directly from PyPI without prior installation:
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
uvx githubtemplateastraluv
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
You can pass options as usual, for example:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
uvx githubtemplateastraluv <args>
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
## Install and upgrade from GitHub (development releases)
|
|
139
|
-
|
|
140
|
-
A dedicated, non-primary distribution channel hosts intermediate and test
|
|
141
|
-
releases on GitHub: `https://github.com/Ogekuri/GitHub-Template-AstralUV`.
|
|
142
|
-
|
|
143
|
-
#### Install
|
|
144
|
-
```bash
|
|
145
|
-
uv tool install githubtemplateastraluv --force --from git+https://github.com/Ogekuri/GitHub-Template-AstralUV.git
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
#### Upgrade to the latest GitHub tagged release (any branch)
|
|
149
|
-
```bash
|
|
150
|
-
githubtemplateastraluv --upgrade --develop
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
#### Force full re-download and reinstallation
|
|
154
|
-
```bash
|
|
155
|
-
githubtemplateastraluv --upgrade --force
|
|
156
|
-
githubtemplateastraluv --upgrade --develop --force
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
`--upgrade --develop` always downloads the most recent tagged build
|
|
160
|
-
from GitHub, regardless of the branch it was tagged on
|
|
161
|
-
(`master`, `develop`, or any other branch). The `--ver` report shows the
|
|
162
|
-
GitHub latest release in the `Latest @ GitHub` row.
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
## Repository Tooling Scripts
|
|
167
|
-
|
|
168
|
-
| Script | Purpose |
|
|
169
|
-
| --- | --- |
|
|
170
|
-
| `scripts/templateastraluv.sh` | Local-run launcher delegating to `uv run --project <root> python -m githubtemplateastraluv`. |
|
|
171
|
-
| `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. |
|
|
172
|
-
| `scripts/clean.sh` | Removes every repository-internal execution-generated artifact and restores the canonical startup state. |
|
|
173
|
-
| `scripts/pre-release-check.sh` | Fail-fast release verification (syntax, compileall, pytest, out-of-tree build, artifact validation) with baseline-guarded cleanup. |
|
|
174
|
-
|
|
175
|
-
`scripts/clean.sh` removes `__pycache__/` and `*.egg-info/` at any depth,
|
|
176
|
-
the `.pytest_cache/`, `.ruff_cache/`, `.mypy_cache/`, `build/`, and
|
|
177
|
-
`.venv/` directories, and the `.coverage`/`.coverage.*` data files. It is
|
|
178
|
-
idempotent (absent targets are a successful no-op), never touches tracked
|
|
179
|
-
files, untracked user files, `$HOME` application data, or the versioned
|
|
180
|
-
release artifacts in `dist/`, and never runs destructive git commands.
|
|
181
|
-
`scripts/build.sh` delegates its pre-build cleanup to `scripts/clean.sh`,
|
|
182
|
-
so two consecutive builds always start from the identical state:
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
# Remove all execution-generated temporary artifacts
|
|
186
|
-
./scripts/clean.sh
|
|
187
|
-
|
|
188
|
-
# Build from the canonical cleaned state (also via clean.sh)
|
|
189
|
-
./scripts/build.sh
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
## Acknowledgments
|
|
194
|
-
|
|
195
|
-
TODO: fill scknowledgments section
|
|
196
|
-
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
githubtemplateastraluv/__init__.py,sha256=rRLix5adqRZzM0LOpsElZFBnTBZGtjts9MQVVAwBTK8,850
|
|
2
|
-
githubtemplateastraluv/__main__.py,sha256=I0zvcbC04AWVVNmpzMbI07EjM2uHAsEpKP_tbmIp8TA,497
|
|
3
|
-
githubtemplateastraluv/config.py,sha256=9YqNgNRTBGb3K8MKni-sLwm-Duijfgp7Fji-_sblEe0,25140
|
|
4
|
-
githubtemplateastraluv/config_render.py,sha256=_D9mPQJLfe7qH39KVXb0JNvSnox60BHCd1QDxIfPIew,18188
|
|
5
|
-
githubtemplateastraluv/core.py,sha256=5S64FY60FuipgyYfvg2cbXBvIsmCyLrescWj-v-niXA,3451
|
|
6
|
-
githubtemplateastraluv/management.py,sha256=CTBh0wuzoBkkNzHAZkfsHdhW-c0d5K5KzRFoGIAjE8U,9755
|
|
7
|
-
githubtemplateastraluv/version_check.py,sha256=ZMMNA2sbrC8U_JBBE8WkWPqKmbuMbGM7SQh2WTU33s4,15595
|
|
8
|
-
githubtemplateastraluv-0.0.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
|
|
9
|
-
githubtemplateastraluv-0.0.2.dist-info/METADATA,sha256=pXc8SyKAGjx60wTE00AMQ4fmS5Rr-NuhC584lFX5ySo,6543
|
|
10
|
-
githubtemplateastraluv-0.0.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
11
|
-
githubtemplateastraluv-0.0.2.dist-info/entry_points.txt,sha256=XH-1vjNI8srhhc8lbZSokz38NevfJvmhGA7yBwlD2sk,136
|
|
12
|
-
githubtemplateastraluv-0.0.2.dist-info/top_level.txt,sha256=NqyMg91W-TpzrQONNj83-3I1K46fe5MsYnan2RUY7mg,23
|
|
13
|
-
githubtemplateastraluv-0.0.2.dist-info/RECORD,,
|
|
File without changes
|
{githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/entry_points.txt
RENAMED
|
File without changes
|
{githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/licenses/LICENSE
RENAMED
|
File without changes
|
{githubtemplateastraluv-0.0.2.dist-info → githubtemplateastraluv-0.0.4.dist-info}/top_level.txt
RENAMED
|
File without changes
|