quantum-framework 0.18.0__py3-none-any.whl

quantum/core/config_env.py

@@ -0,0 +1,54 @@
+"""
+`${VAR}` in quantum.config.yaml (CFG-1).
+
+    datasources:
+      db:
+        password: ${DB_PASSWORD}
+        host: ${DB_HOST:-localhost}
+        port: ${DB_PORT:5432}      # ':' works as well as ':-'
+
+A config file is the place people put secrets by reference, and every loader
+used to read `${DB_PASSWORD}` as the literal password. There were four loaders
+(the CLI, the web server, the service container, migrations); they all go
+through expand_env now.
+"""
+
+import os
+import re
+from typing import Any
+
+_REFERENCE = re.compile(r'\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-?([^}]*))?\}')
+
+
+class ConfigEnvError(ValueError):
+    """A `${VAR}` with no value and no default."""
+
+
+def expand_env(value: Any, path: str = '') -> Any:
+    """Replace `${NAME}` and `${NAME:-default}` in every string of a loaded config.
+
+    `$$` is a literal `$`. A variable that is not set and has no default is an
+    error naming the variable and where it was used — an empty password or
+    database path would otherwise fail much later, somewhere else.
+    """
+    if isinstance(value, dict):
+        return {k: expand_env(v, f'{path}.{k}' if path else str(k)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env(v, f'{path}[{i}]') for i, v in enumerate(value)]
+    if not isinstance(value, str) or '$' not in value:
+        return value
+
+    def substitute(match):
+        if match.group(0) == '$$':
+            return '$'
+        name, default = match.group(1), match.group(2)
+        if name in os.environ:
+            return os.environ[name]
+        if default is not None:
+            return default
+        raise ConfigEnvError(
+            f"quantum.config.yaml: {path or 'value'} uses ${{{name}}}, but the "
+            f"environment variable {name} is not set. Set it, or give a default: "
+            f"${{{name}:-value}}")
+
+    return _REFERENCE.sub(substitute, value)

quantum/core/docs_links.py

@@ -0,0 +1,8 @@
+"""Documentation pages that error messages point to (one place, one spelling)."""
+
+DOCS = 'https://danielgregorio.github.io/quantum'
+
+# EXEC-*: the order in which a page's parts run. The traps — a statement in
+# the markup, a variable the action cannot see, a guard reading the page —
+# all come from that order, so their messages send the reader here.
+HOW_A_PAGE_RUNS = f'{DOCS}/guide/how-a-page-runs'

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,208 @@
+"""
+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.
+"""
+
+import math
+import re
+from decimal import Decimal, ROUND_HALF_UP
+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)
+
+
+def _slugify(v: Any) -> str:
+    """'Olá, Mundo!' -> 'ola-mundo': for URLs made from a title (EXPR-9)."""
+    import unicodedata
+    texto = unicodedata.normalize('NFKD', str(v)).encode('ascii', 'ignore').decode('ascii')
+    return re.sub(r'[^a-z0-9]+', '-', texto.lower()).strip('-')
+
+
+# -- 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:
+    # EXPR-9: half away from zero, as in ColdFusion and spreadsheets. Python's
+    # round() is banker's rounding over binary floats: round(2.5) was 2 and
+    # round(0.125, 2) was 0.12. Decimal over the number's text avoids both.
+    casas = int(digits)
+    passo = Decimal(1).scaleb(-casas)
+    result = Decimal(str(v)).quantize(passo, rounding=ROUND_HALF_UP)
+    return int(result) if casas <= 0 else float(result)
+
+
+def _ceil(v: Any) -> int:
+    return math.ceil(float(v))
+
+
+def _floor(v: Any) -> int:
+    return math.floor(float(v))
+
+
+# -- passwords ---------------------------------------------------------------
+#
+# Authentication is Core (decision D4), and a login is "look the user up, then
+# check the password". Without these, a .q could not check a password against
+# a stored hash without q:python — so every login example just set
+# session.authenticated=true for whoever submitted the form (gap AUTH-1).
+
+def hash_password(password: Any) -> str:
+    """bcrypt hash of a password, for storing. Never store the password itself."""
+    import bcrypt
+    if password is None or password == '':
+        raise ValueError("hashPassword: the password is empty")
+    return bcrypt.hashpw(str(password).encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+
+
+def verify_password(password: Any, hashed: Any) -> bool:
+    """True when `password` matches a hash made by hashPassword.
+
+    Fail-closed: an empty password, a missing hash or a malformed hash is
+    False, never an error — so `q:if condition="verifyPassword(senha, h)"`
+    cannot be tricked into the true branch by bad data.
+    """
+    import bcrypt
+    if not password or not hashed or not isinstance(hashed, str):
+        return False
+    try:
+        return bcrypt.checkpw(str(password).encode('utf-8'), hashed.encode('utf-8'))
+    except (ValueError, TypeError):
+        return False
+
+
+STDLIB = {
+    # passwords
+    'hashPassword': hash_password,
+    'verifyPassword': verify_password,
+    # 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,
+    'slugify': _slugify,
+    # collections
+    'len': _len,
+    'first': _first,
+    'last': _last,
+    'join': _join,
+    'sort': _sort,
+    # numbers
+    'round': _round,
+    'ceil': _ceil,
+    'floor': _floor,
+    'abs': abs,
+    'min': min,
+    'max': max,
+    'int': int,
+    'float': float,
+    'str': str,
+}