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.
@@ -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.2"
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
+ }
@@ -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 (REQ-025).
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, REQ-024).
102
- # @details Insertion order defines canonical display order.
103
- SCHEMA: tuple[SectionSpec, ...] = (
104
- SectionSpec(
105
- token="Notifications",
106
- description="Version-check notification appearance.",
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 schema enum (REQ-025). Raises without
174
- mutation; callers reject the operation on error.
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 executing
279
- (REQ-024 storage lifecycle). Never overwrites an existing
280
- file, valid or not; strict loaders surface invalid files as
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 load_strict() -> dict[str, dict[str, str]]:
298
- """@brief Load and strictly validate the global configuration.
263
+ def _read_payload() -> Any:
264
+ """@brief Read and parse the persisted configuration JSON document.
299
265
 
300
- @details Reads the file selected by `config_path`, parses JSON, and
301
- applies `validate_config`; every failure raises instead of
302
- partially succeeding (REQ-022, REQ-023).
303
- @return {dict[str, dict[str, str]]} Validated configuration payload.
304
- @throws {ConfigError} When the file is absent, unreadable, malformed
305
- JSON, or schema-invalid.
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
- payload = json.loads(text)
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 load_tolerant() -> dict[str, dict[str, str]]:
323
- """@brief Load the configuration, falling back to schema defaults.
324
-
325
- @details Used by the version-check notification path (REQ-026): any
326
- load or validation failure silently selects schema defaults
327
- so existing non-configuration behavior never breaks and no
328
- extra output is produced.
329
- @return {dict[str, dict[str, str]]} Validated payload or defaults.
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
- try:
332
- return load_strict()
333
- except ConfigError:
334
- return default_config()
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: {', '.join(_SECTIONS_BY_TOKEN)}"
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 always carry complete canonical paths (REQ-022) and
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
- section_example = (
549
- "--set Notifications "
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 Notifications:new_version_color bright_green' or "
555
- f"'{section_example}'"
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
- "'--unset Notifications:new_version_color' or "
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 `COLOR_ANSI`.
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 = config.COLOR_ANSI[token][2:-1]
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 strictly, builds the display tree,
442
- and prints the rendering on stdout; failures print nothing
443
- on stdout and report one stderr diagnostic with exit 1.
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.load_strict()
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`; renders schema
462
- documentation with defaults and complete command examples.
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.load_strict()
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 management-command help line.
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 `Options:` section documents
139
- the `--develop` and `--force` modifiers of `--upgrade`; the
140
- `Commands:` section ends with the literal `...` line (A-02).
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
- "--help",
160
- "Print the full help screen or the help text of a specific "
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 configured in the configuration
10
- # subsystem (REQ-026), falling back to bright green / bright red
11
- # schema defaults when configuration cannot be loaded. Success
12
- # refreshes the cache with a 3600 s idle-delay; any failure backs
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 config
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 are configured through the
48
- # configuration subsystem (config.notification_colors, REQ-026);
49
- # only the reset suffix stays local.
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 configured error color (REQ-026).
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 configuration subsystem
281
- with schema-default fallback (REQ-026). Success always
282
- refreshes the cache with the 3600 s idle-delay (REQ-013,
283
- A-04); fetch or parse failures print the configured error
284
- note and back off 86400 s (REQ-014, REQ-015, A-05). The call
285
- always returns normally; callers continue parsing (A-06).
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-024 REQ-025 REQ-026
290
+ REQ-014 REQ-015 REQ-026
292
291
  """
293
292
  check_epoch = time.time()
294
- colors = config.notification_colors()
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, colors["error_color"])
307
+ _report_failure(check_epoch, error, palette["error_color"])
309
308
  return
310
309
  if available > installed:
311
310
  _print_colored(
312
- colors["new_version_color"],
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 configured error color (REQ-030) and
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
- colors = config.notification_colors()
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
- colors["error_color"], f"Version check failed @ PyPI: {error}"
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
- colors["error_color"], f"Version check failed @ GitHub: {error}"
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,,