simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/cli.py

@@ -0,0 +1,381 @@
+"""The command surface: one subcommand, one positional, five flags, one code path for all.
+
+`init` is the only subcommand, and a bare `simcon-toolkit` prints the help and refuses
+rather than guessing which one was meant. The subcommand is a namespace, not ceremony: it
+leaves room beside `init` without ever making a project name ambiguous with a command.
+
+There is no separate non-interactive mode. Every question has a flag, and only one answer is
+REQUIRED: the template, because nothing else decides what the customer gets. The folder
+name defaults to the template's name and the package manager to uv, both safe because a
+clash stops the run before anything is written. So a command naming a template runs at once
+on the defaults, whoever typed it. A command naming none opens the wizard for a person at a
+terminal, which asks only what the flags left open, and is refused with the flag to pass
+for anyone else. `--force` and `--list` answer no question.
+
+Four conventions here are deliberate and each one looks like an oversight:
+
+* `--package-manager` **carries no short form.** `-p` is `--python` in uv and `--project`
+  in pdm and hatch, and a Python scaffolder wants `--python` far more than it wants six
+  saved keystrokes on a flag typed once.
+* `--yes` **is the documented name, with the Python-native spellings accepted quietly.**
+  cookiecutter teaches `--no-input` and copier teaches `--defaults`; neither should meet a
+  parse error, but the name a mould engineer and an assistant both reach for comes first.
+* **Everything this module prints is ASCII.** (The wizard draws two glyphs, and only on a
+  terminal that can encode them.) A Windows console gets UTF-16, but REDIRECTED output
+  falls back to the machine's codepage, and an em dash is unencodable in cp437, cp850 and
+  cp932 — so one decorative character turns `simcon-toolkit init --list > list.txt` into a
+  traceback on a Japanese or Korean machine. This is the tool that must refuse nobody.
+* **The catalogue is read late and its failure is caught.** `--help` and `--version` are
+  what someone reaches for when a command misbehaves, so they must survive a broken
+  installation rather than being the next thing that tracebacks.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from simcon_toolkit.manifest import TemplateSpec
+
+#: Handed to a caller who asked nothing. It is the simplest of the four — one script at its
+#: root — which is the least surprising thing to give someone who supplied no opinion.
+DEFAULT_TEMPLATE = "run-one-simulation"
+
+# Imports nothing, so it is safe above the interpreter check.
+from simcon_toolkit.choices import DEFAULT_PACKAGE_MANAGER, PACKAGE_MANAGERS  # noqa: E402
+
+#: Copying a template out of the installed package is `importlib.resources.as_file()` on a
+#: directory, which is supported only from here.
+MINIMUM_PYTHON = (3, 12)
+
+#: The flags that live under `init`, so a command using one without it can be pointed there.
+INIT_ONLY_FLAGS = frozenset(
+    {
+        "-t",
+        "--template",
+        "--package-manager",
+        "-y",
+        "--yes",
+        "--no-input",
+        "--defaults",
+        "-f",
+        "--force",
+        "-l",
+        "--list",
+    }
+)
+
+#: What argparse prints for a usage error, so one command never speaks in two voices.
+PREFIX = "simcon-toolkit: error:"
+
+
+class KitUnreadable(Exception):
+    """The installed catalogue is absent, incomplete or corrupt — not the caller's doing."""
+
+
+@dataclass(frozen=True)
+class Choices:
+    """What the run resolved to, once flags and defaults were applied."""
+
+    template: str
+    name: str
+    package_manager: str
+
+
+def check_interpreter(version: tuple[int, int] | None = None) -> str | None:
+    """The refusal to print when this Python is too old, or None when it will do.
+
+    Both installers enforce the *floor* at resolution, so this is a backstop rather than
+    the first line of defence: it covers a run from a source checkout, an install forced
+    past the metadata, and a future release that drops the bound. It earns its lines
+    because what the installers produce instead is a resolver's unsatisfiable-requirements
+    dump, which names this package rather than the thing the reader has to change.
+
+    Nothing above it in this module may import the manifest: `tomllib` does not exist
+    below 3.11, so an import at module scope raises first and this sentence is never
+    reached on the versions that need it most.
+
+    The argument is resolved per call rather than defaulted, for the reason spelled out on
+    `is_interactive` — here it could not actually change, but one module should not teach
+    the rule and break it four functions apart.
+    """
+    if version is None:
+        version = sys.version_info[:2]
+    if version >= MINIMUM_PYTHON:
+        return None
+    running = ".".join(str(part) for part in version)
+    wanted = ".".join(str(part) for part in MINIMUM_PYTHON)
+    return (
+        f"simcon-toolkit needs Python {wanted} or newer; this is Python {running}. "
+        f"Run it as `uvx --python {wanted} simcon-toolkit@latest init`, or install Python {wanted}."
+    )
+
+
+@functools.cache
+def read_templates() -> dict[str, TemplateSpec]:
+    """The catalogue, with every way it can be unreadable turned into one refusal.
+
+    A `_kit/` that EXISTS is not a `_kit/` that works, and only the first is checked when
+    the package resolves its root. `force-include` ships whatever is on disk at build time,
+    so a present-but-incomplete kit is a shape this project already worries about, and the
+    carefully worded message written for a missing kit misses it entirely.
+
+    Cached, because `--help` reads it for the epilog and the run reads it again; a failure
+    raises and is therefore never cached, so a broken kit is reported every time.
+    """
+    where = "its installed location"
+    try:
+        from simcon_toolkit.manifest import MANIFEST, load_manifest
+
+        where = str(MANIFEST)
+        return load_manifest()
+    # Broad on purpose: a missing file, unreadable TOML and a manifest with no `templates`
+    # table are three exceptions with one honest cause and one useful thing to say.
+    except Exception as failure:
+        raise KitUnreadable(
+            f"simcon-toolkit cannot read its own template catalogue at {where} ({failure}). "
+            f"The installation is incomplete; reinstall with `uvx simcon-toolkit@latest init`."
+        ) from failure
+
+
+def _catalogue_epilog() -> str:
+    """The template names for `--help`, or nothing. Never a reason for `--help` to fail."""
+    try:
+        return f"Templates: {', '.join(sorted(read_templates()))}."
+    except KitUnreadable:
+        return ""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Every command and flag the installer accepts, and nothing that was designed away."""
+    from simcon_toolkit import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="simcon-toolkit",
+        description="Put a working SIMCON example project on your machine.",
+    )
+    parser.add_argument("--version", action="version", version=f"simcon-toolkit {__version__}")
+    commands = parser.add_subparsers(dest="command", metavar="<command>")
+    init = commands.add_parser(
+        "init",
+        help="create a project from a template",
+        description="Create a project from a template, ready to run.",
+        epilog=_catalogue_epilog(),
+    )
+    init.add_argument("name", nargs="?", help="folder to create (default: the template's own name)")
+    init.add_argument(
+        "-t",
+        "--template",
+        help=f"which workflow to start from; the one required answer (--yes picks {DEFAULT_TEMPLATE})",
+    )
+    init.add_argument(
+        "--package-manager",
+        choices=PACKAGE_MANAGERS,
+        help=f"which installer the project's instructions are written for (default: {DEFAULT_PACKAGE_MANAGER})",
+    )
+    # The aliases are real flags rather than hidden ones: someone who types what copier or
+    # cookiecutter taught them should find it in --help too, not discover it by luck.
+    init.add_argument(
+        "-y",
+        "--yes",
+        "--no-input",
+        "--defaults",
+        action="store_true",
+        help="ask nothing and use the documented defaults",
+    )
+    init.add_argument("-f", "--force", action="store_true", help="overwrite files the template would write")
+    init.add_argument("-l", "--list", action="store_true", help="list the templates and exit")
+    return parser
+
+
+def at_a_terminal() -> bool:
+    """Whether a person can both see a question and answer it.
+
+    Both streams, not only stdin: `init > log.txt` at a terminal would otherwise wait on a
+    question written into the file, and prompt_toolkit raises on a redirected Windows stdout.
+    """
+    # A closed descriptor leaves the stream as None rather than raising, so `init <&-` would
+    # otherwise die on an AttributeError before it had done anything.
+    return bool(sys.stdin and sys.stdout and sys.stdin.isatty() and sys.stdout.isatty())
+
+
+def is_interactive(args: argparse.Namespace, tty: bool | None = None) -> bool:
+    """Whether to open the wizard: someone is there, and the one required answer is missing.
+
+    Checked before any prompt library is reached, never left to one: every library measured
+    blocks forever on an open stdin that nobody writes to, which is what an assistant's
+    captured shell usually hands a child process.
+
+    `tty` is resolved on each call, never as a default argument: a default is evaluated
+    once when this module is imported, which for a long-lived import binds whatever stdin
+    looked like then and answers the same way forever after.
+    """
+    if tty is None:
+        tty = at_a_terminal()
+    return tty and not args.yes and args.template is None
+
+
+def resolve(args: argparse.Namespace) -> Choices:
+    """Flags first, then the documented defaults — and nothing read off this machine.
+
+    `create-next-app`'s `--yes` consults a stored preference file, which is why it needs a
+    flag to reset one and why the same command produces different projects on two laptops.
+    Ours resolves to the documented defaults and nothing else.
+    """
+    template = args.template or DEFAULT_TEMPLATE
+    return Choices(
+        template=template,
+        name=args.name or template,
+        package_manager=args.package_manager or DEFAULT_PACKAGE_MANAGER,
+    )
+
+
+def _describe(spec: TemplateSpec) -> str:
+    """One catalogue line, ASCII only — see the note on encodings at the top of this file."""
+    credentials = " | needs " + ", ".join(spec.needs) if spec.needs else ""
+    return f"  {spec.name:<20} {spec.title}: {spec.description}{credentials}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse, validate, and write the project the caller asked for."""
+    refusal = check_interpreter()
+    if refusal is not None:
+        print(refusal, file=sys.stderr)
+        return 2
+
+    # Everything this module writes is ASCII, but a folder name or a kept file is the
+    # customer's, and stdout encodes strictly: a redirected run on a Japanese codepage would
+    # write the whole project and then die printing its name.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(errors="backslashreplace")
+
+    if argv is None:
+        argv = sys.argv[1:]
+    if argv and argv[0] in INIT_ONLY_FLAGS:
+        # The flags moved under `init`; a command copied from an older page should be told
+        # where they went rather than meet argparse's bare "unrecognized arguments".
+        print(f"{PREFIX} {argv[0]} belongs to the init command: simcon-toolkit init {' '.join(argv)}", file=sys.stderr)
+        return 2
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        # A refusal, so the help goes where refusals go; see `test_every_refusal_goes_to_stderr`.
+        parser.print_help(sys.stderr)
+        return 2
+
+    try:
+        templates = read_templates()
+    except KitUnreadable as unreadable:
+        print(f"{PREFIX} {unreadable}", file=sys.stderr)
+        return 2
+
+    if args.list:
+        print("Templates:")
+        for spec in sorted(templates.values(), key=lambda entry: entry.name):
+            print(_describe(spec))
+        return 0
+
+    # An empty name is a mistyped one, not an absent one. Without this, `-y ""` resolves to
+    # the template's own name and hands back a folder nobody asked for, reporting success.
+    if args.name is not None and not args.name.strip():
+        print(f"{PREFIX} the project name is empty. Give a folder name, or leave it out entirely.", file=sys.stderr)
+        return 2
+
+    tty = at_a_terminal()
+    if args.template is not None and args.template not in templates:
+        known = ", ".join(sorted(templates))
+        # Named first, because the one thing the reader knows is what they typed. The full
+        # list follows rather than a suggestion: four names fit on a line, and a guess that
+        # lands on the wrong one costs more than reading them.
+        print(f"{PREFIX} no template named {args.template!r}. Available: {known}", file=sys.stderr)
+        if not tty or args.yes:
+            return 2
+        # Someone is there to choose, so the menu is kinder than a second attempt at typing.
+        args.template = None
+
+    if is_interactive(args, tty):
+        from simcon_toolkit.wizard import Cancelled, ask, name_problem
+
+        if args.name is not None:
+            # Before the questions, not after them, and by the prompt's own rule: a name that
+            # can never work should not cost the reader two answers first.
+            problem = name_problem(args.name, force=args.force)
+            if problem is not None:
+                print(f"{PREFIX} {problem}", file=sys.stderr)
+                return 2
+
+        try:
+            template, name, package_manager = ask(
+                templates,
+                default_template=DEFAULT_TEMPLATE,
+                name=args.name,
+                package_manager=args.package_manager,
+                force=args.force,
+            )
+        except Cancelled:
+            print("Cancelled; nothing was written.", file=sys.stderr)
+            return 130
+        chosen = Choices(template=template, name=name, package_manager=package_manager)
+    elif args.template is None and not args.yes:
+        # The refusal is what an assistant reads to correct itself, so it names every way out.
+        print(f"{PREFIX} no template chosen, and there is no terminal to ask at.", file=sys.stderr)
+        print(
+            f"Pass --template <name> (--list shows them), or --yes for {DEFAULT_TEMPLATE} with every default.",
+            file=sys.stderr,
+        )
+        return 2
+    else:
+        chosen = resolve(args)
+
+    from simcon_toolkit import KIT_ROOT, __version__
+    from simcon_toolkit.generate import GeneratorError, WriteFailed, format_listing, generate_project
+
+    destination = Path(chosen.name)
+    try:
+        result = generate_project(
+            chosen.template,
+            destination,
+            force=args.force,
+            cli_version=__version__,
+            package_manager=chosen.package_manager,
+        )
+    except GeneratorError as refusal:
+        print(f"{PREFIX} {refusal}", file=sys.stderr)
+        # A write that failed part-way is not a mistake in the arguments.
+        return 1 if isinstance(refusal, WriteFailed) else 2
+    except OSError as failure:
+        # A file missing from our own kit is a broken installation, and saying "could not
+        # write" would send the reader to check their own disk for a fault that is ours.
+        if failure.filename and Path(failure.filename).resolve().is_relative_to(KIT_ROOT.resolve()):
+            print(f"{PREFIX} the installation is incomplete: {failure.filename} is missing.", file=sys.stderr)
+            print("Reinstall with `uvx simcon-toolkit@latest init`.", file=sys.stderr)
+            return 2
+        # A disk that is full or a folder we may not write to: not the caller's mistake in
+        # the arguments, so exit 1 rather than the usage error's 2.
+        print(f"{PREFIX} could not write {destination}: {failure.strerror or failure}", file=sys.stderr)
+        return 1
+
+    # Every resolved value, defaulted or not, because the transcript is all an assistant keeps.
+    print(
+        f"Created {chosen.template} in {destination}, package manager: {chosen.package_manager} "
+        f"({len(result.written)} files written)."
+    )
+    if result.overwritten:
+        print(f"Overwrote {len(result.overwritten)} existing file(s): {format_listing(result.overwritten)}")
+    if result.kept:
+        # Never removed, because only the reader knows whether they are their own work or
+        # something left from a different template.
+        print(f"Left {len(result.kept)} file(s) that are not part of this template: {format_listing(result.kept)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())