trodo-python 2.18.1__py3-none-any.whl → 2.19.0__py3-none-any.whl

trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.18.0"
+__version__ = "2.19.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -322,7 +322,7 @@ def reset(distinct_id: str) -> ResetResult:
 def get_prompt(
     name: str,
     label: Optional[str] = None,
-    version: Optional[int] = None,
+    version: Optional[Union[int, str]] = None,
     cache_ttl_seconds: Optional[float] = None,
     fallback: Optional[Dict[str, Any]] = None,
     max_retries: int = 2,
@@ -330,7 +330,9 @@ def get_prompt(
     """Fetch a managed prompt by name.
 
     Follows the ``production`` label by default; pass ``label`` for a different
-    one or ``version`` to pin exactly.
+    one or ``version`` to pin exactly. ``version`` may be the integer
+    ``version_no`` or a ``version_hash`` (full, or an unambiguous short prefix
+    like ``a3f9c2``) — the hash is the stable identity, so prefer it.
 
     Cached for 60s with stale-while-revalidate, so a Trodo outage degrades
     instead of taking your app down. Pass ``fallback`` to cover cold start::

trodo/prompts/compile.py

@@ -74,8 +74,12 @@ def build_scope(
 ) -> Dict[str, Any]:
     """Build the render scope from declarations + caller values.
 
-    Resolution order: caller value → declared default → required-and-absent
-    raises → optional-and-absent renders empty.
+    Resolution order: caller value -> declared default -> required-and-absent
+    raises -> optional-and-absent renders empty.
+
+    `required` is enforced HERE, in your process, before the model call -- Trodo
+    only stores the declaration. A variable with a default can never fail this
+    check, because the default is itself a value.
     """
     errors: List[str] = []
     scope: Dict[str, Any] = {}
@@ -100,11 +104,24 @@ def build_scope(
         has = name in values
         value = values.get(name) if has else None
 
-        # Missing value -> the declared default, or empty. Nothing is
-        # "required": compile always succeeds with whatever the caller provides.
+        # `required` asks a narrower question than default-substitution does:
+        # did the caller supply something that will actually render? None and ""
+        # both render as nothing, the very outcome the flag exists to prevent,
+        # so neither counts. (0 and False do -- they render.)
+        supplied = has and value is not None and value != ""
+
+        # Missing value -> the declared default, or empty.
         if not has or value is None:
             value = default if has_default else ([] if type_ == "messages" else "")
 
+        # A default always satisfies the requirement, so the two never both
+        # apply; the editor won't let you author both, but a hand-written
+        # declaration can.
+        required = v.get("required") if isinstance(v, dict) else getattr(v, "required", None)
+        if not supplied and required is True and not has_default:
+            errors.append(f"variable '{name}': required, but no value was provided")
+            continue
+
         scope[name] = _coerce(value, type_, name, errors)
 
     # Passing something the prompt doesn't declare is nearly always a rename

trodo/prompts/types.py

@@ -29,6 +29,16 @@ class PromptVariable:
     regex, with no defaults and no required-ness. The declaration is what lets
     ``compile()`` fail before the model call rather than shipping a literal
     ``{{typo}}`` and finding out from the bill.
+
+    ``required`` is enforced by ``compile()``, which runs in YOUR process —
+    Trodo only stores the declaration. Nothing server-side rejects a call for a
+    missing variable, and nothing rejects a version for declaring one.
+
+    Marking a variable required means the caller must pass a value that will
+    actually render: an omitted key, ``None`` and ``""`` all fail, since all
+    three render as nothing (``0`` and ``False`` pass). A variable with
+    a ``default`` can never fail the check — the default is a value — so the two
+    are mutually exclusive in practice.
     """
 
     name: str

{trodo_python-2.18.1.dist-info → trodo_python-2.19.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.18.1
+Version: 2.19.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.18.1.dist-info → trodo_python-2.19.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-trodo/__init__.py,sha256=ZDRoY4LQW3mIN0G7YmfdF_KGoYwUBWIY-T7Dji-7-yQ,26734
+trodo/__init__.py,sha256=n7YUScfJqdXfIUwWL-g1PekBrYfQ0A0m4kAme26rwUM,26928
 trodo/client.py,sha256=9UYaHZtWPMYdlG2xWVf77PQJ9DfFgN-zobTh60i8_Cc,22453
 trodo/types.py,sha256=eySgUvCXROG2TxtxgiU0MNr5iH0DEcduK8bmYtTKG44,3138
 trodo/user_context.py,sha256=uHCI2WYoOI3cNwdIUEuZdX4VYSu14pzm348ksn6hn_c,8195
@@ -25,9 +25,9 @@ trodo/otel/register.py,sha256=bV_ePTfUvPugig2GZnylhzxi2QfoPWs96A9mGLPMrSQ,9387
 trodo/otel/transport.py,sha256=hzZz8gwSMGJ8CxdijmLn1Ljt18owr9XTWy13DLbwYbw,2441
 trodo/otel/wrap_agent.py,sha256=cJjrzlZNW2g6q_coLN7UR4uxn65h4u3-LNzMfE4dLVw,40999
 trodo/prompts/__init__.py,sha256=yunNc8WkTSfEEkRR-NZWXAt_ZB3Ee2INRh-4RE7uHj4,806
-trodo/prompts/compile.py,sha256=sEMl8EWdK0G9uOKGcgc39ujnA5RLCUtbk26TYVqK68Q,6345
+trodo/prompts/compile.py,sha256=ydJDI7YS3PiLzAJ4H-kmqGV-1kkUxlQrf_xtZZ7fR5g,7267
 trodo/prompts/template.py,sha256=obQiivPCR6LEdz7q1cby7uL25tYHYui4aoEaiUNqWfs,9357
-trodo/prompts/types.py,sha256=3oyrEDb1jfnC4gF02mM3izhNHstJ-bu-8TxoF7Yk6mQ,4425
+trodo/prompts/types.py,sha256=1TVGHp3vtWV1tr0l-IJfL7EKvrB8ZmQRwLvDqvbOfJ0,5007
 trodo/queue/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 trodo/queue/batch_flusher.py,sha256=4Lg6T3Urwi9U0Q4FpFGPmjDYKg4ZliCTR-ND8BJvWaY,1298
 trodo/queue/event_queue.py,sha256=EVFZrhlq_kwC3jJ2GK0wMhHISf9UzLCZNDnT_aZ2I2A,872
@@ -36,7 +36,7 @@ trodo/session/server_session.py,sha256=McsudEiq33XDq3nqxgzBcUvIjQxCMscwEuAPnYXrT
 trodo/session/session_manager.py,sha256=7ht5LeeZX1HLLfPeNV_a8NkXGbHl3up0CRtCGr3EzjQ,2995
 trodo/util/__init__.py,sha256=Z9c4rPPdKg06Kk3byKheDqksSgR4WNvS475oQ5sNljc,54
 trodo/util/lru.py,sha256=QIsM7s6J_E9ZjiXatSyReZIEeGypTAcgrPWWy8YsRa4,2465
-trodo_python-2.18.1.dist-info/METADATA,sha256=_pIbEb_guFZ6iH5xI0AyhiPuvVoGTlwgLVKsSqNub5E,25308
-trodo_python-2.18.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-trodo_python-2.18.1.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
-trodo_python-2.18.1.dist-info/RECORD,,
+trodo_python-2.19.0.dist-info/METADATA,sha256=RD_p3hblnxk6pAacML6IkqzfdIqP33lD50GS1kApkW8,25308
+trodo_python-2.19.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+trodo_python-2.19.0.dist-info/top_level.txt,sha256=VCQu1CJWFmNsqTs1YxMcw4Mq35Tc3z3uI9RwHEXAayQ,6
+trodo_python-2.19.0.dist-info/RECORD,,