tina4-python 3.13.116__tar.gz → 3.13.118__tar.gz

{tina4_python-3.13.116 → tina4_python-3.13.118}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tina4-python
-Version: 3.13.116
+Version: 3.13.118
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.116 → tina4_python-3.13.118}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.116"
+version = "3.13.118"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.116 → tina4_python-3.13.118}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.116"
+    return "3.13.118"
 
 
 __version__ = _resolve_version()
@@ -221,3 +221,12 @@ def _preload_from_manifest() -> None:
 
 
 _preload_from_manifest()
+
+
+# ── Import-hint fallback (ADR-0062, agent-experience contract) ──
+# Registered LAST so Python's normal resolution runs first — this finder is
+# only consulted for `tina4_python.<X>` names that every other finder already
+# failed on, which is what keeps it from ever masking a legitimate ImportError
+# raised inside a module that DOES exist. See tina4_python/_import_helper.py.
+from tina4_python._import_helper import install as _install_import_helper  # noqa: E402
+_install_import_helper()

tina4_python-3.13.118/tina4_python/_import_helper.py

@@ -0,0 +1,140 @@
+"""
+tina4_python._import_helper — turn a wrong `tina4_python.<X>` import into a
+helpful ModuleNotFoundError that names the closest real module in the tree.
+
+The finder registers LAST on sys.meta_path, so Python's normal resolution runs
+first. We're only consulted for names that all other finders already gave up
+on — which means we never mask a legitimate ImportError raised deeper inside
+a module that DOES exist. If we're being asked, the module truly does not
+exist under this name.
+
+The suggestion is derived from the REAL installed tree, read from DISK, so a
+rename in the framework updates the hint automatically. There is no
+hand-maintained wrong-guess list.
+
+The tree is enumerated with the filesystem rather than pkgutil.walk_packages()
+on purpose: walk_packages IMPORTS every package it descends into, because
+recursing needs each package's __path__. Doing that here — from
+tina4_python/__init__.py at import time — has two effects, and both are bugs:
+it defeats the lazy subsystem loading, and it binds every subpackage as an
+attribute on tina4_python, which shadows the callables __getattr__ exists to
+provide. That second one is why `realtime` resolved to a module and stopped
+being callable. See tests/test_import_helper_does_not_import_the_tree.py.
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+import sys
+from pathlib import Path
+from difflib import get_close_matches
+from importlib.abc import MetaPathFinder
+from typing import Sequence
+
+
+_PREFIX = "tina4_python."
+
+
+class _Tina4ModuleFinder(MetaPathFinder):
+    """Last-resort finder that turns tina4_python.X misses into hints."""
+
+    def __init__(self) -> None:
+        # Snapshot the tree once at install time. If a plugin registers a new
+        # submodule after install, that plugin's own module load succeeds via
+        # the normal finders BEFORE we're consulted, so the snapshot only
+        # matters for the "did-you-mean" list. A missing plugin module still
+        # produces a helpful hint, just without the plugin's name in it.
+        self._known: tuple[str, ...] = tuple(self._walk())
+
+    @staticmethod
+    def _walk() -> Sequence[str]:
+        try:
+            pkg = importlib.import_module("tina4_python")
+            names: list[str] = []
+            for root in pkg.__path__:
+                base = Path(root)
+                for path in base.rglob("*"):
+                    if path.name.startswith((".", "_")) and path.name != "__init__.py":
+                        continue
+                    if path.is_dir():
+                        if (path / "__init__.py").is_file():
+                            names.append(_PREFIX + ".".join(path.relative_to(base).parts))
+                    elif path.suffix == ".py" and path.name != "__init__.py":
+                        rel = path.relative_to(base).with_suffix("")
+                        names.append(_PREFIX + ".".join(rel.parts))
+            if names:
+                return sorted(set(names))
+            # Not a plain directory tree (zipimport, a namespace package): fall
+            # back to the non-importing pkgutil call. Top level only, but
+            # correct. Never walk_packages, which would import.
+            return sorted(
+                name for _, name, _ in pkgutil.iter_modules(pkg.__path__, prefix=_PREFIX)
+            )
+        except Exception:  # noqa: BLE001 — never let the helper break import
+            return ()
+
+    def find_spec(self, fullname, path, target=None):  # noqa: D401
+        # Only intervene for tina4_python.<X> — everything else defers to
+        # whatever finder comes next, but since we appended ourselves last
+        # and this call reached us, no next finder exists.
+        if not fullname.startswith(_PREFIX):
+            return None
+
+        # Compute the hint. Any failure here degrades to a plain
+        # ModuleNotFoundError rather than raising the helper's own bug.
+        try:
+            hint = self._hint(fullname)
+        except Exception:  # noqa: BLE001
+            hint = ""
+
+        message = f"No module named {fullname!r}"
+        if hint:
+            message = f"{message}. {hint}"
+        raise ModuleNotFoundError(message, name=fullname)
+
+    def _hint(self, fullname: str) -> str:
+        tail = fullname[len(_PREFIX):]
+        last = tail.rsplit(".", 1)[-1]
+
+        # 1) Exact-suffix match — e.g. miss "route" surfaces every real
+        #    module whose last component contains "route" ("core.router",
+        #    "routing_x", "route_helper"). Cheap and reads well.
+        suffix_matches = [
+            m for m in self._known
+            if m != fullname and last in m.rsplit(".", 1)[-1]
+        ]
+
+        # 2) Fuzzy fallback — Levenshtein-style close matches on the
+        #    FULL dotted name, so "tina4_python.route" surfaces
+        #    "tina4_python.core.router" even though "route" is not a
+        #    substring of "router".
+        fuzzy = get_close_matches(fullname, list(self._known), n=5, cutoff=0.55)
+
+        # Merge preserving order, cap at 5.
+        seen: set[str] = set()
+        merged: list[str] = []
+        for name in (*suffix_matches, *fuzzy):
+            if name in seen:
+                continue
+            seen.add(name)
+            merged.append(name)
+            if len(merged) >= 5:
+                break
+
+        if not merged:
+            return ""
+        if len(merged) == 1:
+            return f"Did you mean {merged[0]!r}?"
+        return "Did you mean one of: " + ", ".join(repr(m) for m in merged) + "?"
+
+
+_installed: bool = False
+
+
+def install() -> None:
+    """Idempotent: append the finder to sys.meta_path exactly once."""
+    global _installed
+    if _installed:
+        return
+    sys.meta_path.append(_Tina4ModuleFinder())
+    _installed = True

{tina4_python-3.13.116 → tina4_python-3.13.118}/tina4_python/cli/__init__.py

@@ -129,7 +129,7 @@ def _parse_flags(args: list[str]) -> tuple[dict, list[str]]:
     """Parse --key value and --flag from args. Returns (flags, positional)."""
     # Boolean-only flags that never take a value argument
     boolean_flags = {"no-browser", "no-reload", "no-kill", "production", "managed", "all", "clear",
-                     "json", "public", "no-migration", "once"}
+                     "json", "public", "no-migration", "once", "dry-run", "quote"}
 
     flags = {}
     positional = []
@@ -965,6 +965,254 @@ def _ai(args):
             install_selected(".", selection)
 
 
+# ── Generate resolution envelope (ADR-0062, agent-experience contract) ─────
+#
+# Every `generate model/route/migration/middleware` call ALSO exposes the
+# mapping the framework decided to build — the class name, the (maybe
+# pluralized) table name, every file it will write, and every transformation
+# it applied. An agent (or a human) sees WHAT was chosen without having to
+# reverse-engineer it from the generated files. Emitted as a JSON envelope
+# on `--json`, as a human block on stderr for bare invocations, and skipping
+# every write on `--dry-run` (composable with `--json`).
+#
+# The envelope shape is the SAME across all four language backends and is
+# advertised as `resolution_contract` on the `commands --json` manifest so a
+# caller can programmatically discover the schema version.
+
+# The four generators wired for the envelope. Others (crud, service, queue,
+# validator, seeder, websocket, listener, auth, test, form, view) keep their
+# existing behaviour — this is the minimum surface the plan calls out.
+_RESOLUTION_TARGETS = {"model", "route", "migration", "middleware"}
+
+# Envelope schema version. Bump when the SHAPE changes; adding an optional
+# key on the resolution object is not a break.
+_RESOLUTION_ENVELOPE_VERSION = "1"
+
+
+def _input_fields(flags: dict):
+    """Normalise `--fields` back into the envelope's `input.fields` field.
+
+    A missing / bare / boolean `--fields` maps to null so an agent can rely on
+    the shape; a real "name:string,price:float" value is preserved as-is (the
+    raw text the caller actually supplied).
+    """
+    value = flags.get("fields")
+    if not isinstance(value, str) or not value:
+        return None
+    return value
+
+
+def _resolve_generation(target: str, name: str, flags: dict,
+                        timestamp: str | None = None) -> dict:
+    """Compute the resolution mapping for a generate call. Pure — no writes.
+
+    Called BEFORE the generator runs, so the same envelope drives both --json
+    (emit + write) and --dry-run (emit + skip) without a second walk of the
+    tree. Timestamps for migration filenames are locked at the call site and
+    threaded through the underlying generator via the private `_timestamp`
+    flag, so the envelope path always equals the on-disk filename.
+    """
+    ts = timestamp or datetime.now().strftime("%Y%m%d%H%M%S")
+
+    if target == "model":
+        raw_table = _to_snake(name)
+        table = _to_table(name)
+        transformations = []
+        if raw_table in SQL_RESERVED_TABLE_NAMES and raw_table != table:
+            transformations.append({
+                "kind": "reserved_word_pluralize",
+                "from": raw_table,
+                "to": table,
+                "reason": f"SQL reserved word '{raw_table}' would break CREATE TABLE",
+                "override": (
+                    f"--table {raw_table} --quote (requires quoted-identifier "
+                    "mode, not yet implemented)"
+                ),
+            })
+        migration_filename = f"{ts}_create_{table}.sql"
+        return {
+            "class_name": name,
+            "table_name": table,
+            "file_path": f"src/orm/{name}.py",
+            "migration_path": f"migrations/{migration_filename}",
+            "transformations": transformations,
+            "routes": [],
+            "test_paths": [f"tests/test_{table}_model.py"],
+        }
+
+    if target == "route":
+        route_path = name.lstrip("/")
+        return {
+            "class_name": None,
+            "table_name": None,
+            "file_path": f"src/routes/{route_path}.py",
+            "migration_path": None,
+            "transformations": [],
+            "routes": [
+                f"/api/{route_path}",
+                f"/api/{route_path}/{{id:int}}",
+            ],
+            "test_paths": [f"tests/test_{route_path}.py"],
+        }
+
+    if target == "migration":
+        table = name.removeprefix("create_").removeprefix("add_").removeprefix("drop_")
+        table = _to_snake(table)
+        filename = f"{ts}_{name}.sql"
+        is_create = name.startswith("create_")
+        return {
+            "class_name": None,
+            "table_name": table,
+            "file_path": f"migrations/{filename}",
+            "migration_path": f"migrations/{filename}",
+            "transformations": [],
+            "routes": [],
+            "test_paths": [f"tests/test_{table}_migration.py"] if is_create else [],
+        }
+
+    if target == "middleware":
+        snake = _to_snake(name)
+        return {
+            "class_name": name,
+            "table_name": None,
+            "file_path": f"src/middleware/{snake}.py",
+            "migration_path": None,
+            "transformations": [],
+            "routes": [],
+            "test_paths": [f"tests/test_{snake}.py"],
+        }
+
+    return {}  # never reached; guarded by _RESOLUTION_TARGETS
+
+
+def _actions_from_resolution(target: str, resolution: dict) -> list[str]:
+    """Flat "wrote X" list mirroring what the generators actually write.
+
+    The generators print `  ✓ Created <path>` per file; this reconstructs the
+    same list from the resolution so the envelope's `actions_taken` matches
+    the on-disk effect without having to shadow the generator's own I/O.
+    """
+    actions: list[str] = []
+    file_path = resolution.get("file_path")
+    if file_path:
+        actions.append(f"wrote {file_path}")
+
+    # Migration + its matching .down.sql — _gen_migration writes both.
+    if target == "model" and resolution.get("migration_path"):
+        migration = resolution["migration_path"]
+        actions.append(f"wrote {migration}")
+        actions.append(f"wrote {migration[:-len('.sql')]}.down.sql")
+    if target == "migration" and file_path and file_path.endswith(".sql"):
+        actions.append(f"wrote {file_path[:-len('.sql')]}.down.sql")
+
+    for test_path in resolution.get("test_paths", []):
+        actions.append(f"wrote {test_path}")
+
+    return actions
+
+
+def _format_resolution_block(name: str, target: str, resolution: dict,
+                             dry_run: bool = False) -> str:
+    """Render the human-readable resolution block for stderr on bare calls.
+
+    Same shape as the plan / ADR-0062 example. A generator with no route/table
+    footprint (middleware, route without a matching table) simply omits the
+    lines that don't apply — the block is honest about what was chosen.
+    """
+    suffix = "  (dry-run — nothing written)" if dry_run else ""
+    lines = [f"Generated {target} {name}{suffix}"]
+
+    class_name = resolution.get("class_name")
+    file_path = resolution.get("file_path")
+    if class_name and file_path:
+        lines.append(f"  class      {class_name}  (in {file_path})")
+    elif file_path:
+        lines.append(f"  file       {file_path}")
+
+    pluralize = next(
+        (t for t in resolution.get("transformations", [])
+         if t.get("kind") == "reserved_word_pluralize"),
+        None,
+    )
+    if resolution.get("table_name"):
+        note = ""
+        if pluralize:
+            note = f"  (auto-pluralized: '{pluralize['from']}' is a SQL reserved word)"
+        lines.append(f"  table      {resolution['table_name']}{note}")
+
+    if resolution.get("routes"):
+        lines.append(f"  routes     {', '.join(resolution['routes'])}")
+    if target != "migration" and resolution.get("migration_path"):
+        lines.append(f"  migration  {resolution['migration_path']}")
+
+    if pluralize:
+        lines.append("")
+        lines.append(f"  To keep the raw name '{pluralize['from']}' as the table:")
+        lines.append(
+            f"    tina4 generate {target} {name} "
+            f"--table {pluralize['from']} --quote  "
+            "(opt-in, ADR-0062 forthcoming)"
+        )
+
+    return "\n".join(lines) + "\n"
+
+
+def _emit_resolution(target: str, name: str, flags: dict) -> None:
+    """Handle the --json / --dry-run / bare paths for the 4 wired generators.
+
+    Contract shared by every language (ADR-0062):
+    - --json           → envelope on stdout; nothing else on stdout.
+    - --dry-run        → skip every write; envelope with dry_run=true.
+    - --json + --dry-run → both compose (envelope with actions_taken=[]).
+    - bare             → normal write, then human resolution block on stderr.
+    """
+    import contextlib
+    import io
+    import json as _json
+
+    dry_run = bool(flags.get("dry-run"))
+    want_json = bool(flags.get("json"))
+
+    # Lock the timestamp so the envelope's migration_path and the on-disk
+    # filename agree byte-for-byte (threaded through via `_timestamp` flag).
+    timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+    resolution = _resolve_generation(target, name, flags, timestamp=timestamp)
+
+    actions_taken: list[str] = []
+    if not dry_run:
+        # Thread the locked-in timestamp through the underlying generator,
+        # then run it. When --json we swallow the generator's stdout so the
+        # JSON envelope is the SOLE thing on stdout; otherwise we let its
+        # "Created X" lines through as before.
+        generator_flags = dict(flags)
+        generator_flags["_timestamp"] = timestamp
+        handler = GENERATORS[target]["handler"]
+
+        stdout_sink = io.StringIO() if want_json else sys.stdout
+        with contextlib.redirect_stdout(stdout_sink):
+            handler(name, generator_flags)
+
+        actions_taken = _actions_from_resolution(target, resolution)
+
+    envelope = {
+        "command": "generate",
+        "target": target,
+        "input": {"name": name, "fields": _input_fields(flags)},
+        "resolution": resolution,
+        "actions_taken": actions_taken,
+        "dry_run": dry_run,
+    }
+
+    if want_json:
+        print(_json.dumps(envelope, indent=2))
+    else:
+        # Human resolution block always lands on STDERR (per plan): stdout
+        # keeps whatever the generator printed on the bare path, and the
+        # block never contends with a caller parsing stdout.
+        sys.stderr.write(_format_resolution_block(name, target, resolution,
+                                                  dry_run=dry_run))
+
+
 # ── Generate (rich scaffolding) ───────────────────────────────────────
 
 def _generate(args):
@@ -1004,6 +1252,15 @@ def _generate(args):
     name = args[1] if len(args) > 1 else ""
     flags, _ = _parse_flags(args[2:] if len(args) > 2 else [])
 
+    # ADR-0062: the four wired generators expose a JSON envelope and a
+    # stderr resolution block on every call, so an agent can see WHAT the
+    # framework decided to build with its input. --json emits the envelope;
+    # --dry-run computes it without writing; bare calls print the human
+    # block to stderr AFTER the normal writes complete.
+    if what in _RESOLUTION_TARGETS:
+        _emit_resolution(what, name, flags)
+        return
+
     # Dispatch from the module-level GENERATORS registry (single source of truth
     # for the generate subcommands; also feeds `_help` and the manifest).
     gen_spec = GENERATORS.get(what)
@@ -1385,7 +1642,10 @@ def _gen_migration(name: str, flags: dict = None, *,
     """
     flags = flags or {}
     now = datetime.now()
-    timestamp = now.strftime("%Y%m%d%H%M%S")
+    # ADR-0062: the resolution envelope pre-computes the migration path from a
+    # snapshotted timestamp; if it was supplied via the private `_timestamp`
+    # flag, honour it so envelope and disk agree byte-for-byte.
+    timestamp = flags.get("_timestamp") or now.strftime("%Y%m%d%H%M%S")
     target = Path("migrations")
     target.mkdir(parents=True, exist_ok=True)
 
@@ -3111,7 +3371,18 @@ def _commands_manifest() -> dict:
         if spec.get("args"):
             entry["args"] = list(spec["args"])
         commands.append(entry)
-    return {"framework": "python", "version": __version__, "commands": commands}
+    return {
+        "framework": "python",
+        "version": __version__,
+        "commands": commands,
+        # ADR-0062: agents discover the generate resolution envelope shape
+        # programmatically. A version bump here is a break; adding an
+        # optional envelope key is not.
+        "resolution_contract": {
+            "version": _RESOLUTION_ENVELOPE_VERSION,
+            "envelope": "generate_v1",
+        },
+    }
 
 
 def _commands(args=None):