copier-ui 0.6.8__tar.gz

copier_ui-0.6.8/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: copier-ui
+Version: 0.6.8
+Summary: UI-neutral abstraction over a copier template survey: normalised schema, dependency graph, visibility and validation
+Author-email: Stellars Henson <konrad.jelen+github@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/stellarshenson/copier-tui
+Project-URL: Repository, https://github.com/stellarshenson/copier-tui
+Project-URL: Issues, https://github.com/stellarshenson/copier-tui/issues
+Keywords: copier,template,scaffolding,questionnaire,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: copier>=9.6
+
+# copier-ui
+
+UI-neutral abstraction over a [copier](https://copier.readthedocs.io) template survey.
+
+`copier-ui` reads a template's questions and turns them into a normalised schema with a
+dependency graph, visibility state and validation. It owns semantics and renders nothing, so
+the same core drives a terminal UI, a web UI, an HTTP API or a test.
+
+It never imports a display library and never requires an event loop.
+
+```python
+from copier_ui import TemplateUI
+
+# unsafe=True is copier's own trust gate: this template declares Jinja extensions and tasks,
+# and copier_ui refuses to load such a template before importing anything unless you say so
+ui = TemplateUI.from_template("gh:stellarshenson/copier-data-science", unsafe=True)
+ui.set("dataset_storage", "s3")
+ui.state().fields["s3_bucket"].visible   # True
+ui.render("./my-project")
+```
+
+Part of the [copier-tui](https://github.com/stellarshenson/copier-tui) project.

copier_ui-0.6.8/README.md

@@ -0,0 +1,22 @@
+# copier-ui
+
+UI-neutral abstraction over a [copier](https://copier.readthedocs.io) template survey.
+
+`copier-ui` reads a template's questions and turns them into a normalised schema with a
+dependency graph, visibility state and validation. It owns semantics and renders nothing, so
+the same core drives a terminal UI, a web UI, an HTTP API or a test.
+
+It never imports a display library and never requires an event loop.
+
+```python
+from copier_ui import TemplateUI
+
+# unsafe=True is copier's own trust gate: this template declares Jinja extensions and tasks,
+# and copier_ui refuses to load such a template before importing anything unless you say so
+ui = TemplateUI.from_template("gh:stellarshenson/copier-data-science", unsafe=True)
+ui.set("dataset_storage", "s3")
+ui.state().fields["s3_bucket"].visible   # True
+ui.render("./my-project")
+```
+
+Part of the [copier-tui](https://github.com/stellarshenson/copier-tui) project.

copier_ui-0.6.8/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "copier-ui"
+version = "0.6.8"
+description = "UI-neutral abstraction over a copier template survey: normalised schema, dependency graph, visibility and validation"
+authors = [
+    { name = "Stellars Henson", email = "konrad.jelen+github@gmail.com" },
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["copier", "template", "scaffolding", "questionnaire", "ui"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Code Generators",
+]
+
+dependencies = [
+    "copier>=9.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/stellarshenson/copier-tui"
+Repository = "https://github.com/stellarshenson/copier-tui"
+Issues = "https://github.com/stellarshenson/copier-tui/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["copier_ui*"]

copier_ui-0.6.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

copier_ui-0.6.8/src/copier_ui/__init__.py

@@ -0,0 +1,37 @@
+"""UI-neutral abstraction over a copier template survey."""
+
+from copier_ui.api import TemplateUI
+from copier_ui.errors import (
+    CircularDependencyError,
+    CopierUIError,
+    RenderRefusedError,
+    TemplateLoadError,
+    UnknownFieldError,
+)
+from copier_ui.model import (
+    Choice,
+    Evaluation,
+    FieldState,
+    Kind,
+    Operation,
+    Question,
+    Schema,
+    State,
+)
+
+__all__ = [
+    "Choice",
+    "CircularDependencyError",
+    "CopierUIError",
+    "Evaluation",
+    "FieldState",
+    "Kind",
+    "Operation",
+    "Question",
+    "RenderRefusedError",
+    "Schema",
+    "State",
+    "TemplateLoadError",
+    "TemplateUI",
+    "UnknownFieldError",
+]

copier_ui-0.6.8/src/copier_ui/adapter.py

@@ -0,0 +1,314 @@
+"""Copier-facing layer.
+
+This is the ONLY module in copier_ui or copier_tui allowed to import copier. Everything it
+uses beyond `run_copy`, `run_recopy`, `run_update` and `Phase` is a copier internal that may
+move between copier releases; copier 9.17.2 is the version this was written against. Nothing
+outside this module may import `copier`.
+
+Internals to use, all documented in docs/design-notes.md:
+
+- `copier._main.Worker` - constructed, never run; owns the fetch, the Jinja env and the context
+- `Worker.template.questions_data`, `Worker.template.local_abspath`, `Worker.jinja_env`
+- `Worker.unsafe` and `Worker._check_unsafe(operation)` - the trust gate, config reads only,
+  called before `jinja_env` because that access imports every `_jinja_extensions` entry
+- `Worker.answers` (assign a fresh `copier._user_data.AnswersMap`) and `Worker._render_context()`
+- `copier._user_data.Question` - built fresh per evaluation; `_formatted_choices` is cached
+- `copier._types.MISSING` - the "no default" sentinel returned by `Question.get_default()`
+- `copier._subproject.Subproject.last_answers` - the destination's answers file
+- `copier.Phase.use(Phase.PROMPT)` - wraps every evaluation
+- `copier.run_copy` / `run_recopy` / `run_update` - the only public entry points
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+import re
+from typing import Any
+
+from copier import Phase, run_copy, run_recopy, run_update
+from copier._main import Worker
+from copier._types import MISSING
+from copier._user_data import AnswersMap
+from copier._user_data import Question as CopierQuestion
+from jinja2 import TemplateSyntaxError, meta
+
+from copier_ui.errors import TemplateLoadError
+from copier_ui.model import Choice, Evaluation, Kind, Operation, Question
+
+_KIND_BY_TYPE = {
+    "str": Kind.STRING,
+    "bool": Kind.BOOL,
+    "int": Kind.INTEGER,
+    "float": Kind.FLOAT,
+    "path": Kind.PATH,
+    "json": Kind.STRUCTURED,
+    "yaml": Kind.STRUCTURED,
+}
+
+
+class TemplateAdapter:
+    """Loads a copier template and evaluates its questions against an answer set."""
+
+    def __init__(self, worker: Worker, operation: Operation) -> None:
+        """Wrap a constructed but unrun copier Worker."""
+        self._worker = worker
+        self._operation = operation
+        self._questions: tuple[Question, ...] | None = None
+
+    @classmethod
+    def open(
+        cls,
+        src: str | Path | None,
+        dst: Path,
+        *,
+        vcs_ref: str | None = None,
+        answers_file: Path | None = None,
+        operation: Operation = "copy",
+        unsafe: bool = False,
+    ) -> TemplateAdapter:
+        """Fetch the template, gate its unsafe features, and check it carries a copier config."""
+        worker = Worker(
+            src_path=None if src is None else str(src),
+            dst_path=Path(dst),
+            vcs_ref=vcs_ref,
+            answers_file=answers_file,
+            unsafe=unsafe,
+        )
+        adapter = cls(worker, operation)
+        try:
+            root = worker.template.local_abspath
+            if not _config_paths(root):
+                raise TemplateLoadError(f"No copier configuration file in {root}")
+            worker._check_unsafe("update" if operation == "update" else "copy")
+            _ = worker.jinja_env
+            adapter.questions()
+        except TemplateLoadError:
+            worker._cleanup()
+            raise
+        except Exception as error:
+            worker._cleanup()
+            raise TemplateLoadError(str(error)) from error
+        return adapter
+
+    def questions(self) -> tuple[Question, ...]:
+        """Normalised questions in copier.yml declaration order."""
+        if self._questions is None:
+            self._questions = tuple(
+                self._normalise(id, details)
+                for id, details in self._worker.template.questions_data.items()
+            )
+        return self._questions
+
+    def last_answers(self) -> dict[str, Any]:
+        """The destination's answers file, with every underscore-prefixed key dropped."""
+        return {
+            key: value
+            for key, value in self._worker.subproject.last_answers.items()
+            if not key.startswith("_")
+        }
+
+    def evaluate(self, id: str, answers: Mapping[str, Any]) -> Evaluation:
+        """Resolve one question's visibility, default and choices against the given answers."""
+        load_error = self._load_error(id)
+        if load_error is not None:
+            return Evaluation(
+                visible=True, default=None, has_default=False, choices=(), error=load_error
+            )
+        details = dict(self._worker.template.questions_data[id], validator="")
+        with Phase.use(Phase.PROMPT):
+            try:
+                question = self._copier_question(id, answers, details)
+                visible = question.get_when()
+                choices = _choices_of(question)
+                default = question.get_default()
+            except Exception as error:  # noqa: BLE001 - a failed expression is a value here
+                return Evaluation(
+                    visible=True,
+                    default=None,
+                    has_default=False,
+                    choices=(),
+                    error=_redact(str(error), self.questions(), answers),
+                )
+        if default is MISSING:
+            return Evaluation(
+                visible=visible, default=None, has_default=False, choices=choices, error=None
+            )
+        return Evaluation(
+            visible=visible, default=default, has_default=True, choices=choices, error=None
+        )
+
+    def validate(self, id: str, value: Any, answers: Mapping[str, Any]) -> tuple[str, ...]:
+        """Coerce and validate one value, returning messages instead of raising."""
+        load_error = self._load_error(id)
+        if load_error is not None:
+            return (load_error,)
+        with Phase.use(Phase.PROMPT):
+            try:
+                question = self._copier_question(id, answers)
+                question.validate_answer(question.parse_answer(value))
+            except Exception as error:  # noqa: BLE001 - user input problems are values
+                return (_redact(str(error), self.questions(), answers),)
+        return ()
+
+    def run(self, dst: Path, data: Mapping[str, Any], **copier_kwargs: Any) -> None:
+        """Dispatch to run_copy, run_recopy or run_update with the answers as data."""
+        kwargs: dict[str, Any] = {
+            "vcs_ref": self._worker.vcs_ref,
+            "answers_file": self._worker.answers_file,
+            **copier_kwargs,
+        }
+        if self._operation == "copy":
+            run_copy(str(self._worker.template.url), dst, dict(data), **kwargs)
+        elif self._operation == "recopy":
+            run_recopy(dst, dict(data), **kwargs)
+        else:
+            run_update(dst, dict(data), **kwargs)
+
+    def close(self) -> None:
+        """Drop the template's temporary clone."""
+        self._worker._cleanup()
+
+    def _copier_question(
+        self,
+        id: str,
+        answers: Mapping[str, Any],
+        details: Mapping[str, Any] | None = None,
+    ) -> CopierQuestion:
+        """Build a fresh copier Question bound to a render context for these answers."""
+        if details is None:
+            details = self._worker.template.questions_data[id]
+        self._worker.answers = AnswersMap(user=dict(answers))
+        return CopierQuestion(
+            var_name=id,
+            answers=self._worker.answers,
+            context=self._worker._render_context(),
+            jinja_env=self._worker.jinja_env,
+            settings=self._worker.settings,
+            **details,
+        )
+
+    def _load_error(self, id: str) -> str | None:
+        """The load error of a question, or None when it was normalised cleanly."""
+        for question in self.questions():
+            if question.id == id:
+                return question.load_error
+        return None
+
+    def _normalise(self, id: str, details: Mapping[str, Any]) -> Question:
+        """Turn one raw copier.yml question block into a model Question."""
+        try:
+            with Phase.use(Phase.PROMPT):
+                question = self._copier_question(id, {}, details)
+                kind = _kind_of(
+                    question.get_type_name(),
+                    choices=bool(question.choices),
+                    multiselect=question.multiselect,
+                    secret=question.secret,
+                )
+                multiline = question.get_multiline()
+                placeholder = question.get_placeholder()
+        except Exception as error:  # noqa: BLE001 - a broken question is reported, not raised
+            return Question(
+                id=id,
+                kind=Kind.STRING,
+                label=id,
+                help="",
+                secret=False,
+                multiselect=False,
+                multiline=False,
+                placeholder="",
+                default_source=None,
+                choices_source=None,
+                when_source=True,
+                validator_source="",
+                dependencies=(),
+                load_error=f"{id}: {error}",
+            )
+        return Question(
+            id=id,
+            kind=kind,
+            label=id,
+            help=str(details.get("help", "")),
+            secret=question.secret,
+            multiselect=question.multiselect,
+            multiline=multiline,
+            placeholder=placeholder,
+            default_source=None if question.secret else details.get("default"),
+            choices_source=details.get("choices"),
+            when_source=details.get("when", True),
+            validator_source=str(details.get("validator", "")),
+            dependencies=tuple(
+                dependency
+                for dependency in self._dependencies(
+                    details.get("when"), details.get("default"), details.get("choices")
+                )
+                if dependency != id
+            ),
+            load_error=None,
+        )
+
+    def _dependencies(self, *sources: Any) -> tuple[str, ...]:
+        """Question ids referenced by the given Jinja sources, via jinja2.meta over the AST."""
+        ids = set(self._worker.template.questions_data)
+        found: set[str] = set()
+        for source in _templates(sources):
+            try:
+                ast = self._worker.jinja_env.parse(source)
+            except TemplateSyntaxError:
+                continue
+            found |= meta.find_undeclared_variables(ast) & ids
+        return tuple(sorted(found))
+
+
+def _redact(message: str, questions: tuple[Question, ...], answers: Mapping[str, Any]) -> str:
+    """Replace every secret answer's string form in a message with three asterisks."""
+    for question in questions:
+        if question.secret:
+            secret = str(answers.get(question.id, ""))
+            if secret:
+                message = message.replace(secret, "***")
+    return message
+
+
+def _config_paths(root: Path) -> list[Path]:
+    """The template's copier.yml / copier.yaml files, matching copier's own glob."""
+    return [
+        path
+        for path in root.glob("copier.*")
+        if path.is_file() and re.match(r"\.ya?ml", path.suffix, re.IGNORECASE)
+    ]
+
+
+def _templates(source: Any) -> Iterator[str]:
+    """Every string inside a raw copier.yml value, however deeply nested."""
+    if isinstance(source, str):
+        yield source
+    elif isinstance(source, Mapping):
+        for key, value in source.items():
+            yield from _templates(key)
+            yield from _templates(value)
+    elif isinstance(source, (list, tuple)):
+        for item in source:
+            yield from _templates(item)
+
+
+def _kind_of(type_name: str, *, choices: bool, multiselect: bool, secret: bool) -> Kind:
+    """Map a copier type name plus its modifiers to exactly one Kind."""
+    if multiselect:
+        return Kind.MULTISELECT
+    if choices:
+        return Kind.CHOICE
+    if secret:
+        return Kind.SECRET
+    return _KIND_BY_TYPE[type_name]
+
+
+def _choices_of(question: CopierQuestion) -> tuple[Choice, ...]:
+    """Render copier's formatted choices into ordered label/value pairs."""
+    if not question.choices:
+        return ()
+    return tuple(
+        Choice(label=str(choice.title), value=choice.value)
+        for choice in question._formatted_choices
+    )

copier_ui-0.6.8/src/copier_ui/api.py

@@ -0,0 +1,137 @@
+"""TemplateUI, the synchronous facade every frontend talks to."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+from copier_ui.adapter import TemplateAdapter
+from copier_ui.engine import compute_state, evaluation_order, validate_state, visible_answers
+from copier_ui.errors import RenderRefusedError
+from copier_ui.model import Operation, Schema, State
+
+
+class TemplateUI:
+    """A loaded template, its schema, its answers and its state."""
+
+    def __init__(
+        self,
+        adapter: TemplateAdapter,
+        schema: Schema,
+        order: tuple[str, ...],
+        dst: Path,
+    ) -> None:
+        """Hold the adapter, the schema and the evaluation order; start with no answers."""
+        self._adapter = adapter
+        self._schema = schema
+        self._order = order
+        self._dst = dst
+        self._explicit: dict[str, Any] = {}
+        self._preset: set[str] = set()
+        self._extra: dict[str, Any] = {}
+        self._state = compute_state(schema, order, {}, frozenset(), adapter.evaluate)
+
+    @classmethod
+    def from_template(
+        cls,
+        src: str | Path | None,
+        *,
+        dst: str | Path = ".",
+        operation: Operation = "copy",
+        vcs_ref: str | None = None,
+        answers_file: str | Path | None = None,
+        data: Mapping[str, Any] | None = None,
+        unsafe: bool = False,
+    ) -> TemplateUI:
+        """Load a local path or git URL, seed answers, and compute the first state.
+
+        A template declaring `_jinja_extensions` or `_tasks` is refused with a
+        `TemplateLoadError` unless `unsafe` is true or the template is trusted in copier's own
+        settings, matching what plain copier does before it imports anything.
+        """
+        adapter = TemplateAdapter.open(
+            src,
+            Path(dst),
+            vcs_ref=vcs_ref,
+            answers_file=None if answers_file is None else Path(answers_file),
+            operation=operation,
+            unsafe=unsafe,
+        )
+        try:
+            schema = Schema(questions=adapter.questions())
+            ui = cls(adapter, schema, evaluation_order(schema), Path(dst))
+            ids = schema.ids()
+            if operation in ("update", "recopy"):
+                for id, value in adapter.last_answers().items():
+                    if id in ids:
+                        ui._explicit[id] = value
+            for id, value in (data or {}).items():
+                if id in ids:
+                    ui._explicit[id] = value
+                    ui._preset.add(id)
+                else:
+                    ui._extra[id] = value
+            ui._recompute()
+        except Exception:
+            adapter.close()
+            raise
+        return ui
+
+    def schema(self) -> Schema:
+        """The ordered questions."""
+        return self._schema
+
+    def set(self, id: str, value: Any) -> None:
+        """Record an explicit answer and recompute; raises UnknownFieldError on an unknown id."""
+        self._schema.by_id(id)
+        self._explicit[id] = value
+        self._recompute()
+
+    def state(self) -> State:
+        """The current field state."""
+        return self._state
+
+    def answers(self) -> dict[str, Any]:
+        """Visible answers, JSON-compatible, ready to hand to copier as data."""
+        return visible_answers(self._state)
+
+    def validate(self) -> dict[str, list[str]]:
+        """Per-field error messages; an empty dict means valid."""
+        return validate_state(self._schema, self._state, self._adapter.validate)
+
+    def render(self, dst: str | Path | None = None, **copier_kwargs: Any) -> None:
+        """Run copier with the current answers; raises RenderRefusedError when invalid."""
+        errors = self.validate()
+        if errors:
+            raise RenderRefusedError(errors)
+        target = self._dst if dst is None else Path(dst)
+        self._adapter.run(target, {**self._extra, **self.answers()}, **copier_kwargs)
+
+    def close(self) -> None:
+        """Release the template's temporary clone."""
+        self._adapter.close()
+
+    def __enter__(self) -> Self:
+        """Enter a context that closes the template on exit."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Close the template."""
+        self.close()
+
+    def _recompute(self) -> None:
+        """Re-evaluate visibility, defaults and choices for every question in one pass."""
+        self._state = compute_state(
+            self._schema,
+            self._order,
+            self._explicit,
+            self._preset,
+            self._adapter.evaluate,
+        )

copier_ui-0.6.8/src/copier_ui/engine.py

@@ -0,0 +1,124 @@
+"""State algorithms: evaluation order, state computation, validation, answer extraction.
+
+Pure functions over the model. Evaluation arrives as callables, so this module needs neither
+copier nor a template on disk.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+import heapq
+from typing import Any
+
+from copier_ui.errors import CircularDependencyError
+from copier_ui.model import Evaluator, FieldState, FieldValidator, Schema, State
+
+
+def evaluation_order(schema: Schema) -> tuple[str, ...]:
+    """Topological order of the dependency graph, ties broken by declaration order."""
+    ids = schema.ids()
+    index = {id: position for position, id in enumerate(ids)}
+    deps = {q.id: tuple(d for d in q.dependencies if d in index) for q in schema.questions}
+    dependents: dict[str, list[str]] = {id: [] for id in ids}
+    pending = {}
+    for id, sources in deps.items():
+        unique = set(sources)
+        pending[id] = len(unique)
+        for source in unique:
+            dependents[source].append(id)
+
+    ready = [index[id] for id, count in pending.items() if count == 0]
+    heapq.heapify(ready)
+    order: list[str] = []
+    while ready:
+        id = ids[heapq.heappop(ready)]
+        order.append(id)
+        for dependent in dependents[id]:
+            pending[dependent] -= 1
+            if pending[dependent] == 0:
+                heapq.heappush(ready, index[dependent])
+
+    if len(order) < len(ids):
+        stuck = {id for id in ids if pending[id] > 0}
+        raise CircularDependencyError(_find_cycle(ids, deps, stuck))
+    return tuple(order)
+
+
+def _find_cycle(
+    ids: Sequence[str],
+    deps: Mapping[str, Sequence[str]],
+    stuck: AbstractSet[str],
+) -> tuple[str, ...]:
+    """Walk the unresolved questions until one repeats, and return that cycle."""
+    path: list[str] = []
+    seen: dict[str, int] = {}
+    id = next(candidate for candidate in ids if candidate in stuck)
+    while id not in seen:
+        seen[id] = len(path)
+        path.append(id)
+        id = next(dep for dep in deps[id] if dep in stuck)
+    return tuple(path[seen[id] :])
+
+
+def compute_state(
+    schema: Schema,
+    order: Sequence[str],
+    explicit: Mapping[str, Any],
+    preset: AbstractSet[str],
+    evaluate: Evaluator,
+) -> State:
+    """Evaluate every question once, threading each resolved value into the next evaluation."""
+    answers: dict[str, Any] = {}
+    resolved: dict[str, FieldState] = {}
+    for id in order:
+        question = schema.by_id(id)
+        evaluation = evaluate(id, answers)
+        if id in explicit:
+            value = explicit[id]
+            is_default = False
+        else:
+            value = evaluation.default if evaluation.has_default else None
+            is_default = True
+        answers[id] = value
+        resolved[id] = FieldState(
+            id=id,
+            value=value,
+            visible=evaluation.visible,
+            enabled=question.load_error is None and evaluation.error is None,
+            is_default=is_default,
+            preset=id in preset,
+            secret=question.secret,
+            choices=evaluation.choices,
+            errors=() if evaluation.error is None else (evaluation.error,),
+        )
+
+    fields = {id: resolved[id] for id in schema.ids()}
+    return State(
+        fields=fields,
+        visible_ids=tuple(id for id, field in fields.items() if field.visible),
+    )
+
+
+def validate_state(
+    schema: Schema,
+    state: State,
+    validate_field: FieldValidator,
+) -> dict[str, list[str]]:
+    """Per-field error messages for visible fields; an empty dict means valid."""
+    answers = {id: field.value for id, field in state.fields.items()}
+    errors: dict[str, list[str]] = {}
+    for id in state.visible_ids:
+        field = state.fields[id]
+        if not field.enabled:
+            errors[id] = list(field.errors)
+            continue
+        messages = list(field.errors) + list(validate_field(id, field.value, answers))
+        if messages:
+            errors[id] = messages
+    return errors
+
+
+def visible_answers(state: State) -> dict[str, Any]:
+    """Answers of visible fields only, JSON-compatible."""
+    return {id: state.fields[id].value for id in state.visible_ids}

copier_ui-0.6.8/src/copier_ui/errors.py

@@ -0,0 +1,33 @@
+"""Exception hierarchy for copier_ui."""
+
+from __future__ import annotations
+
+
+class CopierUIError(Exception):
+    """Base class for every copier_ui error."""
+
+
+class TemplateLoadError(CopierUIError):
+    """The template could not be fetched, or its configuration could not be read."""
+
+
+class CircularDependencyError(TemplateLoadError):
+    """Question expressions form a dependency cycle."""
+
+    def __init__(self, cycle: tuple[str, ...]) -> None:
+        """Record the ids taking part in the cycle."""
+        super().__init__("Circular dependency between questions: " + " -> ".join(cycle))
+        self.cycle = cycle
+
+
+class UnknownFieldError(CopierUIError, KeyError):
+    """A question id that is not in the schema."""
+
+
+class RenderRefusedError(CopierUIError):
+    """Rendering was refused because the state has validation errors."""
+
+    def __init__(self, errors: dict[str, list[str]]) -> None:
+        """Record the per-field error messages that blocked the render."""
+        super().__init__("Invalid answers for: " + ", ".join(sorted(errors)))
+        self.errors = errors

copier_ui-0.6.8/src/copier_ui/model.py

@@ -0,0 +1,140 @@
+"""Frozen data model shared by every copier_ui layer and by any frontend."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Literal
+
+from copier_ui.errors import UnknownFieldError
+
+Operation = Literal["copy", "update", "recopy"]
+
+
+class Kind(StrEnum):
+    """The widget-selecting kind of a question."""
+
+    STRING = "string"
+    BOOL = "bool"
+    INTEGER = "integer"
+    FLOAT = "float"
+    PATH = "path"
+    STRUCTURED = "structured"
+    CHOICE = "choice"
+    MULTISELECT = "multiselect"
+    SECRET = "secret"
+
+
+@dataclass(frozen=True, slots=True)
+class Choice:
+    """One selectable option, in copier.yml order."""
+
+    label: str
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class Question:
+    """One normalised question: declared data only, independent of any answer."""
+
+    id: str
+    kind: Kind
+    label: str
+    help: str
+    secret: bool
+    multiselect: bool
+    multiline: bool
+    placeholder: str
+    default_source: Any
+    choices_source: Any
+    when_source: str | bool
+    validator_source: str
+    dependencies: tuple[str, ...]
+    load_error: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Schema:
+    """The template's questions in copier.yml declaration order."""
+
+    questions: tuple[Question, ...]
+
+    def ids(self) -> tuple[str, ...]:
+        """Question ids in declaration order."""
+        return tuple(question.id for question in self.questions)
+
+    def by_id(self, id: str) -> Question:
+        """Look a question up, raising UnknownFieldError when it is absent."""
+        for question in self.questions:
+            if question.id == id:
+                return question
+        raise UnknownFieldError(id)
+
+
+@dataclass(frozen=True, slots=True)
+class Evaluation:
+    """One question resolved against one answer set."""
+
+    visible: bool
+    default: Any
+    has_default: bool
+    choices: tuple[Choice, ...]
+    error: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class FieldState:
+    """One question's live state."""
+
+    id: str
+    value: Any
+    visible: bool
+    enabled: bool
+    is_default: bool
+    preset: bool
+    secret: bool
+    choices: tuple[Choice, ...]
+    errors: tuple[str, ...]
+
+    def __repr__(self) -> str:
+        """Render the state, masking the value of a secret field."""
+        value = "'***'" if self.secret else repr(self.value)
+        return (
+            f"FieldState(id={self.id!r}, value={value}, visible={self.visible}, "
+            f"enabled={self.enabled}, is_default={self.is_default}, preset={self.preset}, "
+            f"secret={self.secret}, choices={self.choices!r}, errors={self.errors!r})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class State:
+    """The whole survey's live state."""
+
+    fields: Mapping[str, FieldState]
+    visible_ids: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON-compatible dump with secret values replaced by None."""
+        return {
+            "fields": {
+                id: {
+                    "value": None if field.secret else field.value,
+                    "visible": field.visible,
+                    "enabled": field.enabled,
+                    "is_default": field.is_default,
+                    "preset": field.preset,
+                    "secret": field.secret,
+                    "choices": [
+                        {"label": choice.label, "value": choice.value} for choice in field.choices
+                    ],
+                    "errors": list(field.errors),
+                }
+                for id, field in self.fields.items()
+            },
+            "visible_ids": list(self.visible_ids),
+        }
+
+
+Evaluator = Callable[[str, Mapping[str, Any]], Evaluation]
+FieldValidator = Callable[[str, Any, Mapping[str, Any]], tuple[str, ...]]

copier_ui-0.6.8/src/copier_ui.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: copier-ui
+Version: 0.6.8
+Summary: UI-neutral abstraction over a copier template survey: normalised schema, dependency graph, visibility and validation
+Author-email: Stellars Henson <konrad.jelen+github@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/stellarshenson/copier-tui
+Project-URL: Repository, https://github.com/stellarshenson/copier-tui
+Project-URL: Issues, https://github.com/stellarshenson/copier-tui/issues
+Keywords: copier,template,scaffolding,questionnaire,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: copier>=9.6
+
+# copier-ui
+
+UI-neutral abstraction over a [copier](https://copier.readthedocs.io) template survey.
+
+`copier-ui` reads a template's questions and turns them into a normalised schema with a
+dependency graph, visibility state and validation. It owns semantics and renders nothing, so
+the same core drives a terminal UI, a web UI, an HTTP API or a test.
+
+It never imports a display library and never requires an event loop.
+
+```python
+from copier_ui import TemplateUI
+
+# unsafe=True is copier's own trust gate: this template declares Jinja extensions and tasks,
+# and copier_ui refuses to load such a template before importing anything unless you say so
+ui = TemplateUI.from_template("gh:stellarshenson/copier-data-science", unsafe=True)
+ui.set("dataset_storage", "s3")
+ui.state().fields["s3_bucket"].visible   # True
+ui.render("./my-project")
+```
+
+Part of the [copier-tui](https://github.com/stellarshenson/copier-tui) project.

copier_ui-0.6.8/src/copier_ui.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/copier_ui/__init__.py
+src/copier_ui/adapter.py
+src/copier_ui/api.py
+src/copier_ui/engine.py
+src/copier_ui/errors.py
+src/copier_ui/model.py
+src/copier_ui.egg-info/PKG-INFO
+src/copier_ui.egg-info/SOURCES.txt
+src/copier_ui.egg-info/dependency_links.txt
+src/copier_ui.egg-info/requires.txt
+src/copier_ui.egg-info/top_level.txt

copier_ui-0.6.8/src/copier_ui.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

copier_ui-0.6.8/src/copier_ui.egg-info/requires.txt

@@ -0,0 +1 @@
+copier>=9.6

copier_ui-0.6.8/src/copier_ui.egg-info/top_level.txt

@@ -0,0 +1 @@
+copier_ui