prefect-client 3.6.24.dev5__tar.gz → 3.6.25.dev1__tar.gz

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.24.dev5
+Version: 3.6.25.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.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/AGENTS.md

@@ -49,5 +49,6 @@ Use `get_logger()` from `prefect.logging` instead of raw `logging.getLogger()`
 - `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)
+- `blocks/` → Server-persisted configuration objects for external service credentials and settings (see blocks/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.25.dev1/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.25.dev1"
+__build_date__ = "2026-03-28 08:16:14.043192+00:00"
+__git_commit__ = "a4ddbe3b3c3499647454b5185ca94dc16aa70a76"
+__dirty__ = False

prefect_client-3.6.25.dev1/src/prefect/blocks/AGENTS.md

@@ -0,0 +1,48 @@
+# Blocks
+
+Reusable, server-persisted configuration objects for connecting workflows to external services. Blocks store credentials and settings securely and are shared across runs via the Prefect server.
+
+## Purpose & Scope
+
+Blocks handle configuration lifecycle: define fields in Python, register schema with the server, save/load named instances, and serialize secrets safely. They do NOT execute workflow logic — that belongs in flows and tasks. Block subclasses define the interface; `core.py` handles all server interaction.
+
+## Entry Points & Contracts
+
+- `Block` (`core.py`) — base class for all blocks. Subclass it, declare Pydantic fields, optionally set `_block_type_slug`, `_logo_url`, etc.
+- `abstract.py` — abstract interfaces (`CredentialsBlock`, `NotificationBlock`, `DatabaseBlock`, `ObjectStorageBlock`, `SecretBlock`, `JobBlock`) to signal capability and constrain API shape.
+- `system.py` — built-in `Secret[T]` block for storing a single secret value.
+- `notifications.py` — `SlackWebhook` and Apprise-based notification blocks.
+- `webhook.py` — `Webhook` block for calling HTTP endpoints.
+- `redis.py` — `RedisStorageContainer` implementing `WritableFileSystem`.
+
+## Usage Patterns
+
+**Define a block:**
+```python
+class MyBlock(Block):
+    _block_type_slug = "my-block"
+    api_key: SecretStr
+    endpoint: str
+```
+
+**Save and load:**
+```python
+await MyBlock(api_key="...", endpoint="...").save("prod")
+block = await MyBlock.load("prod")
+```
+
+**Sync/async dispatch:** All I/O methods (`save`, `load`, `register_type_and_schema`, `delete`) use `@async_dispatch` — the same method name works in sync and async contexts.
+
+## Anti-Patterns
+
+- **Don't call `register_type_and_schema()` manually before `save()`** — `save()` calls it automatically and handles idempotency.
+- **Don't change `_block_type_slug` after a block has been registered** — the slug is the server-side primary key; renaming it creates a new block type and orphans existing documents.
+- **Don't use `load(validate=False)` as the normal path** — it bypasses validation and leaves missing fields as `None`. It exists only for schema migration scenarios.
+
+## Pitfalls
+
+- **`position` in JSON schema** — `model_json_schema()` injects a `position` key (0-based field declaration order) into every property, including nested block definitions. This key affects the schema checksum. Adding or reordering fields changes the checksum and invalidates previously stored schema references.
+- **Schema checksum stability** — the checksum covers field definitions including `position`. Any field addition, removal, or reorder creates a new schema version on the server.
+- **Secret fields use dot-notation paths** — `"credentials.api_key"` means a nested field is secret; `"passwords.*"` means all values under that key are secret. The `secret_fields` list in the schema drives serialization obfuscation.
+- **Nested blocks are registered transitively** — `register_type_and_schema()` walks all field annotations recursively. A deeply nested block that fails registration will surface an error at the outermost `save()` call.
+- **Sync/async paths must stay in lockstep** — `_save_sync` and `asave` / `_save` must produce identical results. Changes to one must be mirrored in the other.

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/blocks/core.py

@@ -428,21 +428,28 @@ class Block(BaseModel, ABC):
         if (ctx := info.context) and ctx.get("include_secrets") is True:
             # Add serialization mode to context so handle_secret_render knows how to process nested models
             ctx["serialization_mode"] = info.mode
+            ctx["by_alias"] = info.by_alias
 
-            for field_name in type(self).model_fields:
+            for field_name, field_info in type(self).model_fields.items():
                 field_value = getattr(self, field_name)
 
-                # In JSON mode, skip fields that don't contain secrets
+                # Determine the correct key in the serialized dict,
+                # respecting alias settings to avoid creating duplicate
+                # entries (e.g. both "schema" and "schema_" for a field
+                # defined as `schema_: str = Field(alias="schema")`).
+                alias = field_info.serialization_alias or field_info.alias
+                if info.by_alias and alias:
+                    key = alias
+                else:
+                    key = field_name
+
+                # Skip fields that don't contain secrets
                 # as they're already properly serialized by the handler
-                if (
-                    info.mode == "json"
-                    and field_name in jsonable_self
-                    and not self._field_has_secrets(field_name)
-                ):
+                if key in jsonable_self and not self._field_has_secrets(field_name):
                     continue
 
                 # For all other fields, use visit_collection with handle_secret_render
-                jsonable_self[field_name] = visit_collection(
+                jsonable_self[key] = visit_collection(
                     expr=field_value,
                     visit_fn=partial(handle_secret_render, context=ctx),
                     return_data=True,
@@ -1946,6 +1953,54 @@ class Block(BaseModel, ABC):
 
         return f"prefect.blocks.{self.get_block_type_slug()}.{block_document_name}"
 
+    @classmethod
+    def _inject_field_positions(
+        cls,
+        schema: dict[str, Any],
+        model_cls: type["Block"],
+        by_alias: bool,
+    ) -> None:
+        """Add a 'position' key to each property in the schema based on field declaration order."""
+        if "properties" not in schema:
+            return
+        for position, field_name in enumerate(model_cls.model_fields):
+            field_info = model_cls.model_fields[field_name]
+            alias = field_info.alias or field_name
+            key = alias if by_alias else field_name
+            if key in schema["properties"]:
+                schema["properties"][key]["position"] = position
+
+    @classmethod
+    def _collect_nested_block_types(
+        cls, model_cls: type["Block"]
+    ) -> dict[str, type["Block"]]:
+        """Return a mapping of class name → Block subclass for all nested blocks."""
+        result: dict[str, type["Block"]] = {}
+
+        for field in model_cls.model_fields.values():
+            annotation = field.annotation
+            if annotation is None:
+                continue
+            cls._walk_annotation_for_blocks(annotation, result)
+
+        return result
+
+    @classmethod
+    def _walk_annotation_for_blocks(
+        cls,
+        annotation: type,
+        result: dict[str, type["Block"]],
+    ) -> None:
+        if Block.is_block_class(annotation):
+            if annotation.__name__ not in result:
+                result[annotation.__name__] = annotation
+                # recurse into the nested block's own fields
+                for nested in cls._collect_nested_block_types(annotation).items():
+                    result.setdefault(nested[0], nested[1])
+        if get_origin(annotation) in NestedTypes:
+            for arg in get_args(annotation):
+                cls._walk_annotation_for_blocks(arg, result)
+
     @classmethod
     def model_json_schema(
         cls,
@@ -1964,6 +2019,19 @@ class Block(BaseModel, ABC):
             schema["definitions"] = schema.pop("$defs")
 
         schema = remove_nested_keys(["additionalProperties"], schema)
+
+        # Add position to top-level properties based on field declaration order
+        cls._inject_field_positions(schema, cls, by_alias)
+
+        # Add position to nested block definitions
+        if "definitions" in schema:
+            nested_blocks = cls._collect_nested_block_types(cls)
+            for def_name, def_schema in schema["definitions"].items():
+                if def_name in nested_blocks:
+                    cls._inject_field_positions(
+                        def_schema, nested_blocks[def_name], by_alias
+                    )
+
         return schema
 
     @classmethod

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/blocks/notifications.py

@@ -496,8 +496,7 @@ class TwilioSMS(AbstractAppriseNotificationBlock):
     to_phone_numbers: list[str] = Field(
         default=...,
         description="A list of valid Twilio phone number(s) to send the message to.",
-        # not wrapped in brackets because of the way UI displays examples; in code should be ["18004242424"]
-        examples=["18004242424"],
+        examples=['["18004242424", "18004242425"]'],
     )
 
     def block_initialization(self) -> None:
@@ -1056,7 +1055,7 @@ class SendgridEmail(AbstractAppriseNotificationBlock):
         default=...,
         title="Recipient emails",
         description="Email ids of all recipients.",
-        examples=['"recipient1@gmail.com"'],
+        examples=['["recipient1@gmail.com", "recipient2@gmail.com"]'],
     )
 
     def block_initialization(self) -> None:

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/AGENTS.md

@@ -16,7 +16,9 @@ Does NOT define concurrency limits (server-side in `server/`). Does NOT handle t
 
 **`strict=False` (default):** logs a warning if the named limit doesn't exist, but proceeds. `strict=True` raises `ConcurrencySlotAcquisitionError`.
 
-**Lease renewal:** `_leases.py` runs a background loop that renews immediately on entry, then sleeps for 75% of `lease_duration` between renewals. Each renewal call uses `@retry_async_fn(max_attempts=3)` for transient failures. If all 3 attempts fail, the background task raises and a done-callback either cancels execution (`raise_on_lease_renewal_failure=True`) or logs a warning.
+**`raise_on_lease_renewal_failure` (public parameter):** Controls lease renewal failure behavior independently from `strict`. When `None` (default), falls back to the value of `strict` for backward compatibility. Set to `False` to let long-running tasks continue even if a transient renewal error occurs; set to `True` to terminate immediately on renewal failure regardless of `strict`. This means `strict=True, raise_on_lease_renewal_failure=False` gives strict slot acquisition but non-fatal renewal failures, and vice versa.
+
+**Lease renewal:** `_leases.py` runs a background loop that renews immediately on entry, then sleeps for 75% of `lease_duration` between renewals. Each renewal call uses `@retry_async_fn(max_attempts=3)` for transient failures. If all 3 attempts fail, the background task raises and a done-callback either cancels execution or logs a warning, depending on `raise_on_lease_renewal_failure`.
 
 **Sync/async lockstep invariant:** `asyncio.py`/`sync.py` and `_asyncio.py`/`_sync.py` are parallel implementations. Any behavior change to one must be mirrored in the other.
 

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/_asyncio.py

@@ -167,6 +167,7 @@ async def concurrency(
     strict: bool = False,
     holder: "Optional[ConcurrencyLeaseHolder]" = None,
     suppress_warnings: bool = False,
+    raise_on_lease_renewal_failure: Optional[bool] = None,
 ) -> AsyncGenerator[None, None]:
     """
     Internal version of the `concurrency` context manager. The public version is located in `prefect.concurrency.asyncio`.
@@ -182,6 +183,11 @@ async def concurrency(
             Defaults to `False`.
         holder: A dictionary containing information about the holder of the concurrency slots.
             Typically includes 'type' and 'id' keys.
+        raise_on_lease_renewal_failure: Controls whether to terminate execution when lease
+            renewal fails. When `None` (default), follows the `strict` parameter for
+            backward compatibility. Set to `False` to allow long-running tasks to continue
+            even if a transient lease renewal error occurs. Set to `True` to terminate
+            execution immediately on renewal failure.
 
     Raises:
         TimeoutError: If the slots are not acquired within the given timeout.
@@ -227,7 +233,9 @@ async def concurrency(
         async with amaintain_concurrency_lease(
             response.lease_id,
             lease_duration,
-            raise_on_lease_renewal_failure=strict,
+            raise_on_lease_renewal_failure=raise_on_lease_renewal_failure
+            if raise_on_lease_renewal_failure is not None
+            else strict,
             suppress_warnings=suppress_warnings,
         ):
             yield

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/_leases.py

@@ -79,19 +79,31 @@ def maintain_concurrency_lease(
                     logger = get_logger("concurrency")
                 if raise_on_lease_renewal_failure:
                     logger.error(
-                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation.",
+                        "Concurrency lease renewal failed - slots are no longer reserved. "
+                        "Terminating execution to prevent over-allocation. "
+                        "Lease ID: %s, exception: %s",
+                        lease_id,
+                        exc,
                         exc_info=(type(exc), exc, exc.__traceback__),
                     )
                     assert cancel_scope.cancel()
                 else:
                     if suppress_warnings:
                         logger.debug(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            "Concurrency lease renewal failed - slots are no longer reserved. "
+                            "Execution will continue, but concurrency limits may be exceeded. "
+                            "Lease ID: %s, exception: %s",
+                            lease_id,
+                            exc,
                             exc_info=(type(exc), exc, exc.__traceback__),
                         )
                     else:
                         logger.warning(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            "Concurrency lease renewal failed - slots are no longer reserved. "
+                            "Execution will continue, but concurrency limits may be exceeded. "
+                            "Lease ID: %s, exception: %s",
+                            lease_id,
+                            exc,
                             exc_info=(type(exc), exc, exc.__traceback__),
                         )
 
@@ -137,19 +149,31 @@ async def amaintain_concurrency_lease(
                     logger = get_logger("concurrency")
                 if raise_on_lease_renewal_failure:
                     logger.error(
-                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation.",
+                        "Concurrency lease renewal failed - slots are no longer reserved. "
+                        "Terminating execution to prevent over-allocation. "
+                        "Lease ID: %s, exception: %s",
+                        lease_id,
+                        exc,
                         exc_info=(type(exc), exc, exc.__traceback__),
                     )
                     cancel_scope.cancel()
                 else:
                     if suppress_warnings:
                         logger.debug(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            "Concurrency lease renewal failed - slots are no longer reserved. "
+                            "Execution will continue, but concurrency limits may be exceeded. "
+                            "Lease ID: %s, exception: %s",
+                            lease_id,
+                            exc,
                             exc_info=(type(exc), exc, exc.__traceback__),
                         )
                     else:
                         logger.warning(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            "Concurrency lease renewal failed - slots are no longer reserved. "
+                            "Execution will continue, but concurrency limits may be exceeded. "
+                            "Lease ID: %s, exception: %s",
+                            lease_id,
+                            exc,
                             exc_info=(type(exc), exc, exc.__traceback__),
                         )
 

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/_sync.py

@@ -81,6 +81,7 @@ def concurrency(
     strict: bool = False,
     holder: "Optional[ConcurrencyLeaseHolder]" = None,
     suppress_warnings: bool = False,
+    raise_on_lease_renewal_failure: Optional[bool] = None,
 ) -> Generator[None, None, None]:
     """A context manager that acquires and releases concurrency slots from the
     given concurrency limits.
@@ -96,6 +97,11 @@ def concurrency(
             Defaults to `False`.
         holder: A dictionary containing information about the holder of the concurrency slots.
             Typically includes 'type' and 'id' keys.
+        raise_on_lease_renewal_failure: Controls whether to terminate execution when lease
+            renewal fails. When `None` (default), follows the `strict` parameter for
+            backward compatibility. Set to `False` to allow long-running tasks to continue
+            even if a transient lease renewal error occurs. Set to `True` to terminate
+            execution immediately on renewal failure.
 
     Raises:
         TimeoutError: If the slots are not acquired within the given timeout.
@@ -143,7 +149,9 @@ def concurrency(
         with maintain_concurrency_lease(
             acquisition_response.lease_id,
             lease_duration,
-            raise_on_lease_renewal_failure=strict,
+            raise_on_lease_renewal_failure=raise_on_lease_renewal_failure
+            if raise_on_lease_renewal_failure is not None
+            else strict,
             suppress_warnings=suppress_warnings,
         ):
             yield

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/asyncio.py

@@ -29,6 +29,7 @@ async def concurrency(
     lease_duration: float = 300,
     strict: bool = False,
     holder: "Optional[ConcurrencyLeaseHolder]" = None,
+    raise_on_lease_renewal_failure: Optional[bool] = None,
 ) -> AsyncGenerator[None, None]:
     """A
     context manager that acquires and releases concurrency slots from the
@@ -45,6 +46,11 @@ async def concurrency(
             Defaults to `False`.
         holder: A dictionary containing information about the holder of the concurrency slots.
             Typically includes 'type' and 'id' keys.
+        raise_on_lease_renewal_failure: Controls whether to terminate execution when lease
+            renewal fails. When `None` (default), follows the `strict` parameter for
+            backward compatibility. Set to `False` to allow long-running tasks to continue
+            even if a transient lease renewal error occurs. Set to `True` to terminate
+            execution immediately on renewal failure.
 
     Raises:
         TimeoutError: If the slots are not acquired within the given timeout.
@@ -72,6 +78,7 @@ async def concurrency(
         strict=strict,
         holder=holder,
         suppress_warnings=False,
+        raise_on_lease_renewal_failure=raise_on_lease_renewal_failure,
     ):
         yield
 

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/concurrency/sync.py

@@ -27,6 +27,7 @@ def concurrency(
     lease_duration: float = 300,
     strict: bool = False,
     holder: "Optional[ConcurrencyLeaseHolder]" = None,
+    raise_on_lease_renewal_failure: Optional[bool] = None,
 ) -> Generator[None, None, None]:
     """A context manager that acquires and releases concurrency slots from the
     given concurrency limits.
@@ -42,6 +43,11 @@ def concurrency(
             Defaults to `False`.
         holder: A dictionary containing information about the holder of the concurrency slots.
             Typically includes 'type' and 'id' keys.
+        raise_on_lease_renewal_failure: Controls whether to terminate execution when lease
+            renewal fails. When `None` (default), follows the `strict` parameter for
+            backward compatibility. Set to `False` to allow long-running tasks to continue
+            even if a transient lease renewal error occurs. Set to `True` to terminate
+            execution immediately on renewal failure.
 
     Raises:
         TimeoutError: If the slots are not acquired within the given timeout.
@@ -69,6 +75,7 @@ def concurrency(
         strict=strict,
         holder=holder,
         suppress_warnings=False,
+        raise_on_lease_renewal_failure=raise_on_lease_renewal_failure,
     ):
         yield
 

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/context.py

@@ -60,6 +60,53 @@ if TYPE_CHECKING:
     from prefect.tasks import Task
 
 
+class _ContextWrappedCallable:
+    """Picklable callable that hydrates Prefect context before calling the
+    wrapped function.  The serialized context is stored as cloudpickle
+    bytes so that standard pickle (used by `multiprocessing`) can handle it."""
+
+    def __init__(
+        self, fn: Callable[..., Any], serialized_context: dict[str, Any]
+    ) -> None:
+        import cloudpickle
+
+        self.fn = fn
+        self._ctx_bytes = cloudpickle.dumps(serialized_context)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        import cloudpickle
+
+        ctx = cloudpickle.loads(self._ctx_bytes)
+        with hydrated_context(ctx):
+            return self.fn(*args, **kwargs)
+
+
+def with_context(fn: Callable[..., Any]) -> _ContextWrappedCallable:
+    """Wrap a function so it runs with the current Prefect context when
+    called in a subprocess.
+
+    Use this to enable `get_run_logger()` and other context-dependent
+    APIs in functions executed via `multiprocessing.Pool`,
+    `ProcessPoolExecutor`, or `multiprocessing.Process`.
+
+    Example:
+        ```python
+        from prefect.context import with_context
+
+        def worker(item):
+            logger = get_run_logger()
+            logger.info(f"Processing {item}")
+
+        @task
+        def my_task():
+            with multiprocessing.Pool() as pool:
+                pool.map(with_context(worker), items)
+        ```
+    """
+    ctx = serialize_context()
+    return _ContextWrappedCallable(fn, ctx)
+
+
 def serialize_context(
     asset_ctx_kwargs: Union[dict[str, Any], None] = None,
 ) -> dict[str, Any]:

{prefect_client-3.6.24.dev5 → prefect_client-3.6.25.dev1}/src/prefect/docker/__init__.py

@@ -17,4 +17,10 @@ def __getattr__(name: str) -> object:
         module, attr = _public_api[name]
         return getattr(import_module(module), attr)
 
+    # Allow submodule imports (e.g. `from prefect.docker._buildx import ...`)
+    try:
+        return import_module(f"{__name__}.{name}")
+    except ModuleNotFoundError:
+        pass
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")