prefect-client 3.8.2.dev5__tar.gz → 3.8.3__tar.gz

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/PKG-INFO

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

prefect_client-3.8.3/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.3"
+__build_date__ = "2026-08-13 18:54:04.527529+00:00"
+__git_commit__ = "d8f54b5c4857e933c31aac97e8ef56ea732c5138"
+__dirty__ = False

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/_internal/concurrency/cancellation.py

@@ -424,11 +424,18 @@ class WatcherThreadCancelScope(CancelScope):
         return self
 
     def __exit__(self, *_: Any) -> Optional[bool]:
-        retval = super().__exit__(*_)
-        self._event.set()
-        if self._enforcer_thread:
-            logger.debug("%r joining enforcer thread %r", self, self._enforcer_thread)
-            self._enforcer_thread.join()
+        # The enforcer thread can inject a cancellation exception at any instruction in
+        # this frame, so the event must be set from a `finally` to guarantee the
+        # enforcer is always released.
+        try:
+            retval = super().__exit__(*_)
+        finally:
+            self._event.set()
+            if self._enforcer_thread:
+                logger.debug(
+                    "%r joining enforcer thread %r", self, self._enforcer_thread
+                )
+                self._enforcer_thread.join()
         return retval
 
     def _send_cancelled_error(self):
@@ -458,10 +465,6 @@ class WatcherThreadCancelScope(CancelScope):
                 with _get_thread_shield(self._supervised_thread):
                     self._send_cancelled_error()
 
-        # Wait for the supervised thread to exit its context
-        logger.debug("%r waiting for supervised thread to exit", self)
-        self._event.wait()
-
     def cancel(self, throw: bool = True):
         if not super().cancel():
             return False

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/_internal/concurrency/services.py

@@ -408,10 +408,21 @@ class FutureQueueService(
             # If the request to the increment endpoint fails in a non-standard
             # way, we need to set the future's result so it'll be re-raised in
             # the context of the caller.
-            future.set_exception(exc)
+            if future.set_running_or_notify_cancel():
+                future.set_exception(exc)
             raise exc
         else:
-            future.set_result(response)
+            # Transitioning the future to running before setting its result closes
+            # the window where the caller cancels it while `acquire` is in flight:
+            # after this point `cancel()` fails, and if the caller got there first
+            # the acquired resource is nobody's and must be discarded.
+            if future.set_running_or_notify_cancel():
+                future.set_result(response)
+            else:
+                await self._discard(response)
+
+    async def _discard(self, response: R) -> None:
+        """Dispose of a result whose caller is no longer waiting for it."""
 
     @abc.abstractmethod
     async def acquire(self, *args: Unpack[Ts]) -> R:

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/_internal/observers.py

@@ -24,8 +24,9 @@ from prefect.exceptions import ObjectNotFound
 from prefect.logging.loggers import get_logger
 from prefect.utilities.services import critical_service_loop
 
-# How long to wait before warning that a suspension state is still unavailable,
-# how often to look initially, and the retry cap after the warning.
+# How long to wait before warning that a suspension transition is still not
+# visible on the flow run, how often to look initially, and the retry cap after
+# the warning.
 SUSPENSION_CONFIRMATION_WARNING_AFTER = 30.0
 SUSPENSION_CONFIRMATION_INTERVAL = 0.5
 SUSPENSION_CONFIRMATION_MAX_INTERVAL = 10.0
@@ -113,28 +114,40 @@ class _SuspensionWatch:
 
         while not self._closed and not self.is_suspended:
             try:
-                state = await self._client.read_flow_run_state(state_id)
+                flow_run = await self._client.read_flow_run(self.flow_run_id)
             except ObjectNotFound:
-                pass
+                self._logger.debug(
+                    "Flow run %s no longer exists; abandoning suspension confirmation.",
+                    self.flow_run_id,
+                )
+                return
             except Exception as exc:
                 last_error = exc
             else:
-                if state.state_details.flow_run_id not in (None, self.flow_run_id):
-                    self._logger.warning(
-                        "Suspension event for flow run %s referred to state %s owned"
-                        " by flow run %s.",
-                        self.flow_run_id,
-                        state_id,
-                        state.state_details.flow_run_id,
-                    )
-                    return
-                self.notify_if_suspended(state)
-                return
+                state = flow_run.state
+                if state is not None:
+                    if state.id == state_id or is_suspended_flow_run_state(state):
+                        self.notify_if_suspended(state)
+                        return
+                    if state.timestamp >= occurred:
+                        # Superseded (e.g. resumed) before confirmation: still
+                        # stop, or this engine could double-execute alongside
+                        # the resumed run's fresh submission.
+                        self.notify_if_suspended(
+                            State(
+                                id=state_id,
+                                type=StateType.PAUSED,
+                                name="Suspended",
+                                timestamp=occurred,
+                            )
+                        )
+                        return
 
             if not warned and time.monotonic() >= warning_deadline:
                 self._logger.warning(
-                    "Received a suspension event for flow run %s, but state %s has"
-                    " not become readable within %s seconds; continuing to retry.",
+                    "Received a suspension event for flow run %s, but its state %s"
+                    " has not become visible within %s seconds; continuing to"
+                    " retry.",
                     self.flow_run_id,
                     state_id,
                     SUSPENSION_CONFIRMATION_WARNING_AFTER,

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/client/orchestration/_work_pools/client.py

@@ -48,7 +48,7 @@ class WorkPoolClient(BaseClient):
         Args:
             work_pool_name: The name of the work pool to heartbeat against.
             worker_name: The name of the worker sending the heartbeat.
-            return_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `return_id` is `True`.
+            get_worker_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `get_worker_id` is `True`.
             worker_metadata: Metadata about the worker to send to the server.
         """
         from uuid import UUID
@@ -376,7 +376,7 @@ class WorkPoolAsyncClient(BaseAsyncClient):
         Args:
             work_pool_name: The name of the work pool to heartbeat against.
             worker_name: The name of the worker sending the heartbeat.
-            return_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `return_id` is `True`.
+            get_worker_id: Whether to return the worker ID. Note: will return `None` if the connected server does not support returning worker IDs, even if `get_worker_id` is `True`.
             worker_metadata: Metadata about the worker to send to the server.
         """
         from uuid import UUID

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/client/schemas/objects.py

@@ -1477,7 +1477,7 @@ class WorkQueueHealthPolicy(PrefectBaseModel):
         Given empirical information about the state of the work queue, evaluate its health status.
 
         Args:
-            late_runs: the count of late runs for the work queue.
+            late_runs_count: the count of late runs for the work queue.
             last_polled: the last time the work queue was polled, if available.
 
         Returns:

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/concurrency/_asyncio.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import concurrent.futures
 import logging
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, AsyncGenerator, Literal, Optional
@@ -150,6 +151,9 @@ async def aacquire_concurrency_slots_with_lease(
     )
     try:
         response = await asyncio.wrap_future(future)
+    except asyncio.CancelledError:
+        _release_lease_when_granted(service, future)
+        raise
     except TimeoutError as timeout:
         raise AcquireConcurrencySlotTimeoutError(
             f"Attempt to acquire concurrency slots timed out after {timeout_seconds} second(s)"
@@ -225,6 +229,28 @@ def _discard_cleanup_lease(lease_id: UUID) -> None:
         ctx.cleanup_lease_ids.remove(lease_id)
 
 
+def _release_lease_when_granted(
+    service: ConcurrencySlotAcquisitionWithLeaseService,
+    future: "concurrent.futures.Future[httpx.Response]",
+) -> None:
+    """Release the lease for an acquisition whose caller has been cancelled.
+
+    The acquisition may still be granted after the caller is gone, and the lease
+    id never reaches the `ConcurrencyContext`, so the slots would stay occupied
+    until the lease expires. The cancelled caller cannot do the release itself, so
+    the service that acquired the slots is asked to release them.
+    """
+
+    def _release(completed: "concurrent.futures.Future[httpx.Response]") -> None:
+        if completed.cancelled() or completed.exception() is not None:
+            # Nothing was granted, so there is nothing to release.
+            return
+
+        service.release_orphaned_lease(completed.result())
+
+    future.add_done_callback(_release)
+
+
 def _response_to_minimal_concurrency_limit_response(
     response: httpx.Response,
 ) -> list[MinimalConcurrencyLimitResponse]:

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/concurrency/services.py

@@ -1,10 +1,11 @@
 import asyncio
+import concurrent.futures
 import json
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from threading import Lock
 from typing import TYPE_CHECKING, Literal, Optional
-from uuid import uuid4
+from uuid import UUID, uuid4
 
 import cachetools
 import httpx
@@ -104,12 +105,25 @@ class ConcurrencySlotAcquisitionWithLeaseService(
         super().__init__(concurrency_limit_names)
         self._client: PrefectClient
         self.concurrency_limit_names: list[str] = sorted(list(concurrency_limit_names))
+        self._pending_releases: set[concurrent.futures.Future[None]] = set()
 
     @asynccontextmanager
     async def _lifespan(self) -> AsyncGenerator[None, None]:
         async with get_client() as client:
             self._client = client
-            yield
+            try:
+                yield
+            finally:
+                # The client closes when this exits, so releases scheduled by
+                # cancelled callers have to finish first or their slots leak.
+                if self._pending_releases:
+                    await asyncio.gather(
+                        *(
+                            asyncio.wrap_future(release)
+                            for release in tuple(self._pending_releases)
+                        ),
+                        return_exceptions=True,
+                    )
 
     async def acquire(
         self,
@@ -185,6 +199,74 @@ class ConcurrencySlotAcquisitionWithLeaseService(
                     if max_retries is not None:
                         max_retries -= 1
 
+    async def _discard(self, response: httpx.Response) -> None:
+        """Release a lease granted to a caller that was cancelled while waiting.
+
+        Without this the slots stay occupied until the lease expires, because the
+        caller never learns the lease id and so cannot record it for cleanup.
+        """
+        lease_id = self._lease_id_from_response(response)
+        if lease_id is None:
+            return
+
+        try:
+            await self._client.release_concurrency_slots_with_lease(lease_id=lease_id)
+        except Exception:
+            logger.warning(
+                f"Failed to release concurrency lease {lease_id} for "
+                f"{self.concurrency_limit_names} after the acquiring caller was cancelled",
+                exc_info=True,
+            )
+
+    def release_orphaned_lease(
+        self, response: httpx.Response
+    ) -> "concurrent.futures.Future[None]":
+        """Release a lease that was delivered to a caller which is already gone.
+
+        The release is scheduled on the service's own loop so it reuses the client
+        that acquired the slots, keeping acquisition and cleanup on the same API, and
+        is tracked so that draining the service waits for it.
+        """
+        with self._lock:
+            loop = self._loop
+            if self._stopped or loop is None or loop.is_closed():
+                logger.warning(
+                    f"Unable to release concurrency lease for {self.concurrency_limit_names} "
+                    "after the acquiring caller was cancelled: the acquisition service is "
+                    "no longer running. The slots remain occupied until the lease expires."
+                )
+                stopped: concurrent.futures.Future[None] = concurrent.futures.Future()
+                stopped.set_result(None)
+                return stopped
+
+            # Registering under the lock `_stop` uses keeps the service from
+            # finishing its lifespan, and closing its client, before this release.
+            release = asyncio.run_coroutine_threadsafe(self._discard(response), loop)
+            self._pending_releases.add(release)
+
+        release.add_done_callback(self._pending_releases.discard)
+        return release
+
+    def _lease_id_from_response(self, response: httpx.Response) -> Optional[UUID]:
+        """Read the lease id out of a successful acquisition response.
+
+        Returns `None` when no slots were acquired, and logs when the response is
+        malformed, since that leaves a possibly active lease we cannot release.
+        """
+        try:
+            data = response.json()
+            if not data.get("limits"):
+                return None
+            return UUID(data["lease_id"])
+        except Exception:
+            logger.warning(
+                f"Unable to read the lease id from the acquisition response for "
+                f"{self.concurrency_limit_names}; if a lease was granted its slots "
+                "remain occupied until it expires.",
+                exc_info=True,
+            )
+            return None
+
 
 def _should_use_cache(
     names: list[str], holder: Optional["ConcurrencyLeaseHolder"]

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/context.py

@@ -994,7 +994,7 @@ def use_profile(
 
     Args:
         profile: The name of the profile to load or an instance of a Profile.
-        override_environment_variable: If set, variables in the profile will take
+        override_environment_variables: If set, variables in the profile will take
             precedence over current environment variables. By default, environment
             variables will override profile settings.
         include_current_context: If set, the new settings will be constructed

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/events/clients.py

@@ -1,5 +1,6 @@
 import abc
 import asyncio
+import base64
 from datetime import timedelta
 from types import TracebackType
 from typing import (
@@ -252,6 +253,11 @@ class AssertingEventsClient(EventsClient):
         return self
 
 
+def _basic_auth_token(auth_string: str) -> str:
+    """Encode an auth string of the form 'user:password' for basic authentication"""
+    return base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")
+
+
 def _get_api_url_and_key(
     api_url: Optional[str], api_key: Optional[str]
 ) -> Tuple[str, str]:
@@ -303,10 +309,15 @@ class PrefectEventsClient(EventsClient):
             auth_string.get_secret_value() if auth_string is not None else None
         )
         self._events_socket_url = events_in_socket_from_api_url(api_url)
-        self._connect = websocket_connect(
-            self._events_socket_url,
-            subprotocols=[Subprotocol("prefect")],
-        )
+        connect_kwargs: Dict[str, Any] = {"subprotocols": [Subprotocol("prefect")]}
+        if self._auth_token:
+            # Servers and proxies that require basic authentication reject the
+            # HTTP upgrade request before the "prefect" subprotocol auth
+            # handshake can run, so also send the credentials as a header.
+            connect_kwargs["additional_headers"] = {
+                "Authorization": f"Basic {_basic_auth_token(self._auth_token)}"
+            }
+        self._connect = websocket_connect(self._events_socket_url, **connect_kwargs)
         self._websocket = None
         self._reconnection_attempts = reconnection_attempts
         self._unconfirmed_events = []
@@ -718,7 +729,6 @@ class PrefectEventSubscriber:
         """
         Args:
             api_url: The base URL for a Prefect Cloud workspace
-            api_key: The API of an actor with the manage_events scope
             reconnection_attempts: When the client is disconnected, how many times
                 the client should attempt to reconnect
             reconnect_on_clean_close: Whether to reconnect when the server closes

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/flows.py

@@ -1507,7 +1507,7 @@ class Flow(Generic[P, R]):
                 parameter schema for the created deployment.
             entrypoint_type: Type of entrypoint to use for the deployment. When using a module path
                 entrypoint, ensure that the module will be importable in the execution environment.
-            print_next_steps_message: Whether or not to print a message with next steps
+            print_next_steps: Whether or not to print a message with next steps
                 after deploying the deployments.
             ignore_warnings: Whether or not to ignore warnings about the work pool type.
             _sla: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.
@@ -1705,7 +1705,7 @@ class Flow(Generic[P, R]):
                 parameter schema for the created deployment.
             entrypoint_type: Type of entrypoint to use for the deployment. When using a module path
                 entrypoint, ensure that the module will be importable in the execution environment.
-            print_next_steps_message: Whether or not to print a message with next steps
+            print_next_steps: Whether or not to print a message with next steps
                 after deploying the deployments.
             ignore_warnings: Whether or not to ignore warnings about the work pool type.
             _sla: (Experimental) SLA configuration for the deployment. May be removed or modified at any time. Currently only supported on Prefect Cloud.
@@ -2562,7 +2562,6 @@ class InfrastructureBoundFlow(Flow[P, R]):
 
         Args:
             flow_run: The existing flow run to retry
-            return_state: If True, return the final state instead of the result
 
         Returns:
             The flow result or final state
@@ -3135,6 +3134,7 @@ async def aserve(
 
         if __name__ == "__main__":
             asyncio.run(main())
+        ```
     """
 
     from prefect.runner import Runner

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/infrastructure/provisioners/container_instance.py

@@ -592,7 +592,7 @@ class ContainerInstancePushProvisioner:
         Logs into the given Azure Container Registry.
 
         Args:
-            registry_name: The name of the registry to log into.
+            login_server: The login server of the registry to log into.
 
         Raises:
             subprocess.CalledProcessError: If the Azure CLI command execution fails.

prefect_client-3.8.3/src/prefect/runner/_uv_command.py

@@ -0,0 +1,90 @@
+"""Auto-`uv run` launcher command construction shared by runner and worker paths."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Iterable
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+from prefect._internal.compatibility.backports import tomllib
+from prefect.settings import get_current_settings
+from prefect.utilities.processutils import command_to_string
+
+
+def _dependencies_include_prefect(dependencies: object) -> bool:
+    if not isinstance(dependencies, Iterable) or isinstance(dependencies, (str, bytes)):
+        return False
+
+    for dependency in dependencies:
+        if not isinstance(dependency, str):
+            continue
+        try:
+            name = Requirement(dependency).name
+        except InvalidRequirement:
+            continue
+        if canonicalize_name(name) == "prefect":
+            return True
+    return False
+
+
+def _pyproject_declares_prefect_dependency(pyproject: Path) -> bool:
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return False
+
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return False
+
+    return _dependencies_include_prefect(project.get("dependencies"))
+
+
+def uv_project_command(
+    project_root: Path | None,
+    engine_args: Iterable[str],
+    path: str | None = None,
+    auto_install_dependencies: bool | None = None,
+) -> str | None:
+    """Build an auto-`uv run` command for a project directory, if applicable.
+
+    Returns `None` unless dependency auto-installation is enabled, `project_root`
+    contains a `pyproject.toml` declaring `prefect` as a project dependency, and
+    `uv` is discoverable on `path` (or the current `PATH` when `path` is `None`).
+
+    `auto_install_dependencies` overrides the current setting value, for callers
+    that resolve the setting from a run-specific environment.
+    """
+    if auto_install_dependencies is None:
+        auto_install_dependencies = (
+            get_current_settings().runner.auto_install_dependencies
+        )
+    if not auto_install_dependencies:
+        return None
+
+    if project_root is None:
+        return None
+
+    pyproject = project_root / "pyproject.toml"
+    if not pyproject.is_file() or not _pyproject_declares_prefect_dependency(pyproject):
+        return None
+
+    uv_executable = (
+        shutil.which("uv", path=path) if path is not None else shutil.which("uv")
+    )
+    if uv_executable is None:
+        return None
+
+    return command_to_string(
+        [
+            uv_executable,
+            "run",
+            "--no-default-groups",
+            "--project",
+            str(project_root),
+            *engine_args,
+        ]
+    )

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/runner/_workspace_starter.py

@@ -2,26 +2,23 @@ from __future__ import annotations
 
 import functools
 import os
-import shutil
 import site
 import subprocess
 import sys
 import sysconfig
 from contextlib import contextmanager
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Iterable, Iterator
+from typing import TYPE_CHECKING, Any, Iterator
 from uuid import UUID
 
 import anyio
 import anyio.abc
-from packaging.requirements import InvalidRequirement, Requirement
-from packaging.utils import canonicalize_name
 
-from prefect._internal.compatibility.backports import tomllib
 from prefect.exceptions import MissingFlowError
 from prefect.flows import load_flow_from_entrypoint, load_function_and_convert_to_flow
 from prefect.runner._process_manager import ProcessHandle
 from prefect.runner._starter_engine import EngineCommandStarter
+from prefect.runner._uv_command import uv_project_command
 from prefect.runner._workspace_resolver import (
     PreparedWorkspace,
     PreparedWorkspaceResult,
@@ -29,7 +26,7 @@ from prefect.runner._workspace_resolver import (
 )
 from prefect.settings import get_current_settings
 from prefect.utilities.asyncutils import run_sync_in_worker_thread
-from prefect.utilities.processutils import command_to_string, sanitize_subprocess_env
+from prefect.utilities.processutils import sanitize_subprocess_env
 
 if TYPE_CHECKING:
     from prefect.client.schemas.objects import FlowRun
@@ -217,67 +214,11 @@ def _absolute_file_entrypoint(workspace: PreparedWorkspace) -> str:
     return f"{entrypoint_path.resolve()}:{object_name}"
 
 
-def _dependencies_include_prefect(dependencies: object) -> bool:
-    if not isinstance(dependencies, Iterable) or isinstance(dependencies, (str, bytes)):
-        return False
-
-    for dependency in dependencies:
-        if not isinstance(dependency, str):
-            continue
-        try:
-            name = Requirement(dependency).name
-        except InvalidRequirement:
-            continue
-        if canonicalize_name(name) == "prefect":
-            return True
-    return False
-
-
-def _pyproject_declares_prefect_dependency(pyproject: Path) -> bool:
-    try:
-        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
-    except (OSError, tomllib.TOMLDecodeError):
-        return False
-
-    project = data.get("project")
-    if not isinstance(project, dict):
-        return False
-
-    return _dependencies_include_prefect(project.get("dependencies"))
-
-
 def _uv_run_command(workspace: PreparedWorkspace) -> str | None:
-    if not get_current_settings().runner.auto_install_dependencies:
-        return None
-
-    project_root = workspace.project_root
-    if project_root is None:
-        return None
-
-    pyproject = project_root / "pyproject.toml"
-    if not pyproject.is_file() or not _pyproject_declares_prefect_dependency(pyproject):
-        return None
-
-    workspace_path = workspace.environment.get("PATH")
-    uv_executable = (
-        shutil.which("uv", path=workspace_path)
-        if workspace_path is not None
-        else shutil.which("uv")
-    )
-    if uv_executable is None:
-        return None
-
-    return command_to_string(
-        [
-            uv_executable,
-            "run",
-            "--no-default-groups",
-            "--project",
-            str(project_root),
-            "-m",
-            "prefect.flow_engine",
-            workspace.runtime_entrypoint,
-        ]
+    return uv_project_command(
+        workspace.project_root,
+        ["-m", "prefect.flow_engine", workspace.runtime_entrypoint],
+        path=workspace.environment.get("PATH"),
     )
 
 

{prefect_client-3.8.2.dev5 → prefect_client-3.8.3}/src/prefect/runner/storage.py

@@ -217,6 +217,9 @@ class GitRepository:
                 "Cannot provide both a branch and a commit SHA. Please provide only one."
             )
 
+        if branch and branch.startswith("-"):
+            raise ValueError("Branch names cannot start with '-'.")
+
         if commit_sha and not re.match(r"^[0-9a-fA-F]{4,64}$", commit_sha):
             raise ValueError(
                 f"Invalid commit SHA: {commit_sha!r}."
@@ -931,7 +934,7 @@ class LocalStorage:
     """
     Sets the working directory in the local filesystem.
     Parameters:
-        Path: Local file path to set the working directory for the flow
+        path: Local file path to set the working directory for the flow
     Examples:
         Sets the working directory for the local path to the flow:
         ```python
@@ -996,7 +999,7 @@ def create_storage_from_source(
     Creates a storage object from a URL.
 
     Args:
-        url: The URL to create a storage object from. Supports git and `fsspec`
+        source: The URL to create a storage object from. Supports git and `fsspec`
             URLs.
         pull_interval: The interval at which to pull contents from remote storage to
             local storage