prefect-client 3.8.4.dev6__tar.gz → 3.8.5__tar.gz

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.8.4.dev6
+Version: 3.8.5
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -64,7 +64,7 @@ Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<17.0,>=15.0.1
 Requires-Dist: whenever<0.11.0,>=0.7.3; python_version >= '3.13'
 Provides-Extra: notifications
-Requires-Dist: apprise<2.0.0,>=1.1.0; extra == 'notifications'
+Requires-Dist: apprise<2.0.0,>=1.13.0; extra == 'notifications'
 Description-Content-Type: text/markdown
 
 <p align="center"><img src="https://github.com/PrefectHQ/prefect/assets/3407835/c654cbc6-63e8-4ada-a92a-efd2f8f24b85" width=1000></p>

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/pyproject.toml

@@ -74,7 +74,7 @@ Documentation = "https://docs.prefect.io"
 Source = "https://github.com/PrefectHQ/prefect"
 Tracker = "https://github.com/PrefectHQ/prefect/issues"
 [project.optional-dependencies]
-notifications = ["apprise>=1.1.0, <2.0.0"]
+notifications = ["apprise>=1.13.0, <2.0.0"]
 
 
 [tool.hatch.version]

prefect_client-3.8.5/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.5"
+__build_date__ = "2026-09-03 21:26:27.614930+00:00"
+__git_commit__ = "486175075d96269ea8a528f2018ea4329d249cc2"
+__dirty__ = False

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/_internal/attempt_control.py

@@ -48,7 +48,7 @@ class EngineOutcomeReceipt:
     state_name: str | None = None
 
     def __post_init__(self) -> None:
-        if not isinstance(self.disposition, EngineDisposition):
+        if not isinstance(self.disposition, EngineDisposition):  # pyright: ignore[reportUnnecessaryIsInstance]
             raise TypeError("Receipt disposition must be an EngineDisposition")
         state_fields = (self.state_id, self.state_type, self.state_name)
         if self.disposition is EngineDisposition.STATE_REPORTED:

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/bundles/__init__.py

@@ -11,6 +11,7 @@ import logging
 import multiprocessing
 import multiprocessing.context
 import os
+import stat
 import subprocess
 import sys
 import tempfile
@@ -395,6 +396,41 @@ def _pickle_local_modules_by_value(flow: Flow[Any, Any]):
                 )
 
 
+def _resolve_include_files_base_dir(value: Path | str) -> Path:
+    """Resolve and validate an explicitly configured include-files base directory."""
+    try:
+        candidate = Path(value).expanduser()
+    except RuntimeError as exc:
+        raise ValueError(
+            f"Invalid include_files_base_dir {str(value)!r}: {exc}"
+        ) from exc
+
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+
+    try:
+        base_dir = candidate.resolve(strict=True)
+        if not stat.S_ISDIR(base_dir.stat().st_mode):
+            raise ValueError(
+                f"include_files_base_dir {str(value)!r} must be a directory."
+            )
+
+        # Open the directory to verify that collection can read it. `os.access` is
+        # not sufficient because its result can differ from the actual operation.
+        with os.scandir(base_dir):
+            pass
+    except FileNotFoundError as exc:
+        raise ValueError(
+            f"include_files_base_dir {str(value)!r} does not exist."
+        ) from exc
+    except NotADirectoryError as exc:
+        raise ValueError(
+            f"include_files_base_dir {str(value)!r} must be a directory."
+        ) from exc
+
+    return base_dir
+
+
 def create_bundle_for_flow_run(
     flow: Flow[Any, Any],
     flow_run: FlowRun,
@@ -463,12 +499,16 @@ def create_bundle_for_flow_run(
     files_key: str | None = None
     zip_path: Path | None = None
     include_files = getattr(flow, "include_files", None)
+    include_files_base_dir = getattr(flow, "include_files_base_dir", None)
 
     if include_files:
         try:
-            # Get base directory from flow file location
-            flow_file = Path(inspect.getfile(flow.fn))
-            base_dir = flow_file.parent.resolve()
+            if include_files_base_dir is None:
+                # Preserve the existing default relative to the flow definition.
+                flow_file = Path(inspect.getfile(flow.fn))
+                base_dir = flow_file.parent.resolve()
+            else:
+                base_dir = _resolve_include_files_base_dir(include_files_base_dir)
 
             # Pipeline: collect -> filter -> check -> zip
             collector = FileCollector(base_dir)
@@ -498,6 +538,8 @@ def create_bundle_for_flow_run(
                         files_key,
                     )
         except (OSError, TypeError, AttributeError) as e:
+            if include_files_base_dir is not None:
+                raise
             # Handle cases where flow has no file (dynamic flow) or other IO errors
             logger.warning(
                 "Could not collect included files: %s. Files will not be bundled.",

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/bundles/_ignore_filter.py

@@ -87,23 +87,9 @@ def _read_ignore_file(path: Path) -> list[str]:
     return [line for line in lines if line.strip() and not line.startswith("#")]
 
 
-def load_ignore_patterns(flow_dir: Path) -> list[str]:
-    """
-    Load patterns from cascading .prefectignore files.
-
-    Load order (patterns combined via union):
-    1. Project root .prefectignore (if found via pyproject.toml detection)
-    2. Flow directory .prefectignore (if different from project root)
-
-    Missing .prefectignore files emit debug log, not warning.
-
-    Args:
-        flow_dir: Flow file's directory (base for relative paths).
-
-    Returns:
-        Combined list of pattern strings from all .prefectignore files.
-    """
-    patterns: list[str] = []
+def _load_ignore_pattern_sources(flow_dir: Path) -> list[tuple[Path, list[str]]]:
+    """Load ignore patterns together with the directory they are relative to."""
+    sources: list[tuple[Path, list[str]]] = []
 
     # 1. Find and load project root .prefectignore
     project_root = find_project_root(flow_dir)
@@ -111,7 +97,7 @@ def load_ignore_patterns(flow_dir: Path) -> list[str]:
         project_ignore = project_root / ".prefectignore"
         if project_ignore.exists():
             logger.debug(f"Loading .prefectignore from project root: {project_ignore}")
-            patterns.extend(_read_ignore_file(project_ignore))
+            sources.append((project_root.resolve(), _read_ignore_file(project_ignore)))
         else:
             logger.debug(f"No .prefectignore found at project root: {project_root}")
     else:
@@ -123,11 +109,34 @@ def load_ignore_patterns(flow_dir: Path) -> list[str]:
         # Only load if different from project root's .prefectignore
         if project_root is None or flow_dir.resolve() != project_root.resolve():
             logger.debug(f"Loading .prefectignore from flow directory: {flow_ignore}")
-            patterns.extend(_read_ignore_file(flow_ignore))
+            sources.append((flow_dir.resolve(), _read_ignore_file(flow_ignore)))
     else:
         logger.debug(f"No .prefectignore found in flow directory: {flow_dir}")
 
-    return patterns
+    return sources
+
+
+def load_ignore_patterns(flow_dir: Path) -> list[str]:
+    """
+    Load patterns from cascading .prefectignore files.
+
+    Load order (later matching patterns override earlier patterns):
+    1. Project root .prefectignore (if found via pyproject.toml detection)
+    2. Flow directory .prefectignore (if different from project root)
+
+    Missing .prefectignore files emit debug log, not warning.
+
+    Args:
+        flow_dir: Flow file's directory (base for relative paths).
+
+    Returns:
+        Combined list of pattern strings from all .prefectignore files.
+    """
+    return [
+        pattern
+        for _, patterns in _load_ignore_pattern_sources(flow_dir)
+        for pattern in patterns
+    ]
 
 
 class IgnoreFilter:
@@ -155,14 +164,16 @@ class IgnoreFilter:
             flow_dir: Base directory for file collection (typically flow file's parent).
         """
         self.flow_dir = flow_dir.resolve()
-        self._spec: pathspec.GitIgnoreSpec | None = None
+        self._specs: list[tuple[Path, pathspec.GitIgnoreSpec]] = []
         self._load_patterns()
 
     def _load_patterns(self) -> None:
         """Load patterns and compile into pathspec."""
-        patterns = load_ignore_patterns(self.flow_dir)
-        if patterns:
-            self._spec = pathspec.GitIgnoreSpec.from_lines(patterns)
+        for pattern_root, patterns in _load_ignore_pattern_sources(self.flow_dir):
+            if patterns:
+                self._specs.append(
+                    (pattern_root, pathspec.GitIgnoreSpec.from_lines(patterns))
+                )
 
     def filter(
         self,
@@ -202,11 +213,25 @@ class IgnoreFilter:
                 result.excluded_by_ignore.append(file)
                 continue
 
-            # Check against ignore spec
+            # Check against ignore specs in cascade order. A later source only
+            # overrides the current decision when one of its patterns matches.
             excluded = False
-            if self._spec is not None:
-                if self._spec.match_file(rel_path):
-                    excluded = True
+            for pattern_root, spec in self._specs:
+                try:
+                    pattern_path = str(file.relative_to(pattern_root))
+                except ValueError:
+                    try:
+                        pattern_path = str(file.resolve().relative_to(pattern_root))
+                    except ValueError:
+                        continue
+
+                normalized_path = pathspec.util.normalize_file(pattern_path)
+                if any(
+                    pattern.include is not None
+                    and pattern.match_file(normalized_path) is not None
+                    for pattern in spec.patterns
+                ):
+                    excluded = spec.match_file(normalized_path)
 
             if excluded:
                 result.excluded_by_ignore.append(file)

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/cache_policies.py

@@ -1,4 +1,5 @@
 import inspect
+import sys
 from copy import deepcopy
 from dataclasses import dataclass, field
 from logging import Logger
@@ -35,15 +36,18 @@ def _register_stable_transforms() -> None:
     Some inputs do not reliably produce deterministic byte strings when serialized via
     `cloudpickle`. This utility registers stabilizing transformations of such types
     so that cache keys that utilize them are deterministic across invocations.
+
+    Transforms are only registered for modules that the user has already imported so
+    that optional dependencies are never imported on their behalf. A value of a given
+    type cannot exist before its module is imported, so this runs when inputs are
+    hashed instead of at import time.
     """
-    try:
+    if sys.modules.get("pandas") is not None:
         import pandas as pd  # pyright: ignore
 
         STABLE_TRANSFORMS[pd.DataFrame] = lambda df: [  # pyright: ignore
             df[col] for col in sorted(df.columns)
         ]
-    except (ImportError, ModuleNotFoundError):
-        pass
 
 
 @dataclass
@@ -377,6 +381,8 @@ class Inputs(CachePolicy):
         if not inputs:
             return None
 
+        _register_stable_transforms()
+
         for key, val in inputs.items():
             if key not in exclude:
                 transformer = STABLE_TRANSFORMS.get(type(val))  # type: ignore[reportUnknownMemberType]
@@ -401,8 +407,6 @@ class Inputs(CachePolicy):
         return Inputs(exclude=self.exclude + [other])
 
 
-_register_stable_transforms()
-
 INPUTS = Inputs()
 NONE = _None()
 NO_CACHE = _None()

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/context.py

@@ -914,6 +914,32 @@ def get_settings_context() -> SettingsContext:
     return settings_ctx
 
 
+@contextmanager
+def _temporary_global_settings_context(
+    settings_context: "SettingsContext",
+) -> Generator[None, None, None]:
+    """
+    Temporarily replace the process-global settings context.
+
+    `SettingsContext.get` returns the process-global settings context when the
+    current `contextvars` context does not contain one. Replacing the global
+    context makes the given settings visible to contexts that were copied before
+    the settings were applied, such as the context that
+    `unittest.IsolatedAsyncioTestCase` copies when it is constructed. Contexts
+    that contain their own settings context are not affected.
+
+    This is an internal utility for `prefect.testing.utilities.prefect_test_harness`.
+    """
+    global GLOBAL_SETTINGS_CONTEXT
+
+    prior_global_settings_context = GLOBAL_SETTINGS_CONTEXT
+    GLOBAL_SETTINGS_CONTEXT = settings_context
+    try:
+        yield
+    finally:
+        GLOBAL_SETTINGS_CONTEXT = prior_global_settings_context
+
+
 @contextmanager
 def tags(*new_tags: str) -> Generator[set[str], None, None]:
     """

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/events/filters.py

@@ -14,6 +14,14 @@ from prefect.utilities.collections import AutoEnum
 from .schemas.events import Event, Resource, ResourceSpecification
 
 
+class AutomationFilterId(PrefectBaseModel):
+    """Filter by `Automation.id`."""
+
+    any_: Optional[list[UUID]] = Field(
+        default=None, description="A list of automation ids to include"
+    )
+
+
 class AutomationFilterCreated(PrefectBaseModel):
     """Filter by `Automation.created`."""
 
@@ -52,6 +60,9 @@ class AutomationFilterTags(PrefectBaseModel):
 
 
 class AutomationFilter(PrefectBaseModel):
+    id: Optional[AutomationFilterId] = Field(
+        default=None, description="Filter criteria for `Automation.id`"
+    )
     name: Optional[AutomationFilterName] = Field(
         default=None, description="Filter criteria for `Automation.name`"
     )

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/events/worker.py

@@ -6,10 +6,12 @@ from uuid import UUID
 from typing_extensions import Self
 
 from prefect._internal.concurrency.services import QueueService
+from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_KEY,
     PREFECT_API_URL,
     PREFECT_CLOUD_API_URL,
+    get_current_settings,
 )
 from prefect.utilities.context import temporary_context
 
@@ -23,8 +25,12 @@ from .related import related_resources_from_run_context
 from .schemas.events import Event
 
 if TYPE_CHECKING:
+    import logging
+
     from prefect.client.orchestration import PrefectClient
 
+logger: "logging.Logger" = get_logger(__name__)
+
 
 class ProcessPoolForwardingEventsClient(EventsClient):
     """An events client that forwards events to a parent process queue."""
@@ -69,8 +75,6 @@ class EventsWorker(QueueService[Event]):
     def __init__(
         self, client_type: Type[EventsClient], client_options: Tuple[Tuple[str, Any]]
     ):
-        from prefect.settings import get_current_settings
-
         self._max_queue_size = get_current_settings().events.worker_max_queue_size
         super().__init__(client_type, client_options)
         self.client_type = client_type
@@ -113,10 +117,29 @@ class EventsWorker(QueueService[Event]):
             return
 
         exclude = {resource.id for resource in event.involved_resources}
-        event.related += await related_resources_from_run_context(
+        related = await related_resources_from_run_context(
             client=self._orchestration_client, exclude=exclude
         )
 
+        # The event was validated when it was created, before these resources were
+        # known, so only attach as many as keep the event within the same maximum that
+        # the Event schema validates.  Otherwise the event is no longer valid to send.
+        maximum = get_current_settings().server.events.maximum_related_resources
+        room = max(maximum - len(event.related), 0)
+        if len(related) > room:
+            logger.warning(
+                "Attaching only %s of the %s related resources from the run context "
+                "to event %s, which already has %s of a maximum %s related resources",
+                room,
+                len(related),
+                event.id,
+                len(event.related),
+                maximum,
+            )
+            related = related[:room]
+
+        event.related += related
+
     @classmethod
     def set_client_override(
         cls, client_type: Optional[Type[EventsClient]], **client_kwargs: Any

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/flow_engine.py

@@ -1213,9 +1213,10 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                         intent = _termination_intent()
                         if intent == "cancel":
                             self.handle_cancellation(exc)
-                        elif intent is None:
-                            self.handle_crash(exc)
-                        elif intent not in _SUPERVISOR_OWNED_INTENTS:
+                            raise
+                        if intent in _SUPERVISOR_OWNED_INTENTS:
+                            raise
+                        if intent is not None:
                             # Defensive: an unknown intent means the control
                             # listener was extended (e.g. "suspend" in a
                             # follow-up PR) without extending this dispatch.
@@ -1227,6 +1228,15 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                                 " dispatch branch.",
                                 intent,
                             )
+                        if self.flow_run.state and self.flow_run.state.is_final():
+                            # A termination signal that lands during teardown
+                            # must not overwrite an already-reported final state
+                            self.logger.debug(
+                                "Termination signal was received after the flow"
+                                " run reached a final state",
+                                exc_info=exc,
+                            )
+                        else:
                             self.handle_crash(exc)
                         raise
                     except Exception:
@@ -1913,9 +1923,10 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                         intent = _termination_intent()
                         if intent == "cancel":
                             await self.handle_cancellation(exc)
-                        elif intent is None:
-                            await self.handle_crash(exc)
-                        elif intent not in _SUPERVISOR_OWNED_INTENTS:
+                            raise
+                        if intent in _SUPERVISOR_OWNED_INTENTS:
+                            raise
+                        if intent is not None:
                             # Defensive: see sync engine's dispatch for why.
                             self.logger.error(
                                 "Unhandled termination intent %r; treating as"
@@ -1923,6 +1934,15 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                                 " dispatch branch.",
                                 intent,
                             )
+                        if self.flow_run.state and self.flow_run.state.is_final():
+                            # A termination signal that lands during teardown
+                            # must not overwrite an already-reported final state
+                            self.logger.debug(
+                                "Termination signal was received after the flow"
+                                " run reached a final state",
+                                exc_info=exc,
+                            )
+                        else:
                             await self.handle_crash(exc)
                         raise
                     except Exception:

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/flows.py

@@ -2397,6 +2397,10 @@ class InfrastructureBoundFlow(Flow[P, R]):
         job_variables: Infrastructure configuration that will override the base job
             configuration of the work pool.
         launcher: Optional upload and execution launcher overrides.
+        include_files: Optional file patterns to include with the flow bundle.
+        include_files_base_dir: Optional base directory for `include_files`. Relative
+            paths are resolved from the working directory when the bundle is created.
+            Defaults to the flow file's directory.
         worker_cls: The class of the worker to use to spin up infrastructure and submit
             the flow to it.
     """
@@ -2409,6 +2413,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         worker_cls: type["BaseWorker[Any, Any, Any]"],
         launcher: BundleLauncher | None = None,
         include_files: Sequence[str] | None = None,
+        include_files_base_dir: Path | str | None = None,
         **kwargs: Any,
     ):
         super().__init__(*args, **kwargs)
@@ -2419,6 +2424,9 @@ class InfrastructureBoundFlow(Flow[P, R]):
         self.include_files: list[str] | None = (
             list(include_files) if include_files is not None else None
         )
+        self.include_files_base_dir: str | None = (
+            str(include_files_base_dir) if include_files_base_dir is not None else None
+        )
 
     @overload
     def __call__(self: "Flow[P, NoReturn]", *args: P.args, **kwargs: P.kwargs) -> None:
@@ -2648,7 +2656,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
             get_result_store,
             resolve_result_storage,
         )
-        from prefect.states import Pending, Scheduled
+        from prefect.states import Failed, Pending, Scheduled
         from prefect.tasks import Task
 
         # Get parameters to error early if they are invalid
@@ -2753,14 +2761,28 @@ class InfrastructureBoundFlow(Flow[P, R]):
                 parent_task_run_id=getattr(parent_task_run, "id", None),
             )
 
-            result = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)
-            upload_bundle_to_storage(
-                result["bundle"],
-                bundle_key,
-                upload_command,
-                zip_path=result["zip_path"],
-                upload_step=upload_step,
-            )
+            try:
+                result = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)
+                upload_bundle_to_storage(
+                    result["bundle"],
+                    bundle_key,
+                    upload_command,
+                    zip_path=result["zip_path"],
+                    upload_step=upload_step,
+                )
+            except Exception as exc:
+                try:
+                    client.set_flow_run_state(
+                        flow_run.id,
+                        state=Failed(message=f"Flow run submission failed: {exc}"),
+                        force=True,
+                    )
+                except Exception:
+                    logger.exception(
+                        "Failed to update flow run %s after submission failed",
+                        flow_run.id,
+                    )
+                raise
 
             # Set flow run to scheduled now that the bundle is uploaded and ready to be executed
             client.set_flow_run_state(flow_run.id, state=Scheduled())
@@ -2795,6 +2817,7 @@ class InfrastructureBoundFlow(Flow[P, R]):
         job_variables: Optional[dict[str, Any]] = None,
         launcher: BundleLauncher | None = NotSet,  # type: ignore
         include_files: Optional[list[str]] = NotSet,  # type: ignore
+        include_files_base_dir: Path | str | None = NotSet,  # type: ignore
     ) -> "InfrastructureBoundFlow[P, R]":
         new_flow = super().with_options(
             name=name,
@@ -2828,6 +2851,9 @@ class InfrastructureBoundFlow(Flow[P, R]):
             include_files=include_files
             if include_files is not NotSet
             else self.include_files,
+            include_files_base_dir=include_files_base_dir
+            if include_files_base_dir is not NotSet
+            else self.include_files_base_dir,
         )
         return new_infrastructure_bound_flow
 
@@ -2839,7 +2865,25 @@ def bind_flow_to_infrastructure(
     job_variables: dict[str, Any] | None = None,
     launcher: BundleLauncher | None = None,
     include_files: Sequence[str] | None = None,
+    *,
+    include_files_base_dir: Path | str | None = None,
 ) -> InfrastructureBoundFlow[P, R]:
+    """Bind a flow to execution on a specific infrastructure work pool.
+
+    Args:
+        flow: The flow to bind.
+        work_pool: The name of the work pool to use.
+        worker_cls: The worker class that submits the flow.
+        job_variables: Infrastructure overrides for the work pool's base job template.
+        launcher: Optional upload and execution launcher overrides.
+        include_files: Optional file patterns to include with the flow bundle.
+        include_files_base_dir: Optional base directory for `include_files`. Relative
+            paths are resolved from the working directory when the bundle is created.
+            Defaults to the flow file's directory.
+
+    Returns:
+        An infrastructure-bound copy of the flow.
+    """
     new = InfrastructureBoundFlow[P, R](
         flow.fn,
         work_pool=work_pool,
@@ -2847,6 +2891,7 @@ def bind_flow_to_infrastructure(
         worker_cls=worker_cls,
         launcher=launcher,
         include_files=include_files,
+        include_files_base_dir=include_files_base_dir,
     )
     # Copy all attributes from the original flow
     for attr, value in flow.__dict__.items():
@@ -2856,6 +2901,9 @@ def bind_flow_to_infrastructure(
     new.worker_cls = worker_cls
     new.launcher = normalize_launcher(launcher)
     new.include_files = list(include_files) if include_files is not None else None
+    new.include_files_base_dir = (
+        str(include_files_base_dir) if include_files_base_dir is not None else None
+    )
     return new
 
 

{prefect_client-3.8.4.dev6 → prefect_client-3.8.5}/src/prefect/logging/handlers.py

@@ -9,7 +9,7 @@ import traceback
 import uuid
 import warnings
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, Callable, Dict, TextIO, Type
+from typing import TYPE_CHECKING, Any, Callable, Dict, TextIO, Type, cast
 
 from rich.console import Console
 from rich.highlighter import Highlighter, NullHighlighter
@@ -334,8 +334,29 @@ class _SafeStreamHandler(StreamHandler):
     it to handleError(), which prints a noisy traceback to sys.stderr. We
     suppress that for ValueError so background threads logging after stream
     teardown stay silent.
+
+    Context-managed locking also prevents asynchronous cancellation from
+    leaving the handler locked on Python 3.12 and earlier.
     """
 
+    def handle(self, record: logging.LogRecord) -> bool:
+        filtered = self.filter(record)
+        if isinstance(filtered, logging.LogRecord):
+            record = filtered
+        if filtered:
+            lock = self.lock
+            assert lock is not None
+            with lock:
+                self.emit(record)
+        return cast(bool, filtered)
+
+    def flush(self) -> None:
+        lock = self.lock
+        assert lock is not None
+        with lock:
+            if self.stream and hasattr(self.stream, "flush"):
+                self.stream.flush()
+
     def handleError(self, record: logging.LogRecord) -> None:
         _, exc, _ = sys.exc_info()
         if isinstance(exc, ValueError) and "closed file" in str(exc):