composeui 0.1.0__py3-none-any.whl

composeui/core/study.py

@@ -0,0 +1,121 @@
+"""A study: the views' state and the model's data, started, saved and opened together.
+
+Without data of its own in the model (`Model.data_name` is None), a study is the views'
+state as JSON (`MainView.save_state`). With it, a study is a zip archive of the views'
+state (`views.json`) and the model's file, so the two are never saved or opened apart.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import zipfile
+import zlib
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from composeui.core.model import InvalidStateError
+
+if TYPE_CHECKING:
+    from composeui.core.model import Model
+    from composeui.core.view import MainView
+
+__all__ = ["open_study", "save_study"]
+
+#: the views' state inside a study's archive, with its versions (`MainView.file_data`)
+VIEWS_NAME = "views.json"
+#: what reading a damaged archive can raise
+_BAD_ARCHIVE_ERRORS = (zipfile.BadZipFile, zlib.error, EOFError)
+#: the compression methods a study's archive may use: what `save_study` writes. `zipfile`
+#: unpacks a bzip2 or LZMA member whole, whatever size is read, so a few bytes of one can
+#: unpack into gigabytes; another method it can't unpack at all (`NotImplementedError`)
+_COMPRESSIONS = frozenset({zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED})
+#: a member's flag of an encrypted one, which `zipfile` won't read without a password
+_ENCRYPTED = 0x1
+
+
+def has_data(model: Model | None) -> bool:
+    """Tell whether a study with this model is an archive, rather than the views' JSON."""
+    return model is not None and model.data_name is not None
+
+
+def new_study(main_view: MainView, model: Model | None) -> None:
+    """Start a new study: the model's data and the views back to their start."""
+    main_view.reset_state()
+    if model is not None:
+        model.new()
+        model.loaded()
+
+
+def save_study(main_view: MainView, model: Model | None, path: Path) -> None:
+    """Save the views' state and the model's data into the file `path`."""
+    if model is None or model.data_name is None:
+        main_view.save_state(path)
+        return
+    # written beside `path` and renamed over it, so a failed save leaves the old study whole
+    partial = path.with_name(f".{path.name}.partial")
+    try:
+        with tempfile.TemporaryDirectory(prefix="composeui-") as directory:
+            data_path = Path(directory, model.data_name)
+            model.save_data(data_path)
+            with zipfile.ZipFile(partial, "w", zipfile.ZIP_DEFLATED) as archive:
+                archive.writestr(VIEWS_NAME, json.dumps(main_view.file_data()))
+                archive.write(data_path, model.data_name)
+        partial.replace(path)
+    finally:
+        partial.unlink(missing_ok=True)
+    main_view.state_filepath = path
+
+
+def open_study(
+    main_view: MainView, model: Model | None, path: Path, *, max_size: int | None = None
+) -> None:
+    """Open the study saved in the file `path`, into the views and the model.
+
+    Everything is checked before anything changes: raises `InvalidStateError`, leaving the
+    views and the model unchanged, for a file that doesn't fit them. `max_size` caps the
+    archive's unpacked size, in bytes, against a small file unpacking into a huge one.
+    """
+    if model is None or model.data_name is None:
+        main_view.load_state(path)
+        if model is not None:
+            model.loaded()
+        return
+    invalid = f"it isn't a valid {main_view.extension} file"
+    try:
+        with zipfile.ZipFile(path) as archive:
+            members = archive.infolist()
+            if sorted(member.filename for member in members) != sorted(
+                [VIEWS_NAME, model.data_name]
+            ) or any(
+                member.compress_type not in _COMPRESSIONS or member.flag_bits & _ENCRYPTED
+                for member in members
+            ):
+                raise InvalidStateError(invalid)
+            # The sizes the archive declares, which it may lie about: a member that unpacks
+            # into more is cut there, and then fails its CRC (`BadZipFile`).
+            if max_size is not None and sum(member.file_size for member in members) > max_size:
+                msg = "the file is too large"
+                raise InvalidStateError(msg)
+            views = archive.getinfo(VIEWS_NAME)
+            try:
+                # not `archive.read`: it unpacks the whole member before cutting it
+                with archive.open(views) as member:
+                    data = json.loads(member.read(views.file_size))
+            except ValueError as error:  # also covers bytes that aren't text
+                raise InvalidStateError(invalid) from error
+            data = main_view.state_data_from_file(data)
+            main_view.check_state_data(data)
+            # before the model's data is replaced: a job writing to it would write into the
+            # study opened (see `Jobs`), so it stops once its open fails too
+            main_view.jobs.drop()
+            with tempfile.TemporaryDirectory(prefix="composeui-") as directory:
+                # the member is named after the model's file, never a path of the archive's
+                archive.extract(model.data_name, directory)
+                model.open_data(Path(directory, model.data_name))
+    except _BAD_ARCHIVE_ERRORS as error:
+        raise InvalidStateError(invalid) from error
+    # checked above, so it can't fail now that the model has changed
+    main_view.load_state_data(data)
+    main_view.state_filepath = path
+    model.loaded()

composeui/core/translation.py

@@ -0,0 +1,221 @@
+"""Translate the text views show, from JSON catalogs.
+
+A catalog is a ``<language>.json`` file mapping the text as written in the code to its
+translation: ``{"Radius": "Rayon"}``. Text missing from every catalog is shown as written,
+like text translated as "": a translation still to fill.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Callable, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from typing_extensions import Self
+
+__all__ = ["T", "TranslatedText", "translator"]
+
+#: translates a text as written in the code into a language
+Translate = Callable[[str], str]
+
+#: ComposeUI's own catalogs, for the text of the views it defines (menus, dialogs...)
+CATALOGS_DIR = Path(__file__).parent.parent / "locales"
+
+
+#: languages by code, each named in itself, as a menu offering them shows them
+LANGUAGE_NAMES: Mapping[str, str] = MappingProxyType(
+    {
+        "ar": "العربية",
+        "bg": "Български",
+        "ca": "Català",
+        "cs": "Čeština",
+        "da": "Dansk",
+        "de": "Deutsch",
+        "el": "Ελληνικά",
+        "en": "English",
+        "es": "Español",
+        "et": "Eesti",
+        "fa": "فارسی",
+        "fi": "Suomi",
+        "fr": "Français",
+        "he": "עברית",
+        "hi": "हिन्दी",
+        "hr": "Hrvatski",
+        "hu": "Magyar",
+        "id": "Bahasa Indonesia",
+        "it": "Italiano",
+        "ja": "日本語",
+        "ko": "한국어",
+        "lt": "Lietuvių",
+        "lv": "Latviešu",
+        "nb": "Norsk bokmål",
+        "nl": "Nederlands",
+        "pl": "Polski",
+        "pt": "Português",
+        "ro": "Română",
+        "ru": "Русский",
+        "sk": "Slovenčina",
+        "sl": "Slovenščina",
+        "sr": "Српски",
+        "sv": "Svenska",
+        "th": "ไทย",
+        "tr": "Türkçe",
+        "uk": "Українська",
+        "vi": "Tiếng Việt",
+        "zh": "中文",
+    }
+)
+
+
+def language_name(language: str, names: Mapping[str, str] = LANGUAGE_NAMES) -> str:
+    """Name `language` in itself, from `names`: "fr-CA" is "Français (CA)".
+
+    A language `names` doesn't know is named by its code.
+    """
+    if language in names:
+        return names[language]
+    base, _, region = language.replace("_", "-").partition("-")
+    if base not in names:
+        return language
+    return f"{names[base]} ({region})" if region else names[base]
+
+
+def no_translation(text: str) -> str:
+    """Show `text` as written in the code."""
+    return text
+
+
+def _language_names(language: str) -> list[str]:
+    """Get the catalog names to look for, most specific first: "fr-CA" then "fr"."""
+    names = [language, language.replace("_", "-")]
+    names.append(names[-1].split("-")[0])
+    return list(dict.fromkeys(names))
+
+
+def load_catalog(directory: Path, language: str) -> dict[str, str]:
+    """Load `language`'s catalog in `directory`, or an empty one if it has none.
+
+    A regional language ("fr-CA", "fr_CA") falls back on its base language's ("fr").
+    """
+    for name in _language_names(language):
+        path = directory / f"{name}.json"
+        if path.is_file():
+            with path.open(encoding="utf-8") as f:
+                catalog = json.load(f)
+            if not isinstance(catalog, dict) or not all(
+                isinstance(key, str) and isinstance(value, str) for key, value in catalog.items()
+            ):
+                msg = f"{path} must map each text to its translation, both strings"
+                raise ValueError(msg)
+            return catalog
+    return {}
+
+
+def translator(language: str, directories: Sequence[Path]) -> Translate:
+    """Get the translation into `language` from the catalogs in `directories`.
+
+    The first directory with a translation of a text wins: an app's catalogs, listed
+    before ComposeUI's, can change the text of ComposeUI's views.
+    """
+    catalog: dict[str, str] = {}
+    for directory in reversed(directories):
+        # "" is still to fill: a catalog after it can translate the text
+        catalog.update(
+            (text, translation)
+            for text, translation in load_catalog(directory, language).items()
+            if translation != ""
+        )
+
+    def translate(text: str) -> str:
+        return catalog.get(text, text)
+
+    return translate
+
+
+# a `__dict__` for what it remembers: a str subclass can't have non-empty `__slots__`
+class TranslatedText(str):  # noqa: SLOT000
+    """Text `View.tr` translated, remembering it as written to translate it again.
+
+    `MainView.set_language` translates it again wherever a view keeps it: in a field, a
+    list (a table's headers) or a dict's keys (a choice's labels). Formatting it keeps the
+    arguments, to format the next translation with them. Other str methods return a plain
+    str, which stays in its language.
+
+    Built from `text` alone (as `T`), it is the text as written. It is translated once a
+    view keeps it and the main view sets a language. Use it for text declared where no
+    view can `tr` it, e.g. a field's default or a class variable.
+    """
+
+    source: str
+    #: the `format` arguments, or `None` if it isn't formatted
+    arguments: tuple[tuple[Any, ...], dict[str, Any]] | None
+
+    def __new__(
+        cls,
+        text: str,
+        source: str | None = None,
+        arguments: tuple[tuple[Any, ...], dict[str, Any]] | None = None,
+    ) -> Self:
+        self = super().__new__(cls, text)
+        self.source = text if source is None else source
+        self.arguments = arguments
+        return self
+
+    def __getnewargs__(self) -> tuple[str, str, tuple[tuple[Any, ...], dict[str, Any]] | None]:  # type: ignore[override]
+        # copying it (`copy.deepcopy`) keeps what it remembers
+        return (str(self), self.source, self.arguments)
+
+    def format(self, *args: Any, **kwargs: Any) -> TranslatedText:
+        """Format it, remembering the arguments: translated text among them follows too."""
+        return TranslatedText(str.format(self, *args, **kwargs), self.source, (args, kwargs))
+
+    def translated(self, translate: Translate) -> TranslatedText:
+        """Translate it again, with `translate`."""
+        text = translate(self.source)
+        if self.arguments is None:
+            return TranslatedText(text, self.source)
+        args, kwargs = self.arguments
+        args = tuple(translate_again(arg, translate) for arg in args)
+        kwargs = {key: translate_again(value, translate) for key, value in kwargs.items()}
+        return TranslatedText(text.format(*args, **kwargs), self.source, (args, kwargs))
+
+
+#: text to translate, as written in the code, wherever it's declared:
+#: ``add: ButtonView = child(ButtonView, text=T("Add"))``
+T = TranslatedText
+
+
+@runtime_checkable
+class Translatable(Protocol):
+    """A value holding `TranslatedText`, e.g. a table cell's button with its text."""
+
+    def translated(self, translate: Translate) -> Translatable:
+        """Get it with its text translated again; itself if it holds none."""
+
+
+def translate_again(value: Any, translate: Translate) -> Any:
+    """Translate the `TranslatedText` in `value` again, itself or in a list, tuple or dict.
+
+    A `Translatable` translates its own. Return `value` itself when it holds none, so a
+    caller can tell nothing changed.
+    """
+    if isinstance(value, (TranslatedText, Translatable)):
+        return value.translated(translate)
+    if isinstance(value, (list, tuple)):
+        items = [translate_again(item, translate) for item in value]
+        if all(new is old for new, old in zip(items, value)):
+            return value
+        return type(value)(items) if type(value) in (list, tuple) else value
+    if isinstance(value, dict):
+        entries = [
+            (translate_again(key, translate), translate_again(item, translate))
+            for key, item in value.items()
+        ]
+        if all(k is k0 and v is v0 for (k, v), (k0, v0) in zip(entries, value.items())):
+            return value
+        return dict(entries)
+    return value

composeui/core/translationcheck.py

@@ -0,0 +1,254 @@
+"""Check an app's catalogs against the text its code translates.
+
+Run it on the app's main view; it fails on text a catalog misses or on a translation whose
+``{placeholders}`` differ from the text's, and lists the entries no code uses::
+
+    python -m composeui.core.translationcheck examples.pipeform:PipeMainView
+
+With ``--write fr``, it first adds the text ``fr.json`` misses to it, translated as "" for a
+translator to fill; until then, the text shows as written.
+
+The text is found two ways: the string literals passed to ``tr`` or ``T`` (or set in a
+``SqliteTable``'s ``refusals``) in the source of every view of the main view, and the text
+the views translate as they show it, which finds text ``tr`` gets from a variable, e.g. an
+enum's. A table's refusals are found only in a module of a view.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import importlib
+import inspect
+import json
+import string
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import attrs
+
+from composeui.core.translation import CATALOGS_DIR, load_catalog
+from composeui.core.view import _retranslate
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator, Sequence
+
+    from composeui.core.view import MainView, View
+
+__all__ = ["CatalogReport", "check_main_view", "main", "placeholders"]
+
+
+@attrs.define
+class CatalogReport:
+    """What a catalog lacks, or has too much of, for the text of the code."""
+
+    path: Path
+    #: text no catalog translates, or as "": it shows as written in the code
+    missing: list[str] = attrs.Factory(list)
+    #: text and translation whose ``{placeholders}`` differ: formatting it fails or loses one
+    mismatched: list[tuple[str, str]] = attrs.Factory(list)
+    #: entries for text the code doesn't translate, or no longer
+    unused: list[str] = attrs.Factory(list)
+
+    @property
+    def is_ok(self) -> bool:
+        """Tell whether every text is translated with its placeholders."""
+        return not self.missing and not self.mismatched
+
+    def __str__(self) -> str:
+        lines = [
+            f"{self.path}: {len(self.missing)} missing, {len(self.mismatched)} with other "
+            f"placeholders, {len(self.unused)} unused"
+        ]
+        lines.extend(f"  missing: {text!r}" for text in self.missing)
+        lines.extend(
+            f"  other placeholders: {text!r} -> {translation!r}"
+            for text, translation in self.mismatched
+        )
+        lines.extend(f"  unused: {text!r}" for text in self.unused)
+        return "\n".join(lines)
+
+
+def find_texts(paths: Iterable[Path]) -> set[str]:
+    """Find the text the code in `paths` translates: `_TEXT_CALLS` literals, `_TEXT_DICTS`."""
+    texts: set[str] = set()
+    for path in paths:
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for node in ast.walk(tree):
+            texts.update(_literal_texts(node))
+    return texts
+
+
+#: what translates the text it's called with: a view's `tr`, and `T` declaring it
+_TEXT_CALLS = ("tr", "T")
+#: class variables whose dict values are text to translate: a `SqliteTable`'s refusals
+#: (`View.refusing` translates them)
+_TEXT_DICTS = ("refusals",)
+
+
+def _literal_texts(node: ast.AST) -> Iterator[str]:
+    if isinstance(node, ast.Call) and node.args:
+        func = node.func
+        name = func.attr if isinstance(func, ast.Attribute) else getattr(func, "id", None)
+        if name in _TEXT_CALLS:
+            yield from _strings([node.args[0]])
+    elif isinstance(node, (ast.Assign, ast.AnnAssign)) and isinstance(node.value, ast.Dict):
+        targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+        if any(getattr(target, "id", None) in _TEXT_DICTS for target in targets):
+            yield from _strings(node.value.values)
+
+
+def _strings(nodes: Iterable[ast.expr | None]) -> Iterator[str]:
+    for node in nodes:
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            yield node.value
+
+
+def shown_texts(main_view: MainView) -> set[str]:
+    """Find the text `main_view`'s views translate to show it, retranslating them."""
+    texts: set[str] = set()
+
+    def record(text: str) -> str:
+        texts.add(text)
+        return text
+
+    _retranslate(main_view, record)
+    return texts
+
+
+def _views(view: View) -> Iterator[View]:
+    yield view
+    for child in view.children_views:
+        yield from _views(child)
+
+
+def source_paths(main_view: MainView) -> set[Path]:
+    """Get the source files of `main_view`'s view classes and their base classes."""
+    paths: set[Path] = set()
+    for view in _views(main_view):
+        for cls in type(view).__mro__:
+            module = sys.modules.get(cls.__module__)
+            file = getattr(module, "__file__", None)
+            if file is not None and file.endswith(".py"):
+                paths.add(Path(file))
+    return paths
+
+
+def placeholders(text: str) -> set[str] | None:
+    """Get the ``{fields}`` `text` formats, or `None` if it isn't a valid format."""
+    try:
+        return {name for _, name, _, _ in string.Formatter().parse(text) if name is not None}
+    except ValueError:
+        return None
+
+
+def check_catalog(
+    path: Path, texts: set[str], catalog: dict[str, str], others: Sequence[dict[str, str]] = ()
+) -> CatalogReport:
+    """Check the catalog at `path` (`catalog`) against `texts`.
+
+    `others` are the catalogs it falls back on, e.g. ComposeUI's: their text isn't missing.
+    """
+    report = CatalogReport(path)
+    report.missing = sorted(texts - _translated(catalog, *others))
+    report.unused = sorted(set(catalog) - texts)
+    report.mismatched = [
+        (text, translation)
+        for text, translation in catalog.items()
+        if translation != "" and placeholders(text) != placeholders(translation)
+    ]
+    return report
+
+
+def _translated(*catalogs: dict[str, str]) -> set[str]:
+    return {text for catalog in catalogs for text, translation in catalog.items() if translation}
+
+
+def _app_texts(main_view_class: type[MainView]) -> tuple[Path, set[str]]:
+    """Get the directory of the app's catalogs and the text its code translates."""
+    directory = main_view_class.translations_dir
+    if directory is None:
+        msg = f"{main_view_class.__name__} sets no translations_dir"
+        raise ValueError(msg)
+    main_view = main_view_class()
+    return directory, find_texts(source_paths(main_view)) | shown_texts(main_view)
+
+
+def write_catalog(main_view_class: type[MainView], language: str) -> tuple[Path, list[str]]:
+    """Add the text `language`'s catalog misses to it, translated as "" for a translator.
+
+    Its entries are kept, unused ones too. A regional language's new catalog ("fr-CA")
+    starts from its base language's: it replaces it. Text ComposeUI's catalog translates
+    isn't added: the app's catalog only has it to translate it otherwise.
+    Return the catalog's path and the text added.
+    """
+    directory, texts = _app_texts(main_view_class)
+    catalog = load_catalog(directory, language)
+    added = sorted(texts - set(catalog) - _translated(load_catalog(CATALOGS_DIR, language)))
+    catalog.update(dict.fromkeys(added, ""))
+    path = directory / f"{language}.json"
+    directory.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(catalog, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return path, added
+
+
+def check_main_view(main_view_class: type[MainView]) -> list[CatalogReport]:
+    """Check each catalog in `main_view_class.translations_dir` against the app's text."""
+    directory, texts = _app_texts(main_view_class)
+    reports = []
+    for path in sorted(directory.glob("*.json")):
+        language = path.stem
+        reports.append(
+            check_catalog(
+                path,
+                texts,
+                load_catalog(directory, language),
+                [load_catalog(CATALOGS_DIR, language)],
+            )
+        )
+    return reports
+
+
+def _main_view_class(spec: str) -> type[MainView]:
+    module_name, _, class_name = spec.partition(":")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as error:
+        raise argparse.ArgumentTypeError(str(error)) from error
+    cls = getattr(module, class_name, None)
+    if not inspect.isclass(cls):
+        msg = f"{spec} isn't a class: expected module:MainViewClass"
+        raise argparse.ArgumentTypeError(msg)
+    return cls
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Print a report for each catalog of a main view; 1 if one isn't ok, else 0."""
+    parser = argparse.ArgumentParser(
+        prog="python -m composeui.core.translationcheck", description=__doc__.splitlines()[0]
+    )
+    parser.add_argument(
+        "main_view", type=_main_view_class, help="the app's main view, as module:Class"
+    )
+    parser.add_argument(
+        "--write",
+        action="append",
+        default=[],
+        metavar="LANGUAGE",
+        help='first add the text to translate to LANGUAGE\'s catalog, translated as ""',
+    )
+    args = parser.parse_args(argv)
+    for language in args.write:
+        path, added = write_catalog(args.main_view, language)
+        print(f"{path}: {len(added)} entries added to translate")  # noqa: T201
+    reports = check_main_view(args.main_view)
+    for report in reports:
+        print(report)  # noqa: T201
+    if not reports:
+        print(f"no catalog in {args.main_view.translations_dir}")  # noqa: T201
+    return 0 if all(report.is_ok for report in reports) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())