quantum-framework 0.9.0__py3-none-any.whl

quantum/core/expression_diagnostics.py

@@ -0,0 +1,87 @@
+"""
+Make an unresolved `{expression}` say something.
+
+FRAMEWORK_PLAN.md Fase 2.2. Both databinding paths catch every exception and
+hand back the literal placeholder, which is the right thing to RENDER — a page
+should not 500 because one field is missing — but it threw the diagnosis away.
+The evaluator already knew that `p` was not defined, or that `projects` is a
+list with no `recordCount`; nobody was told.
+
+That silence was the single biggest cost measured in Fase 4: six of the eleven
+frictions found while writing one real screen were the same disease, and three
+of the four bugs produced no message at all. The time went into discovering
+what was wrong, not into fixing it. See DOGFOOD_NOTES.md.
+
+Two things this has to get right to be worth having:
+
+- **Not flood.** A `q:loop` over 1,000 rows evaluates the same broken
+  expression 1,000 times. Each distinct problem is reported once.
+- **Not cry wolf.** A missing `session.`/`form.` variable is a documented
+  contract, not a mistake — templates render before login on purpose. Those
+  stay quiet, or the log becomes noise nobody reads.
+"""
+
+import logging
+import re
+import threading
+
+logger = logging.getLogger('quantum.databinding')
+
+# Scopes whose absence is normal: a template renders before login, before a
+# form is posted, before a request has query parameters.
+QUIET_SCOPES = ('session', 'application', 'request', 'cookie', 'form', 'query')
+
+
+def root_scope(expression: str) -> str:
+    """The leading scope name of an expression, if it has one."""
+    return expression.split('.')[0].split('[')[0].strip()
+
+
+def is_absent_scope(expression: str) -> bool:
+    """Whether an unresolved expression is an ABSENT SCOPED VARIABLE.
+
+    Those resolve to '' rather than failing — a template renders before login
+    on purpose. Both databinding paths have to agree on this or the same
+    {form.email} renders as '' in one pass and as literal text in the other,
+    which is exactly what happened: the runtime honoured the contract and the
+    renderer leaked the placeholder onto the page.
+    """
+    return root_scope(expression) in QUIET_SCOPES
+
+
+# `{"product": "Laptop", "price": 999}` — a JSON object written inside a
+# value, not an expression that failed. Quantum has no escape for a brace, so
+# a JSON literal in a .q file is read as databinding, complained about once
+# per object, and then left alone (which is why it still works). Ten objects
+# meant ten warnings pointing at nothing the author can fix.
+_JSON_OBJECT_BODY = re.compile(r'^\s*(["\'])(?:(?!\1).)*\1\s*:', re.DOTALL)
+
+
+def looks_like_json_object(expression: str) -> bool:
+    """Whether this is the inside of a JSON object, not an expression."""
+    return bool(_JSON_OBJECT_BODY.match(expression))
+
+
+_seen = set()
+_lock = threading.Lock()
+
+
+def report_unresolved(expression: str, error: BaseException) -> None:
+    """Log why a `{expression}` did not resolve, once per distinct problem."""
+    if is_absent_scope(expression) or looks_like_json_object(expression):
+        return
+
+    reason = str(error) or type(error).__name__
+    key = (expression, reason)
+    with _lock:
+        if key in _seen:
+            return
+        _seen.add(key)
+
+    logger.warning("{%s} did not resolve: %s", expression, reason)
+
+
+def reset() -> None:
+    """Forget what has been reported. For tests, and for a reloading server."""
+    with _lock:
+        _seen.clear()

quantum/core/expression_stdlib.py

@@ -0,0 +1,148 @@
+"""
+Standard functions available inside Quantum `{...}` expressions.
+
+Deliberately small. Every entry here is a function that was either already
+needed by real .q files or whose absence caused a concrete bug:
+
+- `now()` / `dateAdd()` / `dateFormat()` — their absence is why
+  `session.sessionExpiry` had to be hardcoded to make login work at all
+  (AUDIT_FIX_PLAN.md Fase 1). A framework that cannot express "24 hours from
+  now" in its own language forces every app to hardcode a date.
+- `len` / `first` / `last` — `.length` already worked on arrays via attribute
+  access; these make the same thing available as a call.
+
+Functions are looked up by name from expressions, so anything added here
+becomes language surface. That is the reason to keep it short.
+"""
+
+from datetime import datetime, timedelta
+from typing import Any, Iterable, Optional
+
+_UNITS = {
+    's': 'seconds', 'sec': 'seconds', 'second': 'seconds', 'seconds': 'seconds',
+    'n': 'minutes', 'min': 'minutes', 'minute': 'minutes', 'minutes': 'minutes',
+    'h': 'hours', 'hour': 'hours', 'hours': 'hours',
+    'd': 'days', 'day': 'days', 'days': 'days',
+    'w': 'weeks', 'week': 'weeks', 'weeks': 'weeks',
+}
+
+
+# -- dates -----------------------------------------------------------------
+
+def now() -> datetime:
+    """Current local datetime."""
+    return datetime.now()
+
+
+def date_add(unit: str, amount: int, start: Optional[Any] = None) -> datetime:
+    """Add an interval to a datetime (defaults to now).
+
+    dateAdd('h', 24)  ->  24 hours from now
+    """
+    key = _UNITS.get(str(unit).lower())
+    if key is None:
+        raise ValueError(
+            f"unknown date unit {unit!r}; use s/n/h/d/w "
+            f"(seconds/minutes/hours/days/weeks)"
+        )
+    base = _as_datetime(start) if start is not None else datetime.now()
+    return base + timedelta(**{key: int(amount)})
+
+
+def date_format(value: Any, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
+    """Format a datetime (or ISO string) with a strftime pattern."""
+    return _as_datetime(value).strftime(fmt)
+
+
+def date_diff(unit: str, start: Any, end: Any) -> int:
+    """Whole units between two datetimes."""
+    key = _UNITS.get(str(unit).lower())
+    if key is None:
+        raise ValueError(f"unknown date unit {unit!r}")
+    delta = _as_datetime(end) - _as_datetime(start)
+    seconds = delta.total_seconds()
+    per = {'seconds': 1, 'minutes': 60, 'hours': 3600,
+           'days': 86400, 'weeks': 604800}[key]
+    return int(seconds // per)
+
+
+def _as_datetime(value: Any) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, str):
+        return datetime.fromisoformat(value)
+    raise ValueError(f"cannot read {value!r} as a datetime")
+
+
+# -- strings ---------------------------------------------------------------
+
+def _upper(v: Any) -> str: return str(v).upper()
+def _lower(v: Any) -> str: return str(v).lower()
+def _trim(v: Any) -> str: return str(v).strip()
+def _replace(v: Any, old: str, new: str) -> str: return str(v).replace(old, new)
+def _split(v: Any, sep: str = ",") -> list: return str(v).split(sep)
+def _contains(v: Any, needle: Any) -> bool: return str(needle) in str(v)
+
+
+# -- collections -----------------------------------------------------------
+
+def _len(v: Any) -> int:
+    try:
+        return len(v)
+    except TypeError:
+        return 0
+
+
+def _first(v: Iterable) -> Any:
+    items = list(v)
+    return items[0] if items else None
+
+
+def _last(v: Iterable) -> Any:
+    items = list(v)
+    return items[-1] if items else None
+
+
+def _join(v: Iterable, sep: str = ", ") -> str:
+    return sep.join(str(i) for i in v)
+
+
+def _sort(v: Iterable, reverse: bool = False) -> list:
+    return sorted(v, reverse=reverse)
+
+
+# -- numbers ---------------------------------------------------------------
+
+def _round(v: Any, digits: int = 0) -> Any:
+    result = round(float(v), int(digits))
+    return int(result) if digits == 0 else result
+
+
+STDLIB = {
+    # dates
+    'now': now,
+    'dateAdd': date_add,
+    'dateFormat': date_format,
+    'dateDiff': date_diff,
+    # strings
+    'upper': _upper,
+    'lower': _lower,
+    'trim': _trim,
+    'replace': _replace,
+    'split': _split,
+    'contains': _contains,
+    # collections
+    'len': _len,
+    'first': _first,
+    'last': _last,
+    'join': _join,
+    'sort': _sort,
+    # numbers
+    'round': _round,
+    'abs': abs,
+    'min': min,
+    'max': max,
+    'int': int,
+    'float': float,
+    'str': str,
+}