prefect-client 3.6.27.dev5__tar.gz → 3.6.28.dev1__tar.gz

{prefect_client-3.6.27.dev5 → prefect_client-3.6.28.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.27.dev5
+Version: 3.6.28.dev1
 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.28.dev1/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.28.dev1"
+__build_date__ = "2026-04-20 08:52:09.547211+00:00"
+__git_commit__ = "6373056dad307ad9526f0257987e885e30934f87"
+__dirty__ = False

{prefect_client-3.6.27.dev5 → prefect_client-3.6.28.dev1}/src/prefect/client/AGENTS.md

@@ -9,6 +9,7 @@ HTTP client for communicating with Prefect server and Prefect Cloud.
 - **Methods should accept simple kwargs** (`str`, `int`, `UUID`, etc.) and return Pydantic models. Avoid accepting complex objects as parameters.
 - **Client schemas are separate from server schemas.** This module has its own `schemas/` to avoid tangling with `server/schemas/`. Keep the boundary clean.
 - **Do not import server-only modules** (`server/database`, `server/models`, etc.) from anything in this directory — it would break the `prefect-client` package build.
+- **Task-run submission schemas must be eagerly rebuilt.** Schemas instantiated on the concurrent submission path (`Task.create_local_run()`) are rebuilt at import time via `model_rebuild()` at the bottom of `schemas/objects.py`. Pydantic defers schema construction to first use; under threadpool contention, multiple workers race to build the same schema simultaneously. If you add a new schema used in this hot path, add a corresponding `model_rebuild()` call there.
 
 ## Structure
 

{prefect_client-3.6.27.dev5 → prefect_client-3.6.28.dev1}/src/prefect/client/schemas/objects.py

@@ -942,6 +942,18 @@ class TaskRun(TimeSeriesBaseModel, ObjectBaseModel):
         return get_or_create_run_name(name)
 
 
+# These models are instantiated while task runs are being created locally on the
+# concurrent submission path. Rebuild them eagerly so threadpool workers do not
+# trigger deferred first-use schema builds under contention.
+RunInput.model_rebuild()
+TaskRunPolicy.model_rebuild()
+TaskRunResult.model_rebuild()
+FlowRunResult.model_rebuild()
+Parameter.model_rebuild()
+Constant.model_rebuild()
+TaskRun.model_rebuild()
+
+
 class Workspace(PrefectBaseModel):
     """
     A Prefect Cloud workspace.

prefect_client-3.6.28.dev1/src/prefect/utilities/AGENTS.md

@@ -0,0 +1,57 @@
+# 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/`).
+
+## Cross-cutting rules
+
+- **Don't add server imports to utility modules.** Everything here is used client-side too. `HydrationContext.build()` in `schema_tools/` is an explicit, documented exception (async, server-only); no new server-touching code should creep into other modules.
+
+## Subpackages (focused intent nodes)
+
+Each subpackage owns its own `AGENTS.md` with entry points and pitfalls specific to that domain.
+
+- `schema_tools/` → Hydration and validation of `__prefect_kind` template structures (see `schema_tools/AGENTS.md`)
+- `processutils/` → Subprocess execution, output streaming, and command serialization (see `processutils/AGENTS.md`)
+- `callables/` → Function signature introspection, parameter coercion, parameter schema generation (see `callables/AGENTS.md`)
+- `asyncutils/` → Async/sync bridging, thread coordination, concurrency primitives (see `asyncutils/AGENTS.md`)
+- `templating/` → Placeholder detection and value application for Prefect's `{{ }}` templating (see `templating/AGENTS.md`)
+- `engine/` → Result-to-state linking, SIGTERM bridge management, and control-intent coordination (see `engine/AGENTS.md`)
+- `filesystem/` → File filtering, path normalization, `tmpchdir` (see `filesystem/AGENTS.md`)
+
+## Flat modules
+
+These modules have no dedicated intent node yet. Promote any one of them to a subpackage (`foo.py` → `foo/__init__.py` + `foo/AGENTS.md`) when non-obvious invariants accrue — the import path is preserved.
+
+- `annotations.py` — Custom Prefect type annotations used in flow/task signatures (`unmapped`, `allow_failure`, `quote`, `NotSet`)
+- `collections.py` — Extended collection helpers (`visit_collection`, `flatten`, `remove_nested_keys`)
+- `dispatch.py` — Dynamic type dispatch registry
+- `importtools.py` — Dynamic imports, aliased module loading, script-to-module conversion
+- `pydantic.py` — Pydantic v1/v2 compatibility shims, custom serializers, type dispatch integration
+- `hashing.py` — Stable hashing (`stable_hash`, `file_hash`, `hash_objects`)
+- `dockerutils.py` — Docker image building, Python version detection, Docker client helpers
+- `timeout.py` — Timeout context managers for async/sync code
+- `services.py` — Client metrics server and resilient service loop with backoff
+- `visualization.py` — Flow/task graph visualization via Graphviz
+- `urls.py` — URL validation and UI path formatting
+- `names.py` — Slug generation and obfuscation helpers
+- `math.py` — Distribution sampling and clamping utilities
+- `text.py` — String truncation and fuzzy matching
+- `context.py` — Context variable accessors
+- `compat.py` — Python version compatibility shims
+- `slugify.py` — Thin wrapper around `unicode-slugify`
+- `generics.py` — Generic type validation
+- `render_swagger.py` — MkDocs plugin for rendering Swagger/OpenAPI schemas
+
+Private (`_`-prefixed):
+
+- `_ast.py` — AST-based flow-decorator discovery in source files
+- `_engine.py` — Naming and hook-resolution helpers for custom flow/task run names
+- `_git.py` — Git origin/branch introspection for deployment metadata
+- `_infrastructure_exit_codes.py` — Registry of exit-code explanations for infrastructure processes
+- `_deprecated.py` — Legacy wrappers retained for backward compat

prefect_client-3.6.28.dev1/src/prefect/utilities/asyncutils/AGENTS.md

@@ -0,0 +1,20 @@
+# asyncutils
+
+Async/sync bridging, thread coordination, and concurrency primitives used throughout the SDK.
+
+## Purpose & Scope
+
+Bridges Prefect's async engine with user-written sync code (and vice versa) without deadlocking the event loop or losing context. Also provides a handful of async-aware primitives (`LazySemaphore`, timed task creation) used by higher layers.
+
+## Entry Points
+
+- `run_coro_as_sync(coro)` — run an async coroutine from sync code, reusing the global loop when available.
+- `run_sync_in_worker_thread(fn, *args, **kwargs)` — execute a blocking sync callable off the event loop.
+- `sync_compatible(fn)` — decorator letting a single `async def` be called from both sync and async callers.
+- `LazySemaphore` — a semaphore whose capacity is resolved on first acquisition (used for managing open-file limits at import time without evaluating `resource` limits eagerly).
+- `gather(*calls)` / `create_gather_task_group()` — run a collection of coroutine-returning callables concurrently and collect their results positionally.
+- `create_task(coro)` — create an `asyncio.Task` with Prefect's logging-and-cancellation-friendly wiring.
+
+## Pitfalls
+
+_No pitfalls documented yet. Add here when non-obvious behaviors surface during debugging — especially around context propagation, thread-to-loop hand-off, and cancellation semantics, which tend to bite in subtle ways._

prefect_client-3.6.28.dev1/src/prefect/utilities/callables/AGENTS.md

@@ -0,0 +1,22 @@
+# callables
+
+Function signature introspection, parameter coercion, and JSON Schema generation for flow and task parameters.
+
+## Purpose & Scope
+
+Inspects user-written flow/task functions to produce:
+- Bindable `args`/`kwargs` from a parameters dict (`parameters_to_args_kwargs`, `get_call_parameters`).
+- JSON Schema representations of function signatures for UI parameter forms and server-side validation (`parameter_schema`).
+
+## Entry Points
+
+- `parameters_to_args_kwargs(fn, parameters) -> (args, kwargs)` — split a parameters dict into positional and keyword slots based on the function's signature.
+- `get_call_parameters(fn, call_args, call_kwargs) -> dict` — inverse: bind actual call args/kwargs into a parameters dict.
+- `parameter_schema(fn) -> ParameterSchema` — introspect the function signature into a Pydantic-backed JSON Schema.
+
+## Pitfalls
+
+- **`parameters_to_args_kwargs` adjusts the positional/keyword split based on the wrapper's signature, not the wrapped function's.** For `@functools.wraps`-decorated callables, it inspects the *wrapper* (via `follow_wrapped=False`) to count how many positional slots are actually available and routes excess parameters to `**kwargs`. This means `args` and `kwargs` from this function are shaped for the *wrapper* call, not the inner function — callers must not assume all POSITIONAL_OR_KEYWORD parameters end up in `args`.
+- **`parameters_to_args_kwargs` skips the positional-to-keyword rewrite entirely when the function signature contains `*args`.** Inserting KEYWORD_ONLY parameters before a VAR_POSITIONAL parameter is invalid in Python, so the original signature is used as-is in that case.
+- **Passing the same key in both an explicit parameter and a `**kwargs` dict raises `TypeError`.** `parameters_to_args_kwargs` detects when a VAR_KEYWORD (`**kwargs`) dict contains a key that also appears as an explicit parameter and raises rather than silently letting the variadic entry win. Exception: POSITIONAL_ONLY parameters are exempt because `fn(1, **{'a': 2})` is legal when `a` is positional-only.
+- **`generate_parameter_schema` silently downgrades unsupported parameter types to `Any`.** When a parameter's type raises `ValueError`, `TypeError`, or `PydanticInvalidForJsonSchema` during JSON schema generation (e.g., `Callable`, custom types Pydantic can't serialize), the type is replaced with `Any` in the output schema without warning. If a flow parameter shows up as `Any` in the schema, the declared type is not JSON-schema-compatible.

prefect_client-3.6.28.dev1/src/prefect/utilities/engine/AGENTS.md

@@ -0,0 +1,31 @@
+# engine
+
+Result-to-state linking, SIGTERM bridge management, and helpers shared by the flow/task engines.
+
+## Purpose & Scope
+
+Two responsibilities live here:
+
+1. **Result-to-state linking** — glue between Python return values (which callers receive) and the `State` objects that represent them on the server. Maintains the identity-keyed `run_results` map inside `EngineContext` and exposes safe accessors.
+
+2. **SIGTERM bridge** — installs and tears down Prefect's SIGTERM handler (`TerminationSignal`), coordinates control-intent acknowledgement with the runner, and exposes locked helpers so the engine can atomically commit cancellation intent before signalling readiness to the runner.
+
+Naming and hook-resolution helpers for custom flow/task run names live in sibling `../_engine.py` (flat module), not here.
+
+## Entry Points
+
+**Result linking:**
+- `link_state_to_result(state, result, run_type)` — associate a `State` with a Python object under a specific `RunType` for later lookup via `get_state_for_result`.
+- `link_state_to_flow_run_result(state, result)` / `link_state_to_task_run_result(state, result)` — scoped variants used by the flow and task engines respectively.
+- `get_state_for_result(obj) -> tuple[State, RunType] | None` — identity-verified lookup that handles `id()` collisions safely.
+
+**SIGTERM bridge:**
+- `capture_sigterm()` — context manager that installs Prefect's SIGTERM bridge; outermost scope installs it, nested scopes reuse or reinstall as needed. The runner's control listener connects only while this context is active.
+- `is_prefect_sigterm_handler_installed() -> bool` — check (under lock) whether Prefect's bridge is the active SIGTERM handler.
+- `can_ack_control_intent() -> bool` — check (under the same lock) whether the child can safely acknowledge a queued control intent.
+- `commit_control_intent_and_ack(commit_intent, clear_intent, send_ack, trigger_cancel)` — atomically commit a control intent and write the ack byte to the runner, all under `_prefect_sigterm_bridge_lock`.
+
+## Pitfalls
+
+- **Never access `EngineContext.run_results` directly via `id(obj)`.** Always call `get_state_for_result(obj)` — the accessor verifies object identity in addition to the ID match, avoiding false hits when Python reuses an id for a different object after GC.
+- **All SIGTERM-state reads and writes must hold `_prefect_sigterm_bridge_lock`.** The lock is a `threading.RLock` that serializes handler install/restore with ack writes. Reading `signal.getsignal(SIGTERM)` outside the lock creates a TOCTOU race where the handler is restored after the child decides it's safe to ack but before the runner observes the ack byte.

prefect_client-3.6.28.dev1/src/prefect/utilities/filesystem/AGENTS.md

@@ -0,0 +1,17 @@
+# filesystem
+
+File path utilities, pathspec-based filtering, and local filesystem context managers.
+
+## Purpose & Scope
+
+Path normalization, file filtering compatible with `.gitignore`/`.prefectignore`-style pattern lists (`filter_files`), open-file-limit introspection (`get_open_file_limit`), and a `tmpchdir` context manager for scoped working-directory changes.
+
+## Entry Points
+
+- `filter_files(root, ignore_patterns, include_dirs=True) -> set[str]` — return the set of paths under `root` that should be *ignored* according to pathspec patterns. Intended as input to `shutil.copytree`'s `ignore` callback.
+- `tmpchdir(path)` — context manager that `chdir`s into `path` and restores the previous cwd on exit.
+- `get_open_file_limit() -> int` — platform-specific maximum open-file count, with a conservative Windows default.
+
+## Pitfalls
+
+- **`filter_files` with `include_dirs=True` (the default) always includes all ancestor directories of matched files**, even if those directories weren't directly matched by the ignore patterns. This ensures `shutil.copytree`'s `ignore_func` doesn't skip directories containing files that should be copied. Side effect: callers expecting only pathspec-matched entries will receive additional directory paths. The parent-dir expansion does NOT run when `include_dirs=False`.

prefect_client-3.6.28.dev1/src/prefect/utilities/processutils/AGENTS.md

@@ -0,0 +1,22 @@
+# processutils
+
+Subprocess execution, output streaming, command serialization, and signal forwarding.
+
+## Purpose & Scope
+
+Cross-platform subprocess primitives used by workers, runners, bundle execution, and the CLI. Handles process launch (`run_process`), output consumption (`consume_process_output`, `stream_text`), and platform-neutral command serialization (`command_to_string`, `command_from_string`).
+
+## Entry Points
+
+- `sanitize_subprocess_env(env) -> dict[str, str]` — strip `None` values from an env mapping before passing to subprocess launch APIs; `None` means "omit this key", which `subprocess` and `anyio.open_process` do not accept.
+- `run_process(command, ...)` — async subprocess runner with output streaming and signal forwarding.
+- `consume_process_output(process, stdout_sink, stderr_sink)` — drain a running process's streams into writers.
+- `stream_text(source, *sinks)` — fan out a text stream to multiple sinks.
+- `command_to_string(command: list[str]) -> str` / `command_from_string(s: str) -> list[str]` — platform-neutral serialize/deserialize of command arrays for storage and cross-platform bundles.
+- `get_sys_executable() -> str` — `sys.executable` with platform-appropriate handling (see pitfalls).
+
+## Pitfalls
+
+- **Non-UTF-8 subprocess output is silently replaced.** `consume_process_output` and `stream_text` (via `TextReceiveStream(errors="replace")`) replace invalid bytes with the Unicode replacement character `\ufffd` rather than raising. If captured output contains `\ufffd`, the subprocess emitted bytes that were not valid UTF-8.
+- **`command_to_string` always uses POSIX quoting (`shlex.join`), even on Windows.** This is intentional for platform-neutral storage — bundle commands are serialized by one platform and may be deserialized by another. `command_from_string` uses a dual-path approach: if the string was POSIX-serialized by Prefect (round-trips cleanly through `shlex.split`/`shlex.join`), it uses POSIX parsing; otherwise it falls back to native Windows command-line parsing (`CommandLineToArgvW`). Do not use `" ".join(command)` or `shlex.split(command)` directly when working with stored Prefect commands — use these helpers instead.
+- **`get_sys_executable()` no longer quotes the Python path on Windows.** It previously returned `'"path/to/python"'` (with embedded quotes) on Windows; now it returns the raw path. Code relying on the old quoted form (e.g., joining into a shell string) will break — use `subprocess.list2cmdline` or `command_to_string` for shell-safe serialization instead.

prefect_client-3.6.28.dev1/src/prefect/utilities/schema_tools/AGENTS.md

@@ -0,0 +1,53 @@
+# schema_tools
+
+Hydration and validation of `__prefect_kind` template structures used in deployment parameters and automation action payloads.
+
+## Purpose & Scope
+
+Resolves `__prefect_kind` structures into real Python values (hydration) and validates JSON Schema parameter specs with first-class support for Prefect's placeholder types (validation).
+
+## 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. `hydrate()` 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 this module** — it's used client-side too. `HydrationContext.build()` is an explicit exception (async, server-only); the rest of `hydration.py` must remain importable without a running server.
+
+## Pitfalls
+
+- **`HydrationContext` workspace variables are loaded once at build time.** Stale contexts don't reflect variable updates made after context creation.

prefect_client-3.6.28.dev1/src/prefect/utilities/templating/AGENTS.md

@@ -0,0 +1,19 @@
+# templating
+
+Placeholder detection and value application for Prefect's `{{ }}` templating used in block references, workspace variables, and parameter templating.
+
+## Purpose & Scope
+
+Finds `{{ ... }}` placeholders inside nested structures (`find_placeholders`) and substitutes their resolved values back in (`apply_values`). Distinguishes between standard placeholders, block-document references, and environment variable placeholders via `PlaceholderType`.
+
+Note: this module is *not* a Jinja renderer. For Jinja hydration of `__prefect_kind: "jinja"` structures, see `../schema_tools/`. For user-facing Jinja templates in automation actions, see `prefect/server/utilities/user_templates.py`.
+
+## Entry Points
+
+- `find_placeholders(template) -> set[Placeholder]` — walk any dict/list/str and collect `{{ name }}` placeholders, classified by `PlaceholderType`.
+- `apply_values(template, values) -> template` — substitute resolved values back into the nested structure.
+- `determine_placeholder_type(name) -> PlaceholderType` — classify a placeholder name as STANDARD / BLOCK_DOCUMENT / ENV_VAR.
+
+## Pitfalls
+
+- **`resolve_block_document_references` raises `ValueError` for malformed block placeholders.** Placeholders must follow the format `prefect.blocks.<block-type-slug>.<block-document-name>` (at least two dot-separated parts after the prefix). A placeholder like `{{ prefect.blocks.only-type }}` (missing the document name) raises `ValueError` before any network call is made.

prefect_client-3.6.27.dev5/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.6.27.dev5"
-__build_date__ = "2026-04-16 21:12:02.023498+00:00"
-__git_commit__ = "03b8cad670c313d68d0bf8e87b0256e525713aa5"
-__dirty__ = False

prefect_client-3.6.27.dev5/src/prefect/utilities/AGENTS.md

@@ -1,83 +0,0 @@
-# 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
-- `processutils.py` — Subprocess execution, output streaming, and command serialization helpers (`run_process`, `consume_process_output`, `stream_text`, `command_to_string`, `command_from_string`)
-- `pydantic.py` — Pydantic v1/v2 compatibility shims
-- `templating.py` — Jinja template utilities and `maybe_template()` detection
-- `filesystem.py` — File filtering (`filter_files`), path normalization, and `tmpchdir` context manager
-- `engine.py` — Result-to-state linking and identity-verified lookup for `EngineContext`; provides `link_state_to_result`, `get_state_for_result`, `link_state_to_flow_run_result`, and `link_state_to_task_run_result`
-
-## 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`.
-- **`resolve_block_document_references` raises `ValueError` for malformed block placeholders.** Placeholders must follow the format `prefect.blocks.<block-type-slug>.<block-document-name>` (at least two dot-separated parts after the prefix). A placeholder like `{{ prefect.blocks.only-type }}` (missing the document name) raises `ValueError` before any network call is made.
-- `HydrationContext` workspace variables are loaded once at build time. Stale contexts don't reflect variable updates made after context creation.
-- **Non-UTF-8 subprocess output is silently replaced.** `consume_process_output` and `stream_text` (via `TextReceiveStream(errors="replace")`) replace invalid bytes with the Unicode replacement character `\ufffd` rather than raising. If captured output contains `\ufffd`, the subprocess emitted bytes that were not valid UTF-8.
-- **`parameters_to_args_kwargs` adjusts the positional/keyword split based on the wrapper's signature, not the wrapped function's.** For `@functools.wraps`-decorated callables, it inspects the *wrapper* (via `follow_wrapped=False`) to count how many positional slots are actually available and routes excess parameters to `**kwargs`. This means `args` and `kwargs` from this function are shaped for the *wrapper* call, not the inner function — callers must not assume all POSITIONAL_OR_KEYWORD parameters end up in `args`.
-- **`parameters_to_args_kwargs` skips the positional-to-keyword rewrite entirely when the function signature contains `*args`.** Inserting KEYWORD_ONLY parameters before a VAR_POSITIONAL parameter is invalid in Python, so the original signature is used as-is in that case.
-- **Passing the same key in both an explicit parameter and a `**kwargs` dict raises `TypeError`.** `parameters_to_args_kwargs` detects when a VAR_KEYWORD (`**kwargs`) dict contains a key that also appears as an explicit parameter and raises rather than silently letting the variadic entry win. Exception: POSITIONAL_ONLY parameters are exempt because `fn(1, **{'a': 2})` is legal when `a` is positional-only.
-- **`filter_files` with `include_dirs=True` (the default) always includes all ancestor directories of matched files**, even if those directories weren't directly matched by the ignore patterns. This ensures `shutil.copytree`'s `ignore_func` doesn't skip directories containing files that should be copied. Side effect: callers expecting only pathspec-matched entries will receive additional directory paths. The parent-dir expansion does NOT run when `include_dirs=False`.
-- **`generate_parameter_schema` silently downgrades unsupported parameter types to `Any`.** When a parameter's type raises `ValueError`, `TypeError`, or `PydanticInvalidForJsonSchema` during JSON schema generation (e.g., `Callable`, custom types Pydantic can't serialize), the type is replaced with `Any` in the output schema without warning. If a flow parameter shows up as `Any` in the schema, the declared type is not JSON-schema-compatible.
-- **Never access `EngineContext.run_results` directly via `id(obj)`.** Always call `get_state_for_result(obj)`.
-- **`command_to_string` always uses POSIX quoting (`shlex.join`), even on Windows.** This is intentional for platform-neutral storage — bundle commands are serialized by one platform and may be deserialized by another. `command_from_string` uses a dual-path approach: if the string was POSIX-serialized by Prefect (round-trips cleanly through `shlex.split`/`shlex.join`), it uses POSIX parsing; otherwise it falls back to native Windows command-line parsing (`CommandLineToArgvW`). Do not use `" ".join(command)` or `shlex.split(command)` directly when working with stored Prefect commands — use these helpers instead.
-- **`get_sys_executable()` no longer quotes the Python path on Windows.** It previously returned `'"path/to/python"'` (with embedded quotes) on Windows; now it returns the raw path. Code relying on the old quoted form (e.g., joining into a shell string) will break — use `subprocess.list2cmdline` or `command_to_string` for shell-safe serialization instead.