prefect-client 3.1.4__py3-none-any.whl → 3.1.6__py3-none-any.whl

prefect/client/utilities.py

@@ -5,31 +5,32 @@ Utilities for working with clients.
 # This module must not import from `prefect.client` when it is imported to avoid
 # circular imports for decorators such as `inject_client` which are widely used.
 
+from collections.abc import Awaitable, Coroutine
 from functools import wraps
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Awaitable,
-    Callable,
-    Coroutine,
-    Optional,
-    Tuple,
-    TypeVar,
-    cast,
-)
-
-from typing_extensions import Concatenate, ParamSpec
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+
+from typing_extensions import Concatenate, ParamSpec, TypeGuard, TypeVar
 
 if TYPE_CHECKING:
-    from prefect.client.orchestration import PrefectClient
+    from prefect.client.orchestration import PrefectClient, SyncPrefectClient
 
 P = ParamSpec("P")
-R = TypeVar("R")
+R = TypeVar("R", infer_variance=True)
+
+
+def _current_async_client(
+    client: Union["PrefectClient", "SyncPrefectClient"],
+) -> TypeGuard["PrefectClient"]:
+    """Determine if the client is a PrefectClient instance attached to the current loop"""
+    from prefect._internal.concurrency.event_loop import get_running_loop
+
+    # Only a PrefectClient will have a _loop attribute that is the current loop
+    return getattr(client, "_loop", None) == get_running_loop()
 
 
 def get_or_create_client(
     client: Optional["PrefectClient"] = None,
-) -> Tuple["PrefectClient", bool]:
+) -> tuple["PrefectClient", bool]:
     """
     Returns provided client, infers a client from context if available, or creates a new client.
 
@@ -41,29 +42,22 @@ def get_or_create_client(
     """
     if client is not None:
         return client, True
-    from prefect._internal.concurrency.event_loop import get_running_loop
+
     from prefect.context import AsyncClientContext, FlowRunContext, TaskRunContext
 
     async_client_context = AsyncClientContext.get()
     flow_run_context = FlowRunContext.get()
     task_run_context = TaskRunContext.get()
 
-    if async_client_context and async_client_context.client._loop == get_running_loop():
-        return async_client_context.client, True
-    elif (
-        flow_run_context
-        and getattr(flow_run_context.client, "_loop", None) == get_running_loop()
-    ):
-        return flow_run_context.client, True
-    elif (
-        task_run_context
-        and getattr(task_run_context.client, "_loop", None) == get_running_loop()
-    ):
-        return task_run_context.client, True
-    else:
-        from prefect.client.orchestration import get_client as get_httpx_client
+    for context in (async_client_context, flow_run_context, task_run_context):
+        if context is None:
+            continue
+        if _current_async_client(context_client := context.client):
+            return context_client, True
+
+    from prefect.client.orchestration import get_client as get_httpx_client
 
-        return get_httpx_client(), False
+    return get_httpx_client(), False
 
 
 def client_injector(
@@ -90,16 +84,18 @@ def inject_client(
 
     @wraps(fn)
     async def with_injected_client(*args: P.args, **kwargs: P.kwargs) -> R:
-        client = cast(Optional["PrefectClient"], kwargs.pop("client", None))
-        client, inferred = get_or_create_client(client)
+        given = kwargs.pop("client", None)
+        if TYPE_CHECKING:
+            assert given is None or isinstance(given, PrefectClient)
+        client, inferred = get_or_create_client(given)
         if not inferred:
             context = client
         else:
             from prefect.utilities.asyncutils import asyncnullcontext
 
-            context = asyncnullcontext()
+            context = asyncnullcontext(client)
         async with context as new_client:
-            kwargs.setdefault("client", new_client or client)
+            kwargs |= {"client": new_client}
             return await fn(*args, **kwargs)
 
     return with_injected_client

prefect/concurrency/asyncio.py

@@ -17,7 +17,6 @@ except ImportError:
 from prefect.client.orchestration import get_client
 from prefect.client.schemas.responses import MinimalConcurrencyLimitResponse
 from prefect.logging.loggers import get_run_logger
-from prefect.utilities.asyncutils import sync_compatible
 
 from .context import ConcurrencyContext
 from .events import (
@@ -79,7 +78,7 @@ async def concurrency(
 
     names = names if isinstance(names, list) else [names]
 
-    limits = await _acquire_concurrency_slots(
+    limits = await _aacquire_concurrency_slots(
         names,
         occupy,
         timeout_seconds=timeout_seconds,
@@ -95,7 +94,7 @@ async def concurrency(
     finally:
         occupancy_period = cast(Interval, (pendulum.now("UTC") - acquisition_time))
         try:
-            await _release_concurrency_slots(
+            await _arelease_concurrency_slots(
                 names, occupy, occupancy_period.total_seconds()
             )
         except anyio.get_cancelled_exc_class():
@@ -138,7 +137,7 @@ async def rate_limit(
 
     names = names if isinstance(names, list) else [names]
 
-    limits = await _acquire_concurrency_slots(
+    limits = await _aacquire_concurrency_slots(
         names,
         occupy,
         mode="rate_limit",
@@ -149,7 +148,6 @@ async def rate_limit(
     _emit_concurrency_acquisition_events(limits, occupy)
 
 
-@sync_compatible
 @deprecated_parameter(
     name="create_if_missing",
     start_date="Sep 2024",
@@ -157,10 +155,10 @@ async def rate_limit(
     when=lambda x: x is not None,
     help="Limits must be explicitly created before acquiring concurrency slots; see `strict` if you want to enforce this behavior.",
 )
-async def _acquire_concurrency_slots(
+async def _aacquire_concurrency_slots(
     names: List[str],
     slots: int,
-    mode: Union[Literal["concurrency"], Literal["rate_limit"]] = "concurrency",
+    mode: Literal["concurrency", "rate_limit"] = "concurrency",
     timeout_seconds: Optional[float] = None,
     create_if_missing: Optional[bool] = None,
     max_retries: Optional[int] = None,
@@ -199,8 +197,7 @@ async def _acquire_concurrency_slots(
     return retval
 
 
-@sync_compatible
-async def _release_concurrency_slots(
+async def _arelease_concurrency_slots(
     names: List[str], slots: int, occupancy_seconds: float
 ) -> List[MinimalConcurrencyLimitResponse]:
     async with get_client() as client:

prefect/concurrency/services.py

@@ -83,6 +83,9 @@ class ConcurrencySlotAcquisitionService(QueueService):
                         if max_retries is not None and max_retries <= 0:
                             raise exc
                         retry_after = float(exc.response.headers["Retry-After"])
+                        logger.debug(
+                            f"Unable to acquire concurrency slot. Retrying in {retry_after} second(s)."
+                        )
                         await asyncio.sleep(retry_after)
                         if max_retries is not None:
                             max_retries -= 1

prefect/concurrency/sync.py

@@ -9,6 +9,9 @@ from typing import (
 )
 
 import pendulum
+from typing_extensions import Literal
+
+from prefect.utilities.asyncutils import run_coro_as_sync
 
 try:
     from pendulum import Interval
@@ -19,8 +22,8 @@ except ImportError:
 from prefect.client.schemas.responses import MinimalConcurrencyLimitResponse
 
 from .asyncio import (
-    _acquire_concurrency_slots,
-    _release_concurrency_slots,
+    _aacquire_concurrency_slots,
+    _arelease_concurrency_slots,
 )
 from .events import (
     _emit_concurrency_acquisition_events,
@@ -30,6 +33,36 @@ from .events import (
 T = TypeVar("T")
 
 
+def _release_concurrency_slots(
+    names: List[str], slots: int, occupancy_seconds: float
+) -> List[MinimalConcurrencyLimitResponse]:
+    result = run_coro_as_sync(
+        _arelease_concurrency_slots(names, slots, occupancy_seconds)
+    )
+    if result is None:
+        raise RuntimeError("Failed to release concurrency slots")
+    return result
+
+
+def _acquire_concurrency_slots(
+    names: List[str],
+    slots: int,
+    mode: Literal["concurrency", "rate_limit"] = "concurrency",
+    timeout_seconds: Optional[float] = None,
+    create_if_missing: Optional[bool] = None,
+    max_retries: Optional[int] = None,
+    strict: bool = False,
+) -> List[MinimalConcurrencyLimitResponse]:
+    result = run_coro_as_sync(
+        _aacquire_concurrency_slots(
+            names, slots, mode, timeout_seconds, create_if_missing, max_retries, strict
+        )
+    )
+    if result is None:
+        raise RuntimeError("Failed to acquire concurrency slots")
+    return result
+
+
 @contextmanager
 def concurrency(
     names: Union[str, List[str]],
@@ -81,7 +114,6 @@ def concurrency(
         create_if_missing=create_if_missing,
         strict=strict,
         max_retries=max_retries,
-        _sync=True,
     )
     acquisition_time = pendulum.now("UTC")
     emitted_events = _emit_concurrency_acquisition_events(limits, occupy)
@@ -94,7 +126,6 @@ def concurrency(
             names,
             occupy,
             occupancy_period.total_seconds(),
-            _sync=True,
         )
         _emit_concurrency_release_events(limits, occupy, emitted_events)
 
@@ -134,6 +165,5 @@ def rate_limit(
         timeout_seconds=timeout_seconds,
         create_if_missing=create_if_missing,
         strict=strict,
-        _sync=True,
     )
     _emit_concurrency_acquisition_events(limits, occupy)

prefect/context.py

@@ -25,7 +25,6 @@ from typing import (
     Union,
 )
 
-import pendulum
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
 from pydantic_extra_types.pendulum_dt import DateTime
 from typing_extensions import Self
@@ -44,12 +43,16 @@ from prefect.results import (
     get_default_persist_setting_for_tasks,
 )
 from prefect.settings import Profile, Settings
-from prefect.settings.legacy import _get_settings_fields
+from prefect.settings.legacy import (
+    _get_settings_fields,  # type: ignore[reportPrivateUsage]
+)
 from prefect.states import State
 from prefect.task_runners import TaskRunner
 from prefect.utilities.services import start_client_metrics_server
 
 T = TypeVar("T")
+P = TypeVar("P")
+R = TypeVar("R")
 
 if TYPE_CHECKING:
     from prefect.flows import Flow
@@ -121,8 +124,8 @@ class ContextModel(BaseModel):
     """
 
     # The context variable for storing data must be defined by the child class
-    __var__: ContextVar
-    _token: Optional[Token] = PrivateAttr(None)
+    __var__: ContextVar[Self]
+    _token: Optional[Token[Self]] = PrivateAttr(None)
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
         extra="forbid",
@@ -150,7 +153,7 @@ class ContextModel(BaseModel):
         return cls.__var__.get(None)
 
     def model_copy(
-        self: Self, *, update: Optional[Dict[str, Any]] = None, deep: bool = False
+        self: Self, *, update: Optional[Mapping[str, Any]] = None, deep: bool = False
     ):
         """
         Duplicate the context model, optionally choosing which fields to include, exclude, or change.
@@ -199,14 +202,14 @@ class SyncClientContext(ContextModel):
         assert c1 is ctx.client
     """
 
-    __var__ = ContextVar("sync-client-context")
+    __var__: ContextVar[Self] = ContextVar("sync-client-context")
     client: SyncPrefectClient
     _httpx_settings: Optional[dict[str, Any]] = PrivateAttr(None)
     _context_stack: int = PrivateAttr(0)
 
     def __init__(self, httpx_settings: Optional[dict[str, Any]] = None):
         super().__init__(
-            client=get_client(sync_client=True, httpx_settings=httpx_settings),
+            client=get_client(sync_client=True, httpx_settings=httpx_settings),  # type: ignore[reportCallIssue]
         )
         self._httpx_settings = httpx_settings
         self._context_stack = 0
@@ -220,11 +223,11 @@ class SyncClientContext(ContextModel):
         else:
             return self
 
-    def __exit__(self, *exc_info):
+    def __exit__(self, *exc_info: Any):
         self._context_stack -= 1
         if self._context_stack == 0:
-            self.client.__exit__(*exc_info)
-            return super().__exit__(*exc_info)
+            self.client.__exit__(*exc_info)  # type: ignore[reportUnknownMemberType]
+            return super().__exit__(*exc_info)  # type: ignore[reportUnknownMemberType]
 
     @classmethod
     @contextmanager
@@ -264,12 +267,12 @@ class AsyncClientContext(ContextModel):
 
     def __init__(self, httpx_settings: Optional[dict[str, Any]] = None):
         super().__init__(
-            client=get_client(sync_client=False, httpx_settings=httpx_settings),
+            client=get_client(sync_client=False, httpx_settings=httpx_settings),  # type: ignore[reportCallIssue]
         )
         self._httpx_settings = httpx_settings
         self._context_stack = 0
 
-    async def __aenter__(self):
+    async def __aenter__(self: Self) -> Self:
         self._context_stack += 1
         if self._context_stack == 1:
             await self.client.__aenter__()
@@ -278,11 +281,11 @@ class AsyncClientContext(ContextModel):
         else:
             return self
 
-    async def __aexit__(self, *exc_info):
+    async def __aexit__(self: Self, *exc_info: Any) -> None:
         self._context_stack -= 1
         if self._context_stack == 0:
-            await self.client.__aexit__(*exc_info)
-            return super().__exit__(*exc_info)
+            await self.client.__aexit__(*exc_info)  # type: ignore[reportUnknownMemberType]
+            return super().__exit__(*exc_info)  # type: ignore[reportUnknownMemberType]
 
     @classmethod
     @asynccontextmanager
@@ -305,19 +308,20 @@ class RunContext(ContextModel):
         client: The Prefect client instance being used for API communication
     """
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
 
         start_client_metrics_server()
 
-    start_time: DateTime = Field(default_factory=lambda: pendulum.now("UTC"))
+    start_time: DateTime = Field(default_factory=lambda: DateTime.now("UTC"))
     input_keyset: Optional[Dict[str, Dict[str, str]]] = None
     client: Union[PrefectClient, SyncPrefectClient]
 
-    def serialize(self):
+    def serialize(self: Self, include_secrets: bool = True) -> Dict[str, Any]:
         return self.model_dump(
             include={"start_time", "input_keyset"},
             exclude_unset=True,
+            context={"include_secrets": include_secrets},
         )
 
 
@@ -336,9 +340,9 @@ class EngineContext(RunContext):
         flow_run_states: A list of states for flow runs created within this flow run
     """
 
-    flow: Optional["Flow"] = None
+    flow: Optional["Flow[Any, Any]"] = None
     flow_run: Optional[FlowRun] = None
-    task_runner: TaskRunner
+    task_runner: TaskRunner[Any]
     log_prints: bool = False
     parameters: Optional[Dict[str, Any]] = None
 
@@ -351,21 +355,21 @@ class EngineContext(RunContext):
     persist_result: bool = Field(default_factory=get_default_persist_setting)
 
     # Counter for task calls allowing unique
-    task_run_dynamic_keys: Dict[str, int] = Field(default_factory=dict)
+    task_run_dynamic_keys: Dict[str, Union[str, int]] = Field(default_factory=dict)
 
     # Counter for flow pauses
     observed_flow_pauses: Dict[str, int] = Field(default_factory=dict)
 
     # Tracking for result from task runs in this flow run for dependency tracking
     # Holds the ID of the object returned by the task run and task run state
-    task_run_results: Mapping[int, State] = Field(default_factory=dict)
+    task_run_results: dict[int, State] = Field(default_factory=dict)
 
     # Events worker to emit events
     events: Optional[EventsWorker] = None
 
-    __var__: ContextVar = ContextVar("flow_run")
+    __var__: ContextVar[Self] = ContextVar("flow_run")
 
-    def serialize(self):
+    def serialize(self: Self, include_secrets: bool = True) -> Dict[str, Any]:
         return self.model_dump(
             include={
                 "flow_run",
@@ -378,6 +382,8 @@ class EngineContext(RunContext):
                 "persist_result",
             },
             exclude_unset=True,
+            serialize_as_any=True,
+            context={"include_secrets": include_secrets},
         )
 
 
@@ -394,7 +400,7 @@ class TaskRunContext(RunContext):
         task_run: The API metadata for this task run
     """
 
-    task: "Task"
+    task: "Task[Any, Any]"
     task_run: TaskRun
     log_prints: bool = False
     parameters: Dict[str, Any]
@@ -405,7 +411,7 @@ class TaskRunContext(RunContext):
 
     __var__ = ContextVar("task_run")
 
-    def serialize(self):
+    def serialize(self: Self, include_secrets: bool = True) -> Dict[str, Any]:
         return self.model_dump(
             include={
                 "task_run",
@@ -418,6 +424,8 @@ class TaskRunContext(RunContext):
                 "persist_result",
             },
             exclude_unset=True,
+            serialize_as_any=True,
+            context={"include_secrets": include_secrets},
         )
 
 
@@ -436,7 +444,7 @@ class TagsContext(ContextModel):
         # Return an empty `TagsContext` instead of `None` if no context exists
         return cls.__var__.get(TagsContext())
 
-    __var__: ContextVar = ContextVar("tags")
+    __var__: ContextVar[Self] = ContextVar("tags")
 
 
 class SettingsContext(ContextModel):
@@ -453,9 +461,9 @@ class SettingsContext(ContextModel):
     profile: Profile
     settings: Settings
 
-    __var__: ContextVar = ContextVar("settings")
+    __var__: ContextVar[Self] = ContextVar("settings")
 
-    def __hash__(self) -> int:
+    def __hash__(self: Self) -> int:
         return hash(self.settings)
 
     @classmethod
@@ -562,7 +570,7 @@ def tags(*new_tags: str) -> Generator[Set[str], None, None]:
 
 @contextmanager
 def use_profile(
-    profile: Union[Profile, str],
+    profile: Union[Profile, str, Any],
     override_environment_variables: bool = False,
     include_current_context: bool = True,
 ):
@@ -662,7 +670,7 @@ def root_settings_context():
     # an override in the `SettingsContext.get` method.
 
 
-GLOBAL_SETTINGS_CONTEXT: SettingsContext = root_settings_context()
+GLOBAL_SETTINGS_CONTEXT: SettingsContext = root_settings_context()  # type: ignore[reportConstantRedefinition]
 
 
 # 2024-07-02: This surfaces an actionable error message for removed objects

prefect/deployments/flow_runs.py

@@ -113,10 +113,8 @@ async def run_deployment(
     task_run_ctx = TaskRunContext.get()
     if as_subflow and (flow_run_ctx or task_run_ctx):
         # TODO: this logic can likely be simplified by using `Task.create_run`
-        from prefect.utilities.engine import (
-            _dynamic_key_for_task_run,
-            collect_task_run_inputs,
-        )
+        from prefect.utilities._engine import dynamic_key_for_task_run
+        from prefect.utilities.engine import collect_task_run_inputs
 
         # This was called from a flow. Link the flow run as a subflow.
         task_inputs = {
@@ -143,7 +141,7 @@ async def run_deployment(
             else task_run_ctx.task_run.flow_run_id
         )
         dynamic_key = (
-            _dynamic_key_for_task_run(flow_run_ctx, dummy_task)
+            dynamic_key_for_task_run(flow_run_ctx, dummy_task)
             if flow_run_ctx
             else task_run_ctx.task_run.dynamic_key
         )

prefect/docker/__init__.py

@@ -17,4 +17,4 @@ def __getattr__(name: str) -> object:
         module, attr = _public_api[name]
         return getattr(import_module(module), attr)
 
-    raise ImportError(f"module {__name__!r} has no attribute {name!r}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

prefect/events/schemas/events.py

@@ -13,16 +13,20 @@ from typing import (
 )
 from uuid import UUID, uuid4
 
-import pendulum
-from pydantic import ConfigDict, Field, RootModel, field_validator, model_validator
+from pydantic import (
+    AfterValidator,
+    ConfigDict,
+    Field,
+    RootModel,
+    model_validator,
+)
 from pydantic_extra_types.pendulum_dt import DateTime
-from typing_extensions import Self
+from typing_extensions import Annotated, Self
 
 from prefect._internal.schemas.bases import PrefectBaseModel
 from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE,
-    PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES,
 )
 
 from .labelling import Labelled
@@ -90,22 +94,34 @@ class RelatedResource(Resource):
         return self["prefect.resource.role"]
 
 
+def _validate_related_resources(value) -> List:
+    from prefect.settings import PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES
+
+    if len(value) > PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value():
+        raise ValueError(
+            "The maximum number of related resources "
+            f"is {PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value()}"
+        )
+    return value
+
+
 class Event(PrefectBaseModel):
     """The client-side view of an event that has happened to a Resource"""
 
     model_config = ConfigDict(extra="ignore")
 
     occurred: DateTime = Field(
-        default_factory=lambda: pendulum.now("UTC"),
+        default_factory=lambda: DateTime.now("UTC"),
         description="When the event happened from the sender's perspective",
     )
-    event: str = Field(
-        description="The name of the event that happened",
-    )
+    event: str = Field(description="The name of the event that happened")
     resource: Resource = Field(
         description="The primary Resource this event concerns",
     )
-    related: List[RelatedResource] = Field(
+    related: Annotated[
+        List[RelatedResource],
+        AfterValidator(_validate_related_resources),
+    ] = Field(
         default_factory=list,
         description="A list of additional Resources involved in this event",
     )
@@ -144,17 +160,6 @@ class Event(PrefectBaseModel):
             resources[related.role].append(related)
         return resources
 
-    @field_validator("related")
-    @classmethod
-    def enforce_maximum_related_resources(cls, value: List[RelatedResource]):
-        if len(value) > PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value():
-            raise ValueError(
-                "The maximum number of related resources "
-                f"is {PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value()}"
-            )
-
-        return value
-
     def find_resource_label(self, label: str) -> Optional[str]:
         """Finds the value of the given label in this event's resource or one of its
         related resources.  If the label starts with `related:<role>:`, search for the

prefect/events/utilities.py

@@ -3,7 +3,6 @@ from typing import Any, Dict, List, Optional, Union
 from uuid import UUID
 
 import pendulum
-from pydantic_extra_types.pendulum_dt import DateTime
 
 from .clients import (
     AssertingEventsClient,
@@ -20,7 +19,7 @@ TIGHT_TIMING = timedelta(minutes=5)
 def emit_event(
     event: str,
     resource: Dict[str, str],
-    occurred: Optional[DateTime] = None,
+    occurred: Optional[pendulum.DateTime] = None,
     related: Optional[Union[List[Dict[str, str]], List[RelatedResource]]] = None,
     payload: Optional[Dict[str, Any]] = None,
     id: Optional[UUID] = None,

prefect/filesystems.py

@@ -1,6 +1,7 @@
 import abc
 import urllib.parse
 from pathlib import Path
+from shutil import copytree
 from typing import Any, Dict, Optional
 
 import anyio
@@ -13,7 +14,6 @@ from prefect._internal.schemas.validators import (
 )
 from prefect.blocks.core import Block
 from prefect.utilities.asyncutils import run_sync_in_worker_thread, sync_compatible
-from prefect.utilities.compat import copytree
 from prefect.utilities.filesystem import filter_files
 
 from ._internal.compatibility.migration import getattr_migration
@@ -158,7 +158,7 @@ class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):
         copytree(from_path, local_path, dirs_exist_ok=True, ignore=ignore_func)
 
     async def _get_ignore_func(self, local_path: str, ignore_file: str):
-        with open(ignore_file, "r") as f:
+        with open(ignore_file) as f:
             ignore_patterns = f.readlines()
         included_files = filter_files(root=local_path, ignore_patterns=ignore_patterns)
 
@@ -348,7 +348,7 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
 
         included_files = None
         if ignore_file:
-            with open(ignore_file, "r") as f:
+            with open(ignore_file) as f:
                 ignore_patterns = f.readlines()
 
             included_files = filter_files(