schemify-cli 0.1.0__py3-none-any.whl

schemify/fillers.py

@@ -0,0 +1,272 @@
+"""Data fillers: ask the user for a value matching a JSON Schema, picked by the schema kind.
+
+The kind is `enum` when the schema has choices, else its `format` when a filler is
+registered for it (`date`, `date-time`), else its `type`.
+
+A schema `default` is offered as the answer of a text, boolean or enum prompt.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+import questionary
+
+from .computers import KEYWORD, ComputeError, compute
+from .models import Schema
+from .registry import NotSupportedError, Registry
+from .validators import Parser, check_value, to_date, to_datetime, to_int, to_number
+
+type FillFn = Callable[[Schema, str, bool], Any]
+"""Asks for a value of a sub-schema, given its label and whether it is required.
+
+An optional value the user skips is returned as `MISSING`.
+"""
+
+MISSING: Any = object()
+"""Returned by a filler when the user skips an optional value."""
+
+fillers = Registry[FillFn]("Schema kind")
+"""The default registry, used by `ask_data`."""
+
+
+class InvalidDataError(Exception):
+    """Raised when the entered data does not match the whole schema.
+
+    Each value is checked as it is entered, this catches the keywords
+    no filler asks about (like `allOf` or `dependentRequired`).
+    """
+
+
+def ask_data(schema: Schema) -> Any:
+    """Ask the user for data matching `schema`, usually an object, and return it.
+
+    The `x-compute` properties are not asked, they are computed once the data is entered.
+
+    Raises:
+        NotSupportedError: A part of the schema has no filler (like `$ref` or `oneOf`),
+            or a computed property names an unknown computer.
+        InvalidDataError: A property can not be computed,
+            or the data does not match the whole schema.
+
+    """
+    data = fill(schema, "")
+
+    try:
+        compute(schema, data)
+    except ComputeError as e:
+        raise InvalidDataError(e) from e
+    error = check_value(schema, data)
+
+    if error is not None:
+        raise InvalidDataError(error)
+
+    return data
+
+
+def ask_list(schema: Schema) -> list[Any]:
+    """Ask for items matching `schema` until the user stops, at least one, and return them.
+
+    Each item is asked, computed and checked like `ask_data`, so `$.` paths point to the item.
+
+    Raises:
+        NotSupportedError: A part of the schema has no filler, or names an unknown computer.
+        InvalidDataError: An item can not be computed, or does not match the whole schema.
+
+    """
+    items: list[Any] = []
+
+    while True:
+        questionary.print(f"Item {len(items) + 1}", style="bold")
+        items.append(ask_data(schema))
+        questionary.print("")  # separate each item's questions from the next
+
+        if not questionary.confirm(
+            f"Add another item? ({len(items)} so far)", default=True
+        ).unsafe_ask():
+            return items
+
+
+def kind(schema: Schema) -> str:
+    """Return the filler name of `schema`: `enum`, a registered `format`, or its `type`."""
+    if "enum" in schema:
+        return "enum"
+
+    if schema.get("format") in fillers:
+        return schema["format"]
+
+    return str(schema.get("type"))
+
+
+def fill(schema: Schema, label: str, *, required: bool = True) -> Any:
+    """Ask for a value of `schema` with the filler matching its kind.
+
+    Raises:
+        NotSupportedError: No filler matches the schema kind.
+
+    """
+    try:
+        fill_fn = fillers[kind(schema)]
+    except NotSupportedError as e:
+        message = f"Can not fill '{label or 'data'}': {e}"
+        raise NotSupportedError(message) from e
+
+    return fill_fn(schema, label, required)
+
+
+# -----------------------
+# utils
+# -----------------------
+
+
+def _name(schema: Schema, label: str) -> str:
+    """Return the schema `title` when it has one, else the property path."""
+    return schema.get("title") or label
+
+
+def _message(schema: Schema, label: str) -> str:
+    name = _name(schema, label)
+    description = schema.get("description")
+
+    return f"{name} ({description}):" if description else f"{name}:"
+
+
+def _skipped(schema: Schema, label: str, *, required: bool) -> bool:
+    """Ask whether to add an optional value, `False` for required values."""
+    if required:
+        return False
+
+    return not questionary.confirm(f"Add '{_name(schema, label)}'?", default=True).unsafe_ask()
+
+
+# -----------------------
+# typed text
+# -----------------------
+
+
+def _text_filler(parse: Parser) -> FillFn:
+    """Build a filler asking a text answer, parsed then checked against the schema."""
+
+    def fill_text(schema: Schema, label: str, required: bool) -> Any:  # noqa: FBT001
+        def validate(text: str) -> bool | str:
+            if not required and not text.strip():
+                return True
+
+            try:
+                value = parse(text)
+            except ValueError as e:
+                return str(e)
+
+            error = check_value(schema, value)
+
+            return error is None or error
+
+        default = str(schema["default"]) if "default" in schema else ""
+        answer = questionary.text(
+            _message(schema, label), default=default, validate=validate
+        ).unsafe_ask()
+
+        if not required and not answer.strip():
+            return MISSING
+
+        return parse(answer)
+
+    return fill_text
+
+
+fillers.add(_text_filler(str), "string")
+fillers.add(_text_filler(to_int), "integer")
+fillers.add(_text_filler(to_number), "number")
+fillers.add(_text_filler(to_date), "date")
+fillers.add(_text_filler(to_datetime), "date-time")
+
+
+# -----------------------
+# choices
+# -----------------------
+
+
+@fillers.register("boolean")
+def fill_boolean(schema: Schema, label: str, required: bool) -> Any:  # noqa: FBT001
+    """Ask yes / no."""
+    if _skipped(schema, label, required=required):
+        return MISSING
+
+    default = schema.get("default") is True
+
+    return questionary.confirm(_message(schema, label), default=default).unsafe_ask()
+
+
+@fillers.register("enum")
+def fill_enum(schema: Schema, label: str, required: bool) -> Any:  # noqa: FBT001
+    """Ask to pick one of the `enum` choices, they can be any JSON value."""
+    if _skipped(schema, label, required=required):
+        return MISSING
+
+    choices = {str(choice): choice for choice in schema["enum"]}
+    default = str(schema["default"]) if schema.get("default") in schema["enum"] else None
+    answer = questionary.select(
+        _message(schema, label), choices=list(choices), default=default
+    ).unsafe_ask()
+
+    return choices[answer]
+
+
+# -----------------------
+# containers
+# -----------------------
+
+
+@fillers.register("array")
+def fill_array(schema: Schema, label: str, required: bool) -> Any:  # noqa: FBT001
+    """Ask items until the user stops, respecting `minItems`, `maxItems` and `uniqueItems`.
+
+    shortcut: a `default` of the whole array is not offered, its items are asked one by one.
+    """
+    if _skipped(schema, label, required=required):
+        return MISSING
+
+    items_schema = schema.get("items", {})
+    min_items = schema.get("minItems", 0)
+    max_items = schema.get("maxItems")
+    items: list[Any] = []
+
+    while max_items is None or len(items) < max_items:
+        if (
+            len(items) >= min_items
+            and not questionary.confirm(
+                f"Add an item to '{_name(schema, label)}'?", default=True
+            ).unsafe_ask()
+        ):
+            break
+
+        item = fill(items_schema, f"{label}[{len(items)}]")
+
+        if schema.get("uniqueItems") and item in items:
+            questionary.print(f"{item!r} is already in '{_name(schema, label)}'", style="fg:red")
+            continue
+
+        items.append(item)
+
+    return items
+
+
+@fillers.register("object")
+def fill_object(schema: Schema, label: str, required: bool) -> Any:  # noqa: FBT001
+    """Ask each property in order, optional ones can be skipped, computed ones are not asked."""
+    if _skipped(schema, label, required=required):
+        return MISSING
+
+    required_names = set(schema.get("required", []))
+    data: dict[str, Any] = {}
+
+    for name, property_schema in schema.get("properties", {}).items():
+        if KEYWORD in property_schema:
+            continue
+
+        path = f"{label}.{name}" if label else name
+        value = fill(property_schema, path, required=name in required_names)
+
+        if value is not MISSING:
+            data[name] = value
+
+    return data

schemify/formatters.py

@@ -0,0 +1,66 @@
+"""Data formatters: turn filled data into source text, picked by format name.
+
+Each format name is also its pygments lexer name, used to highlight the printed output.
+"""
+
+import json
+import pprint
+import re
+from collections.abc import Callable
+from typing import Any
+
+from .registry import Registry
+
+type FormatFn = Callable[[Any], str]
+
+formatters = Registry[FormatFn]("Format")
+"""The default registry, used by the `fill --format` option."""
+
+
+@formatters.register("json")
+def to_json(data: Any) -> str:
+    """Format as indented JSON, keeping non-ASCII characters."""
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+@formatters.register("python")
+def to_python(data: Any) -> str:
+    """Format as a Python literal: `{'done': True, 'note': None}`."""
+    return pprint.pformat(data, sort_dicts=False)
+
+
+@formatters.register("javascript")
+def to_javascript(data: Any) -> str:
+    """Format as a JavaScript object literal, quoting only the keys that need it."""
+    return _javascript(data, 0)
+
+
+# -----------------------
+# utils
+# -----------------------
+
+_JS_IDENTIFIER = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+
+
+def _javascript_key(key: str) -> str:
+    return key if _JS_IDENTIFIER.fullmatch(key) else json.dumps(key, ensure_ascii=False)
+
+
+def _javascript(value: Any, level: int) -> str:
+    indent = "  " * (level + 1)
+    closing_indent = "  " * level
+
+    if isinstance(value, dict) and value:
+        lines = [
+            f"{indent}{_javascript_key(k)}: {_javascript(v, level + 1)}" for k, v in value.items()
+        ]
+
+        return "{\n" + ",\n".join(lines) + f"\n{closing_indent}}}"
+
+    if isinstance(value, list) and value:
+        lines = [f"{indent}{_javascript(item, level + 1)}" for item in value]
+
+        return "[\n" + ",\n".join(lines) + f"\n{closing_indent}]"
+
+    # scalars, `{}` and `[]`: JSON is valid JavaScript
+    return json.dumps(value, ensure_ascii=False)

schemify/generators.py

@@ -0,0 +1,323 @@
+"""Schema generators: ask the user about a type and return its JSON Schema, picked by type name."""
+
+import inspect
+import json
+from collections.abc import Callable, Sequence
+from typing import Any, get_origin
+
+import questionary
+
+from .computers import KEYWORD, computers, groups
+from .models import Schema
+from .registry import Registry
+from .validators import (
+    ARRAY_CONSTRAINTS,
+    NUMBER_CONSTRAINTS,
+    STRING_CONSTRAINTS,
+    Constraint,
+    default_parser,
+    is_choice,
+    is_property_name,
+    optional,
+    validator,
+    within_bounds,
+)
+
+type GenerateFn = Callable[[], Schema]
+
+SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+generators = Registry[GenerateFn]("Type")
+"""The default registry, every registered type is offered in the type prompts."""
+
+
+def ask_schema(title: str | None = None) -> Schema:
+    """Ask the user for the properties of an object and return its JSON Schema."""
+    header = {"$schema": SCHEMA_DIALECT, "title": title} if title else {"$schema": SCHEMA_DIALECT}
+
+    return {**header, **generators["object"]()}
+
+
+# -----------------------
+# utils
+# -----------------------
+
+
+def _ask_type(message: str, extra: Sequence[str] = ()) -> str:
+    choices = [*generators.names, *extra]
+
+    return questionary.select(message, choices=choices, default="string").unsafe_ask()
+
+
+def _wants_validators() -> bool:
+    return questionary.confirm("Add validators?", default=False).unsafe_ask()
+
+
+def _ask_constraints(constraints: list[Constraint]) -> Schema:
+    """Ask each constraint, an empty answer skips it, a conflicting bound is asked again."""
+    schema: Schema = {}
+
+    for constraint in constraints:
+        keyword, question, parse, _ = constraint
+        answer = questionary.text(
+            f"{question} (optional):", validate=optional(within_bounds(schema, constraint))
+        ).unsafe_ask()
+
+        if answer.strip():
+            schema[keyword] = parse(answer)
+
+    return schema
+
+
+# -----------------------
+# primitive types
+# -----------------------
+
+
+@generators.register("string")
+def generate_string() -> Schema:
+    """Ask for a string: format (email, uuid), digits only, length, pattern, blocked values."""
+    schema: Schema = {"type": "string"}
+
+    if not _wants_validators():
+        return schema
+
+    string_format = questionary.select("Format:", choices=["none", "email", "uuid"]).unsafe_ask()
+
+    if string_format != "none":
+        return {**schema, "format": string_format}
+
+    constraints = STRING_CONSTRAINTS
+
+    if questionary.confirm("Digits only?", default=False).unsafe_ask():
+        schema["pattern"] = r"^\d+$"
+        constraints = [c for c in STRING_CONSTRAINTS if c[0] != "pattern"]
+
+    return {**schema, **_ask_constraints(constraints)}
+
+
+def _number_generator(number_type: str) -> GenerateFn:
+    def generate() -> Schema:
+        """Ask for an integer or a number: bounds and a multiple."""
+        schema: Schema = {"type": number_type}
+
+        if not _wants_validators():
+            return schema
+
+        return {**schema, **_ask_constraints(NUMBER_CONSTRAINTS)}
+
+    return generate
+
+
+generators.add(_number_generator("integer"), "integer")
+generators.add(_number_generator("number"), "number")
+
+
+@generators.register("boolean")
+def generate_boolean() -> Schema:
+    """Return a boolean."""
+    return {"type": "boolean"}
+
+
+@generators.register("date")
+def generate_date() -> Schema:
+    """Return an ISO date string: `2026-11-04`."""
+    return {"type": "string", "format": "date"}
+
+
+@generators.register("datetime")
+def generate_datetime() -> Schema:
+    """Return an RFC 3339 datetime string: `2026-11-04T10:30:00+03:00`."""
+    return {"type": "string", "format": "date-time"}
+
+
+@generators.register("enum")
+def generate_enum() -> Schema:
+    """Ask for a string limited to choices, one per prompt."""
+    choices: list[str] = []
+
+    while choice := (
+        questionary.text("Choice (empty to finish):", validate=is_choice(choices))
+        .unsafe_ask()
+        .strip()
+    ):
+        choices.append(choice)
+
+    return {"type": "string", "enum": choices}
+
+
+# -----------------------
+# container types
+# -----------------------
+
+
+@generators.register("array")
+def generate_array() -> Schema:
+    """Ask for a list of items of one type: size and unique items."""
+    items = generators[_ask_type("Items type:")]()
+    schema: Schema = {"type": "array", "items": items}
+
+    if not _wants_validators():
+        return schema
+
+    schema = {**schema, **_ask_constraints(ARRAY_CONSTRAINTS)}
+
+    if questionary.confirm("Unique items?", default=False).unsafe_ask():
+        schema["uniqueItems"] = True
+
+    return schema
+
+
+@generators.register("object")
+def generate_object() -> Schema:
+    """Ask for an object: each property name, type, label, description, default, and if required.
+
+    The label is saved as the JSON Schema `title`, fillers show it instead of the property name.
+    """
+    properties: Schema = {}
+    required: list[str] = []
+
+    while (
+        name := questionary.text(
+            "Property name (empty to finish):", validate=is_property_name(properties)
+        )
+        .unsafe_ask()
+        .strip()
+    ):
+        # a computed property needs earlier properties to compute from
+        type_name = _ask_type(f"Type of '{name}':", ["computed"] if properties else [])
+        property_schema = (
+            _generate_computed(list(properties))
+            if type_name == "computed"
+            else generators[type_name]()
+        )
+        annotations = {
+            "title": questionary.text(f"Label shown instead of '{name}' when filling (optional):")
+            .unsafe_ask()
+            .strip(),
+            "description": questionary.text(f"Description of '{name}' (optional):")
+            .unsafe_ask()
+            .strip(),
+        }
+
+        properties[name] = {
+            **{keyword: value for keyword, value in annotations.items() if value},
+            **property_schema,
+        }
+
+        # a computed property sets its own `default` in `x-compute`
+        if type_name != "computed":
+            parse = default_parser(property_schema)
+            default = questionary.text(
+                f"Default value of '{name}' (optional):", validate=optional(validator(parse))
+            ).unsafe_ask()
+
+            if default.strip():
+                properties[name]["default"] = parse(default)
+
+        if questionary.confirm(f"Is '{name}' required?", default=True).unsafe_ask():
+            required.append(name)
+
+        questionary.print("")  # separate each property's questions from the next
+
+    schema: Schema = {"type": "object", "properties": properties}
+
+    if required:
+        schema["required"] = required
+
+    if not questionary.confirm("Allow extra properties?", default=False).unsafe_ask():
+        schema["additionalProperties"] = False
+
+    return schema
+
+
+def _to_options(text: str) -> dict[str, Any]:
+    """Parse computer options, a JSON object: `{"sep": ", "}`."""
+    try:
+        options = json.loads(text)
+    except json.JSONDecodeError as e:
+        message = f"Invalid JSON: {e.msg}"
+        raise ValueError(message) from None
+
+    if not isinstance(options, dict):
+        message = "Options must be a JSON object"
+        raise ValueError(message)  # noqa: TRY004 - prompt validators catch ValueError
+
+    return options
+
+
+def _computer_choices() -> list[str | questionary.Separator]:
+    """List the computers under a header per group, the ungrouped ones last under 'Other'."""
+    grouped = {name for names in groups.values() for name in names}
+    other = [name for name in computers.names if name not in grouped]
+    choices: list[str | questionary.Separator] = []
+
+    for group, names in {**groups, "Other": other}.items():
+        if names:
+            choices += [questionary.Separator(f"── {group} ──"), *names]
+
+    return choices
+
+
+_PLACEHOLDERS: dict[Any, Any] = {str: "text", int: 1, float: 1.5, bool: True, dict: {}, list: []}
+_JSON_TYPES = (str, int, float, bool, dict, list, type(None))
+
+
+def _options_example(fn: Callable[..., Any], sources: int) -> dict[str, Any] | None:
+    """Return example options of `fn` once `sources` values fill its first parameters.
+
+    An option with a default shows it, a required one a placeholder of its type.
+    `None` when `fn` takes no options.
+    """
+    example: dict[str, Any] = {}
+    takes_any = False
+
+    for param in inspect.signature(fn).parameters.values():
+        if param.kind is param.VAR_POSITIONAL:
+            sources = 0  # it takes the remaining sources
+        elif param.kind is param.VAR_KEYWORD:
+            takes_any = True
+        elif sources and param.kind is not param.KEYWORD_ONLY:
+            sources -= 1
+        elif param.default is not param.empty and isinstance(param.default, _JSON_TYPES):
+            example[param.name] = param.default
+        else:
+            kind = get_origin(param.annotation) or param.annotation  # `dict[str, Any]` -> `dict`
+            example[param.name] = _PLACEHOLDERS.get(kind, "value")
+
+    return example if example or takes_any else None
+
+
+def _describe(name: str, fn: Callable[..., Any]) -> None:
+    """Print the computer signature and summary, so the user knows its sources and options."""
+    summary = (inspect.getdoc(fn) or "").split("\n\n")[0]
+    questionary.print(f"{name}{inspect.signature(fn)}", style="bold")
+
+    if summary:
+        questionary.print(f"  {summary}", style="italic")
+
+
+def _generate_computed(names: list[str]) -> Schema:
+    """Ask how a property is computed from the earlier `names`, and the type of its result.
+
+    Keyword sources (`{"alias": "path"}`), `$.` / `[*]` paths and `default` are written by hand.
+    """
+    fn = questionary.select("Compute with:", choices=_computer_choices()).unsafe_ask()
+    _describe(fn, computers[fn])
+    sources = questionary.checkbox("Computed from (in order):", choices=names).unsafe_ask()
+    example = _options_example(computers[fn], len(sources))
+    spec: Schema = {"fn": fn}
+
+    if sources:
+        spec["from"] = sources
+
+    if example is not None:
+        hint = json.dumps(example, ensure_ascii=False)
+        options = questionary.text(
+            f"Options as JSON (optional), like {hint}:", validate=optional(validator(_to_options))
+        ).unsafe_ask()
+
+        if options.strip():
+            spec["options"] = _to_options(options)
+
+    return {**generators[_ask_type("Result type:")](), KEYWORD: spec}

schemify/models.py

@@ -0,0 +1,6 @@
+"""Types shared by generators, fillers and validators."""
+
+from typing import Any
+
+type Schema = dict[str, Any]
+"""A JSON Schema, or one of its sub-schemas."""