prefect-client 3.6.24.dev1__tar.gz → 3.6.24.dev2__tar.gz

{prefect_client-3.6.24.dev1 → prefect_client-3.6.24.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.24.dev1
+Version: 3.6.24.dev2
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect_client-3.6.24.dev1 → prefect_client-3.6.24.dev2}/src/prefect/AGENTS.md

@@ -48,5 +48,6 @@ Use `get_logger()` from `prefect.logging` instead of raw `logging.getLogger()`
 - `logging/` → Logging handlers, API log shipping, and run-context loggers (see logging/AGENTS.md)
 - `runner/` → Thin facade over extracted single-responsibility classes for local flow run execution (see runner/AGENTS.md)
 - `deployments/` → YAML-driven deployment lifecycle: project init, build/push/pull steps, and triggering remote flow runs (see deployments/AGENTS.md)
+- `utilities/` → Cross-cutting helpers: async utils, schema hydration, callables introspection, and more (see utilities/AGENTS.md)
 - `docker/` → `DockerImage` class for building and pushing Docker images during deployment
 - `telemetry/` → OS-level resource metric collection and run telemetry

prefect_client-3.6.24.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.24.dev2"
+__build_date__ = "2026-03-24 08:20:38.049808+00:00"
+__git_commit__ = "950ac604f873cee7c2df788d96a4a54bb4e08e4e"
+__dirty__ = False

{prefect_client-3.6.24.dev1 → prefect_client-3.6.24.dev2}/src/prefect/flow_engine.py

@@ -1798,12 +1798,23 @@ def run_flow(
             ret_val = run_flow_sync(**kwargs)
     except (Abort, Pause):
         raise
-    except:
+    except Exception:
         if error_logger:
             error_logger.error(
                 "Engine execution exited with unexpected exception", exc_info=True
             )
         raise
+    except BaseException:
+        # This top-level wrapper can fail before setup_run_context() installs
+        # the flow-run-scoped logger onto the engine.  This branch
+        # intentionally preserves per-run error logging for interrupts such
+        # as KeyboardInterrupt and SystemExit that would otherwise bypass
+        # the Exception handler above.
+        if error_logger:
+            error_logger.error(
+                "Engine execution interrupted by base exception", exc_info=True
+            )
+        raise
     return ret_val
 
 

prefect_client-3.6.24.dev2/src/prefect/utilities/AGENTS.md

@@ -0,0 +1,70 @@
+# Utilities
+
+General-purpose helpers and cross-cutting tools used throughout the Prefect SDK and server.
+
+## Purpose & Scope
+
+Shared utilities: data manipulation, async helpers, schema tooling, callables introspection, and infrastructure helpers. These modules have no common theme beyond being broadly reused — if something is self-contained and used across two or more subsystems, it lives here.
+
+Does NOT include: server-specific utilities (`server/utilities/`), concurrency slot management (`concurrency/`), or logging infrastructure (`logging/`).
+
+## Key Submodules
+
+- `schema_tools/` — Hydration and validation of `__prefect_kind` template structures (see below)
+- `asyncutils.py` — Async/sync bridge utilities and concurrency helpers
+- `callables.py` — Function signature introspection and parameter coercion
+- `collections.py` — Extended collection helpers (visit, flatten, remove nested keys)
+- `annotations.py` — Custom Prefect type annotations used in flow/task signatures
+- `pydantic.py` — Pydantic v1/v2 compatibility shims
+- `templating.py` — Jinja template utilities and `maybe_template()` detection
+
+## schema_tools: Hydration System
+
+`schema_tools/hydration.py` resolves `__prefect_kind` structures into real Python values. These structures appear in deployment parameters and automation action payloads.
+
+### Entry Point
+
+```python
+from prefect.utilities.schema_tools.hydration import hydrate, HydrationContext
+
+ctx = HydrationContext(render_jinja=True, jinja_context={"event": event})
+result = hydrate(parameters, ctx)
+```
+
+### `__prefect_kind` Contracts
+
+| Kind | Input structure | Output | Notes |
+|------|----------------|--------|-------|
+| `"jinja"` | `{"__prefect_kind": "jinja", "template": "..."}` | `str` | **Always returns a string** — even if the template renders a number |
+| `"json"` | `{"__prefect_kind": "json", "value": ...}` | parsed value | If `value` is already a non-string (int, bool, list, dict, None), it is returned as-is without JSON decoding |
+| `"workspace_variable"` | `{"__prefect_kind": "workspace_variable", "variable_name": "..."}` | variable value | Requires `render_workspace_variables=True` in context |
+
+**Critical non-obvious invariant:** `jinja` kind always returns a `str`. To preserve the original type of a templated value (int, float, bool, list, dict), use the json+jinja pattern with `| tojson`:
+
+```python
+# Type-preserving round-trip for a single expression:
+{
+    "__prefect_kind": "json",
+    "value": {
+        "__prefect_kind": "jinja",
+        "template": "{{ value | tojson }}"
+    }
+}
+# Renders {{ value | tojson }} → JSON string → json.loads() → original type
+```
+
+This is the pattern used by `RunDeployment._wrap_v1_template` for single-expression Jinja parameters.
+
+### Placeholder Protocol
+
+Handlers return `Placeholder` subclasses (e.g. `RemoveValue`, `InvalidJSON`, `InvalidJinja`) when values are missing or rendering fails. The `hydrate()` function removes keys with `RemoveValue` and propagates error placeholders unless `raise_on_error=True` in the context.
+
+## Anti-Patterns
+
+- **Don't use `jinja` kind and expect a typed value** — it always returns a string. Use `json` + `jinja` + `| tojson` for type preservation.
+- **Don't add server imports to utility modules** — these are used client-side too. `HydrationContext.build()` is an exception (async, server-only) but the rest of `hydration.py` must remain importable without a running server.
+
+## Pitfalls
+
+- `maybe_template(s)` (in `templating.py`) only checks whether a string looks like it contains a Jinja expression — it does not validate that it's well-formed. A string with `{{` but no `}}` returns `True`.
+- `HydrationContext` workspace variables are loaded once at build time. Stale contexts don't reflect variable updates made after context creation.

{prefect_client-3.6.24.dev1 → prefect_client-3.6.24.dev2}/src/prefect/utilities/schema_tools/hydration.py

@@ -208,6 +208,9 @@ def json_handler(obj: dict[str, Any], ctx: HydrationContext):
         if isinstance(dehydrated_json, Placeholder):
             return dehydrated_json
 
+        if not isinstance(dehydrated_json, str):
+            return dehydrated_json
+
         try:
             return json.loads(dehydrated_json)
         except (json.decoder.JSONDecodeError, TypeError) as e:

prefect_client-3.6.24.dev1/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.6.24.dev1"
-__build_date__ = "2026-03-21 08:11:26.248833+00:00"
-__git_commit__ = "a74453a3544b6e146a7b422d9bfb3d9bd0a55594"
-__dirty__ = False