pyguibud 0.1.0__py3-none-any.whl

pyguibud/__main__.py

@@ -0,0 +1,8 @@
+"""PyGUIbud command-line entry point."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyguibud/_argparse.py

@@ -0,0 +1,205 @@
+"""Translated argparse plumbing shared by ``pyguibud``, ``pyguibud-uic`` and the preview child.
+
+It lives outside :mod:`pyguibud.cli` because the preview child must not import the CLI
+(ADR-007/013 import boundary); like the CLI it loads no GUI toolkit.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import functools
+import re
+import sys
+import threading
+from collections.abc import Callable
+from typing import Any, NoReturn, TypeVar, cast
+
+from .credits import credit
+from .i18n import (
+    LANGUAGE_CODE_RE,
+    N_,
+    NP_,
+    _,
+    detect_language,
+    ngettext,
+    normalise_language,
+    set_language,
+)
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+class _PreParseError(Exception):
+    """Raised by the pre-parser instead of exiting; the real parser reports the problem."""
+
+
+class _QuietParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        raise _PreParseError(message)
+
+
+# Every message of argparse that this parser can emit, marked so that ``pybabel extract`` keeps
+# it in the catalogue (argparse's own catalogue has no pyguibud language). The set is the union of
+# Python 3.10 to 3.13; unreachable texts (sub-commands, FileType, programmer errors) are left out.
+# Translators: these are the texts of Python's argparse module. Keep every placeholder (%s,
+# %(prog)s, %(value)r, ...) and the final newline of the "error" line exactly as in the source.
+_ARGPARSE_MSGIDS = (
+    N_("%(heading)s:"),
+    N_("%(prog)s: error: %(message)s\n"),
+    N_(" (default: %(default)s)"),
+    N_("ambiguous option: %(option)s could match %(matches)s"),
+    N_("argument %(argument_name)s: %(message)s"),
+    N_("expected at least one argument"),
+    N_("expected at most one argument"),
+    N_("expected one argument"),
+    NP_("expected %s argument", "expected %s arguments"),
+    N_("ignored explicit argument %r"),
+    N_("invalid %(type)s value: %(value)r"),
+    N_("invalid choice: %(value)r (choose from %(choices)s)"),
+    N_("not allowed with argument %s"),
+    N_("one of the arguments %s is required"),
+    N_("optional arguments"),  # Python 3.10 and older
+    N_("options"),
+    N_("positional arguments"),
+    N_("show program's version number and exit"),
+    N_("show this help message and exit"),
+    N_("the following arguments are required: %s"),
+    N_("unexpected option string: %s"),
+    N_("unrecognized arguments: %s"),
+    N_("usage: "),
+)
+
+
+class _Swap:
+    """argparse's ``_``/``ngettext`` while any wrapped call runs, in any thread (QA-19e-03).
+
+    The first call to enter saves and replaces them and the last to leave restores them, so
+    concurrent or nested parses never restore each other's state. The lock guards only the
+    swap: holding it during a parse would serialise every parser.
+    """
+
+    lock = threading.Lock()
+    depth = 0
+    saved: tuple[Any, Any] = (None, None)
+
+
+def _bound(method: _F) -> _F:
+    """Run ``method`` with argparse's ``_`` and ``ngettext`` replaced by ours, then restore them."""
+
+    @functools.wraps(method)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+        with _Swap.lock:
+            if _Swap.depth == 0:
+                _Swap.saved = argparse._, argparse.ngettext  # type: ignore[attr-defined]
+                argparse._, argparse.ngettext = _, ngettext  # type: ignore[attr-defined]
+            _Swap.depth += 1
+        try:
+            return method(*args, **kwargs)
+        finally:
+            with _Swap.lock:
+                _Swap.depth -= 1
+                if _Swap.depth == 0:
+                    argparse._, argparse.ngettext = _Swap.saved  # type: ignore[attr-defined]
+
+    return cast(_F, wrapper)
+
+
+class _Formatter(argparse.HelpFormatter):
+    """Help formatter that keeps line breaks in texts and translates hard-coded colons."""
+
+    class _Section(argparse.HelpFormatter._Section):
+        """A help section whose heading colon is translated (``%(heading)s:``; French puts a space).
+
+        argparse translates it itself only from 3.11.9 and 3.12.3 (not 3.12.0), so an untranslated
+        heading line is replaced: a feature test, not a version test (QA-19e-02). Where argparse
+        translated the heading, the untranslated line is absent.
+        """
+
+        def format_help(self) -> str:
+            text = super().format_help()
+            if self.heading is None or self.heading is argparse.SUPPRESS:
+                return text
+            indent = " " * self.formatter._current_indent  # as argparse indented the heading
+            plain = f"\n{indent}{self.heading}:\n"
+            if not text.startswith(plain):
+                return text
+            heading = _("%(heading)s:") % {"heading": self.heading}
+            return f"\n{indent}{heading}\n{text[len(plain) :]}"
+
+    def _fill_text(self, text: str, width: int, indent: str) -> str:
+        # The credit is never wrapped (--help, --version): a break could split "Claude Code".
+        keep, fill = credit(), super()._fill_text
+        lines = text.split("\n")
+        return "\n".join(
+            indent + line if line == keep else fill(line, width, indent) for line in lines
+        )
+
+
+_PLAIN_ARGUMENT = re.compile(r"argument (?P<argument_name>.+?): (?P<message>.*)", re.DOTALL)
+
+
+class PyGUIbudParser(argparse.ArgumentParser):
+    """An argument parser whose own texts (usage, titles, -h, errors) are translated.
+
+    argparse translates them with its private catalogue, which has no pyguibud languages, so
+    its ``_`` is bound to ours while this parser works. Build it only after the language is
+    chosen (``_select_initial_language``).
+    """
+
+    @_bound
+    def __init__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401 - argparse's own
+        kwargs.setdefault("formatter_class", _Formatter)
+        kwargs["add_help"] = False
+        super().__init__(*args, **kwargs)
+        self.add_argument("-h", "--help", action="help", help=_("show this help message and exit"))
+
+    parse_known_args = _bound(argparse.ArgumentParser.parse_known_args)
+    parse_args = _bound(argparse.ArgumentParser.parse_args)
+    format_help = _bound(argparse.ArgumentParser.format_help)
+    format_usage = _bound(argparse.ArgumentParser.format_usage)
+
+    @_bound
+    def error(self, message: str) -> NoReturn:
+        # Before 3.11.9/3.12.3 ArgumentError.__str__ does not translate its prefix: a feature
+        # test, as for the heading colon (a translated prefix never matches the English one).
+        plain = _PLAIN_ARGUMENT.fullmatch(message)
+        if plain is not None:
+            message = _("argument %(argument_name)s: %(message)s") % plain.groupdict()
+        argparse.ArgumentParser.error(self, message)
+
+
+def _make_stdout_safe() -> None:
+    """Never crash on characters the console encoding cannot represent."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            with contextlib.suppress(ValueError, OSError):
+                reconfigure(errors="replace")
+
+
+def _select_initial_language(argv: list[str] | None, option: str = "--lang") -> None:
+    """Set the language before the real parser is built so --help and errors are translated.
+
+    ``option`` names the interface-language option (the preview child's is ``--ui-lang``).
+    """
+    pre = _QuietParser(add_help=False, allow_abbrev=False)
+    pre.add_argument(option, dest="lang", default=None)
+    requested: str | None = None
+    try:
+        known, _rest = pre.parse_known_args(argv)
+        requested = known.lang
+    except _PreParseError:
+        pass
+    set_language(_requested_language(requested) or detect_language())
+
+
+def _requested_language(value: str | None) -> str | None:
+    """The supported code of a ``--lang`` value, or None.
+
+    Unlike an environment variable (``de_DE.UTF-8``), the option must be a plain language code,
+    so ``de_DE/../x`` or ``en_XA;rm`` is refused instead of being cut down to a language (QA-11-12).
+    """
+    if value is None or LANGUAGE_CODE_RE.fullmatch(value) is None:
+        return None
+    return normalise_language(value)

pyguibud/cli.py

@@ -0,0 +1,155 @@
+"""PyGUIbud command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .__about__ import __version__
+from ._argparse import (
+    PyGUIbudParser,
+    _make_stdout_safe,
+    _requested_language,
+    _select_initial_language,
+)
+from .credits import credit
+from .i18n import (
+    LANGUAGES,
+    PSEUDO_LANGUAGE,
+    _,
+    get_language,
+    set_language,
+)
+
+
+def version_text() -> str:
+    """The ``--version`` text: program, version and the author credit (``%`` escaped)."""
+    return "%(prog)s " + f"{__version__}\n{credit()}".replace("%", "%%")
+
+
+def _language_arg(value: str) -> str:
+    code = _requested_language(value)
+    if code is None:
+        valid = ", ".join((*LANGUAGES, PSEUDO_LANGUAGE))
+        raise argparse.ArgumentTypeError(
+            # Translators: {code} is what the user typed, {valid} a list of language codes.
+            _("unknown language '{code}'; valid codes are: {valid}").format(code=value, valid=valid)
+        )
+    return code
+
+
+def _print_languages() -> None:
+    active = get_language()
+    # Translators: heading above the list of selectable interface languages.
+    print(_("Available interface languages (* marks the active one):"))
+    for code, autonym in LANGUAGES.items():
+        print(f"{'*' if code == active else ' '} {code}  {autonym}")
+    print()
+    # Translators: {code} is the pseudo-locale code; it is not a real language.
+    print(
+        _("The pseudo-locale {code} is also accepted; it is meant for testing layouts.").format(
+            code=PSEUDO_LANGUAGE
+        )
+    )
+
+
+#: The ``--theme`` choices are fixed tokens (never translated), like option names.
+THEME_CHOICES = ("light", "dark", "high-contrast")
+
+
+def _default_launch(lang: str | None, theme: str | None, **keywords: Any) -> int:  # noqa: ANN401
+    """Open the designer; Tk is imported only here, so --version and --help never load it."""
+    from pyguibud.designer import launch
+
+    return launch(lang, theme, **keywords)
+
+
+def main(argv: list[str] | None = None, *, launch: Callable[..., int] | None = None) -> int:
+    """Entry point for the PyGUIbud CLI.
+
+    Args:
+        argv: Command-line arguments; defaults to sys.argv[1:].
+        launch: Opens the designer as ``launch(language, theme)`` (plus ``path=`` when a FILE
+            is given) and returns the exit code; ``language`` and ``theme`` are None when not
+            given, so the designer's settings decide; ``no_plugins=True`` only with
+            ``--no-plugins``. Tests inject a fake. Defaults to
+            :func:`pyguibud.designer.launch`.
+
+    Returns:
+        Exit code (0 on success).
+    """
+    _make_stdout_safe()
+    _select_initial_language(argv)
+
+    parser = PyGUIbudParser(
+        prog="pyguibud",
+        description=_("PyGUIbud: drag-and-drop GUI builder for Python."),
+        epilog=credit(),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_text(),
+        help=_("show the version number and exit"),
+    )
+    parser.add_argument(
+        "--lang",
+        metavar="CODE",
+        type=_language_arg,
+        default=None,
+        help=_("interface language code, for example de_DE or en_XA"),
+    )
+    parser.add_argument(
+        "--list-languages",
+        action="store_true",
+        help=_("list the available interface languages and exit"),
+    )
+
+    parser.add_argument(
+        "--theme",
+        choices=THEME_CHOICES,
+        default=None,
+        # Translators: {default} is the --theme value used by default (light), inserted as it
+        # is: the option accepts only the untranslated names shown in its list of choices.
+        help=_("designer colour theme (default: the last one used, else {default})").format(
+            default=THEME_CHOICES[0]
+        ),
+    )
+    parser.add_argument(
+        "--no-plugins",
+        action="store_true",
+        # Translators: the safe-mode option; plugins are widget packages installed separately.
+        help=_("start without loading any plugin (safe mode)"),
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        metavar="FILE",
+        default=None,
+        help=_("a .ui file to open"),
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.lang is not None and args.lang != get_language():
+        set_language(args.lang)
+
+    if args.list_languages:
+        _print_languages()
+        return 0
+
+    keywords: dict[str, Any] = {"no_plugins": True} if args.no_plugins else {}
+    if args.file is not None:
+        from .core.files import is_network_or_device_path
+
+        # Never touch a network path, not even to test that it exists (R82).
+        if is_network_or_device_path(args.file):
+            parser.error(_("Network and device paths cannot be opened."))
+        if not os.path.exists(args.file):
+            # Translators: {path} is the file named on the command line.
+            parser.error(_("The file '{path}' does not exist.").format(path=args.file))
+        keywords["path"] = Path(os.path.abspath(args.file))
+    return (launch or _default_launch)(args.lang, args.theme, **keywords)

pyguibud/codegen/__init__.py

@@ -0,0 +1,198 @@
+"""``pyguibud.codegen``: Python code from ``.ui`` files (spec ``docs/specs/codegen.md``, ADR-008).
+
+The generated module needs only the standard library and ``ttkbootstrap``. This package never
+imports a toolkit, ``pyguibud_runtime`` or its own ``_support`` module: it copies the *text* of
+``_support.py``. The output depends only on the ``.ui`` files (and their images), never on the
+CLI language, the machine, the working directory, the hash seed or the time.
+"""
+
+from __future__ import annotations
+
+import keyword
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from pyguibud.__about__ import __version__
+from pyguibud.codegen._emit import Emitter, image_constant, lit
+from pyguibud.codegen._errors import (
+    M_INVALID_ONE,
+    M_NOTHING,
+    M_OUTSIDE,
+    M_READ_ONLY,
+    M_UNSAFE,
+    CodegenError,
+)
+from pyguibud.codegen._plan import Plan
+from pyguibud.codegen._pot import extract_pot
+from pyguibud.core.diagnostics import Finding
+from pyguibud.core.files import DiskFiles
+from pyguibud.core.registry import default_registry
+from pyguibud.core.validate import validate
+from pyguibud.core.xml_io import ReadResult
+
+__all__ = [
+    "FORMAT",
+    "GENERATED_MARKER",
+    "CodegenError",
+    "GeneratedModule",
+    "default_output",
+    "extract_pot",
+    "generate_python",
+    "support_text",
+]
+
+GENERATED_MARKER: Final = "# Generated by pyguibud-uic"
+FORMAT: Final = 1
+
+_SUPPORT_FILE: Final = Path(__file__).with_name("_support.py")
+_BEGIN: Final = "# --- BEGIN SUPPORT ---"
+_END: Final = "# --- END SUPPORT ---"
+_NOT_NAME: Final = re.compile(r"[^A-Za-z0-9_]")
+# Warnings for --check and load_ui, refused by the code generator unless allowed (QA-11-03).
+_OUTSIDE_CODES: Final = frozenset({"validate.absolute_path", "validate.path_escapes"})
+
+
+@dataclass(frozen=True)
+class GeneratedModule:
+    """The text of a generated module (LF newlines, ends with one newline)."""
+
+    text: str
+    class_name: str
+    warnings: tuple[Finding, ...]
+    #: Every .ui file the module was generated from (the input and its included files).
+    sources: tuple[str, ...] = ()
+
+
+def support_text() -> str:
+    """The support region of ``_support.py``, without its markers (CRLF-safe)."""
+    text = _SUPPORT_FILE.read_bytes().decode("utf-8").replace("\r\n", "\n")
+    lines = text.split("\n")
+    region = lines[lines.index(_BEGIN) + 1 : lines.index(_END)]
+    return "\n".join(region).strip("\n")
+
+
+def _stem_name(path: str) -> str:
+    stem = _NOT_NAME.sub("_", os.path.splitext(os.path.basename(path))[0])
+    return "_" + stem if stem[:1].isdigit() else stem
+
+
+def default_output(path: str) -> str:
+    """``"dir/my-form.ui"`` -> ``"dir/my_form_ui.py"`` (an importable module name)."""
+    return os.path.join(os.path.dirname(path), _stem_name(path) + "_ui.py")
+
+
+def _class_name(main_id: str | None, path: str) -> str:
+    if main_id:
+        base = main_id[:1].upper() + main_id[1:]
+    else:
+        # A stem without ASCII letters or digits ("日本.ui", "__.ui") gives a fixed name.
+        stem = _stem_name(path)
+        base = stem if stem.strip("_") else "Form"
+    name = "Ui_" + base
+    if not name.isascii() or not name.isidentifier() or keyword.iskeyword(name):
+        raise CodegenError("codegen.unsafe_name", M_UNSAFE, name=name)
+    return name
+
+
+def generate_python(
+    result: ReadResult, path: str, *, output: str, allow_outside: bool = False
+) -> GeneratedModule:
+    """Validate ``result`` (read from ``path``) with its includes and images, then generate.
+
+    ``output`` is the path the module will be written to; it is used only to compute the
+    relative catalogue folders and never appears in the text. An image or include path that is
+    absolute or leaves the folder of its ``.ui`` file is only a warning for ``--check`` and
+    ``load_ui``, but the code generator refuses it unless ``allow_outside`` (``--force``).
+
+    Raises:
+        CodegenError: ``codegen.invalid_document``, ``codegen.read_only``,
+            ``codegen.outside_path``, ``codegen.nothing_to_generate``,
+            ``codegen.unsafe_name`` or ``codegen.image_changed``.
+    """
+    registry = default_registry()
+    files = DiskFiles(path, result)
+    report = validate(
+        result.document,
+        registry,
+        source=result.source,
+        positions=result.positions,
+        files=files,
+    )
+    errors = report.errors
+    if errors:
+        raise CodegenError(
+            "codegen.invalid_document", M_INVALID_ONE, findings=errors, path=path, count=len(errors)
+        )
+    if result.read_only:
+        raise CodegenError(
+            "codegen.read_only", M_READ_ONLY, path=path, version=result.source_version
+        )
+    outside = tuple(f for f in report.warnings if f.code in _OUTSIDE_CODES)
+    if outside and not allow_outside:  # QA-11-03: the module would embed files from elsewhere
+        raise CodegenError(
+            "codegen.outside_path",
+            M_OUTSIDE,
+            findings=outside,
+            path=path,
+            src=outside[0].params.get("path", ""),
+            force="--force",
+        )
+    document = result.document
+    mains = [w for w in document.children if w.kind == "main"]
+    windows = mains + [w for w in document.children if w.kind == "dialog"]
+    if not windows:
+        raise CodegenError("codegen.nothing_to_generate", M_NOTHING, path=path)
+    class_name = _class_name(mains[0].id if mains else None, path)
+    plan = Plan(files, document, result.source, output)
+    emitter = Emitter(plan, registry)
+    build = emitter.build(windows)
+    docs = tuple(
+        (
+            doc.document.meta.i18n_domain,
+            doc.document.meta.source_locale,
+            plan.locale_dir(doc, output),
+        )
+        for doc in plan.docs
+    )
+    lines = [
+        f"{GENERATED_MARKER} {__version__} (format {FORMAT}) from "
+        f"{os.path.basename(path)!a}. Do not edit: changes are lost on regeneration.",
+        "# Requires Python >= 3.10 and ttkbootstrap >= 2.2, < 3. This module does not import "
+        "PyGUIbud.",
+        "from __future__ import annotations",
+        "",
+        f"# --- support: identical in every generated module (pyguibud-uic format {FORMAT}) ---",
+        support_text(),
+        "# --- end of support ---",
+        "",
+        f"_DOCS = {lit(docs)}",
+        f"_HANDLERS = {lit(tuple(sorted(emitter.handlers)))}",
+        f"_THEME = {lit(document.meta.theme)}",
+    ]
+    for image in plan.images:
+        lines += image_constant(image.number, image.data)
+    lines += [
+        "",
+        "",
+        f"class {class_name}(_Ui):",
+        '    """Generated interface; build it with setup_ui()."""',
+        "",
+        "    _docs = _DOCS",
+        "    _handler_names = _HANDLERS",
+        "    _theme_name = _THEME",
+        *([] if mains else ["    _has_main = False"]),
+        "",
+        *build,
+    ]
+    for number in sorted(emitter.methods):
+        lines += ["", *emitter.methods[number]]
+    lines += ["", "", 'if __name__ == "__main__":', f"    _preview({class_name})"]
+    return GeneratedModule(
+        text="\n".join(lines) + "\n",
+        class_name=class_name,
+        warnings=(*report.warnings, *plan.warnings),
+        sources=tuple(files.path_of(doc.key) for doc in plan.docs),
+    )