prefect-client 3.7.9.dev4__tar.gz → 3.7.9.dev5__tar.gz

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/PKG-INFO

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

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

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.9.dev5"
+__build_date__ = "2026-07-21 08:58:32.807456+00:00"
+__git_commit__ = "e8d311f1f3f3b947f585f520f9dcfd9e96720dce"
+__dirty__ = False

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/client/orchestration/__init__.py

@@ -123,7 +123,7 @@ from prefect.client.schemas.sorting import (
 from prefect.logging import get_logger
 from prefect.settings import (
     PREFECT_API_AUTH_STRING,
-    PREFECT_API_DATABASE_CONNECTION_URL,
+    PREFECT_SERVER_DATABASE_CONNECTION_URL,
     PREFECT_API_ENABLE_HTTP2,
     PREFECT_API_KEY,
     PREFECT_API_REQUEST_TIMEOUT,
@@ -132,7 +132,7 @@ from prefect.settings import (
     PREFECT_API_URL,
     PREFECT_CLIENT_CSRF_SUPPORT_ENABLED,
     PREFECT_CLOUD_API_URL,
-    PREFECT_SERVER_ALLOW_EPHEMERAL_MODE,
+    PREFECT_SERVER_EPHEMERAL_ENABLED,
     PREFECT_TESTING_UNIT_TEST_MODE,
 )
 from prefect.types._datetime import now
@@ -245,7 +245,7 @@ def get_client(
     api: str = PREFECT_API_URL.value()
     server_type = None
 
-    if not api and PREFECT_SERVER_ALLOW_EPHEMERAL_MODE:
+    if not api and PREFECT_SERVER_EPHEMERAL_ENABLED:
         # create an ephemeral API if none was provided
         from prefect.server.api.server import SubprocessASGIServer
 
@@ -255,7 +255,7 @@ def get_client(
 
         api = server.api_url
         server_type = ServerType.EPHEMERAL
-    elif not api and not PREFECT_SERVER_ALLOW_EPHEMERAL_MODE:
+    elif not api and not PREFECT_SERVER_EPHEMERAL_ENABLED:
         raise ValueError(
             "No Prefect API URL provided. Please set PREFECT_API_URL to the address of a running Prefect server."
         )
@@ -933,7 +933,7 @@ class PrefectClient(
             deployment_filter: filter criteria for deployments
             sort: sort criteria for the task runs
             limit: maximum number of task runs to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the task run query.
 
         Returns:
@@ -1040,7 +1040,7 @@ class PrefectClient(
             work_pool_name: Name of the work pool for which to get queues.
             work_queue_filter: Criteria by which to filter queues.
             limit: maximum number of work queues to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the work queue query.
 
         Returns:
@@ -1190,7 +1190,7 @@ class PrefectClient(
         if self._ephemeral_app:
             self.logger.debug(
                 "Using ephemeral application with database at "
-                f"{PREFECT_API_DATABASE_CONNECTION_URL.value()}"
+                f"{PREFECT_SERVER_DATABASE_CONNECTION_URL.value()}"
             )
         else:
             self.logger.debug(
@@ -1672,7 +1672,7 @@ class SyncPrefectClient(
             deployment_filter: filter criteria for deployments
             sort: sort criteria for the task runs
             limit: maximum number of task runs to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the task run query.
 
         Returns:
@@ -2082,7 +2082,7 @@ class SyncPrefectClient(
             work_pool_name: Name of the work pool for which to get queues.
             work_queue_filter: Criteria by which to filter queues.
             limit: maximum number of work queues to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the work queue query.
 
         Returns:

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/client/orchestration/_deployments/client.py

@@ -399,7 +399,7 @@ class DeploymentClient(BaseClient):
             work_pool_filter: filter criteria for work pools
             work_queue_filter: filter criteria for work pool queues
             limit: maximum number of deployments to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the deployment query.
 
         Returns:
@@ -1113,7 +1113,7 @@ class DeploymentAsyncClient(BaseAsyncClient):
             work_pool_filter: filter criteria for work pools
             work_queue_filter: filter criteria for work pool queues
             limit: maximum number of deployments to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the deployment query.
 
         Returns:

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/client/orchestration/_flow_runs/client.py

@@ -282,7 +282,7 @@ class FlowRunClient(BaseClient):
             work_queue_filter: filter criteria for work pool queues
             sort: sort criteria for the flow runs
             limit: maximum number of flow runs to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the flow run query.
 
         Returns:
@@ -782,7 +782,7 @@ class FlowRunAsyncClient(BaseAsyncClient):
             work_queue_filter: filter criteria for work pool queues
             sort: sort criteria for the flow runs
             limit: maximum number of flow runs to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the flow run query.
 
         Returns:

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/client/orchestration/_flows/client.py

@@ -129,7 +129,7 @@ class FlowClient(BaseClient):
             work_queue_filter: filter criteria for work pool queues
             sort: sort criteria for the flows
             limit: maximum number of flows to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the flow query.
 
         Returns:
@@ -289,7 +289,7 @@ class FlowAsyncClient(BaseAsyncClient):
             work_queue_filter: filter criteria for work pool queues
             sort: sort criteria for the flows
             limit: maximum number of flows to return. When `None`, the server
-                applies `PREFECT_API_DEFAULT_LIMIT` (200 by default).
+                applies `PREFECT_SERVER_API_DEFAULT_LIMIT` (200 by default).
             offset: an offset for the flow query.
 
         Returns:

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/client/schemas/filters.py

@@ -441,8 +441,12 @@ class TaskRunFilterStateName(PrefectBaseModel):
 
 
 class TaskRunFilterState(PrefectBaseModel, OperatorMixin):
-    type: Optional[TaskRunFilterStateType]
-    name: Optional[TaskRunFilterStateName]
+    type: Optional[TaskRunFilterStateType] = Field(
+        default=None, description="Filter criteria for `TaskRun` state type"
+    )
+    name: Optional[TaskRunFilterStateName] = Field(
+        default=None, description="Filter criteria for `TaskRun` state name"
+    )
 
 
 class TaskRunFilterSubFlowRuns(PrefectBaseModel):

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/concurrency/_asyncio.py

@@ -183,6 +183,15 @@ async def aacquire_concurrency_slots_with_lease(
                 log_level,
                 f"Concurrency limits {names!r} do not exist - skipping acquisition.",
             )
+    elif ctx := ConcurrencyContext.get():
+        # Record the lease for cleanup the moment it is granted. In the sync
+        # path this coroutine runs to completion on a separate event loop thread
+        # that the caller's timeout/cancellation cannot reach, so a cancellation
+        # firing in the calling thread the instant the lease is granted can no
+        # longer lose the lease id and leak the slot. The normal release path
+        # removes it again; anything left over is released idempotently when the
+        # ConcurrencyContext exits.
+        ctx.cleanup_lease_ids.append(retval.lease_id)
 
     return retval
 
@@ -204,6 +213,18 @@ async def arelease_concurrency_slots_with_lease(
         await client.release_concurrency_slots_with_lease(lease_id=lease_id)
 
 
+def _discard_cleanup_lease(lease_id: UUID) -> None:
+    """Drop a lease id recorded for cleanup once it has been released normally.
+
+    Leases are recorded on the active `ConcurrencyContext` the moment they are
+    acquired; this removes one after a successful release so the context does not
+    re-release it on exit.
+    """
+    ctx = ConcurrencyContext.get()
+    if ctx is not None and lease_id in ctx.cleanup_lease_ids:
+        ctx.cleanup_lease_ids.remove(lease_id)
+
+
 def _response_to_minimal_concurrency_limit_response(
     response: httpx.Response,
 ) -> list[MinimalConcurrencyLimitResponse]:
@@ -300,10 +321,11 @@ async def concurrency(
                 lease_id=response.lease_id,
             )
         except anyio.get_cancelled_exc_class():
-            # The task was cancelled before it could release the lease. Add the
-            # lease ID to the cleanup list so it can be released when the
-            # concurrency context is exited.
-            if ctx := ConcurrencyContext.get():
-                ctx.cleanup_lease_ids.append(response.lease_id)
+            # The task was cancelled before it could release the lease. Leave the
+            # lease ID in the cleanup list (recorded at acquisition) so it is
+            # released when the concurrency context is exited.
+            pass
+        else:
+            _discard_cleanup_lease(response.lease_id)
 
         emit_concurrency_release_events(response.limits, occupy, emitted_events)

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/concurrency/_sync.py

@@ -11,6 +11,7 @@ from prefect.client.schemas.responses import (
     MinimalConcurrencyLimitResponse,
 )
 from prefect.concurrency._asyncio import (
+    _discard_cleanup_lease,
     aacquire_concurrency_slots,
     aacquire_concurrency_slots_with_lease,
     arelease_concurrency_slots_with_lease,
@@ -20,7 +21,6 @@ from prefect.concurrency._events import (
     emit_concurrency_release_events,
 )
 from prefect.concurrency._leases import maintain_concurrency_lease
-from prefect.concurrency.context import ConcurrencyContext
 from prefect.utilities.asyncutils import run_coro_as_sync
 
 
@@ -159,11 +159,12 @@ def concurrency(
         try:
             release_concurrency_slots_with_lease(acquisition_response.lease_id)
         except CancelledError:
-            # The task was cancelled before it could release the lease. Add the
-            # lease ID to the cleanup list so it can be released when the
-            # concurrency context is exited.
-            if ctx := ConcurrencyContext.get():
-                ctx.cleanup_lease_ids.append(acquisition_response.lease_id)
+            # The task was cancelled before it could release the lease. Leave the
+            # lease ID in the cleanup list (recorded at acquisition) so it is
+            # released when the concurrency context is exited.
+            pass
+        else:
+            _discard_cleanup_lease(acquisition_response.lease_id)
 
         emit_concurrency_release_events(
             acquisition_response.limits, occupy, emitted_events

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/deployments/runner.py

@@ -98,7 +98,7 @@ from prefect.exceptions import (
 from prefect.runner.storage import RunnerStorage
 from prefect.schedules import Schedule
 from prefect.settings import (
-    PREFECT_DEFAULT_WORK_POOL_NAME,
+    PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME,
     PREFECT_UI_URL,
 )
 from prefect.types import ListOfNonEmptyStrings
@@ -1446,7 +1446,7 @@ async def adeploy(
     Args:
         *deployments: A list of deployments to deploy.
         work_pool_name: The name of the work pool to use for these deployments. Defaults to
-            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
+            the value of `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME`.
         image: The name of the Docker image to build, including the registry and
             repository. Pass a DockerImage instance to customize the Dockerfile used
             and build arguments.
@@ -1483,7 +1483,9 @@ async def adeploy(
             )
         ```
     """
-    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()
+    work_pool_name = (
+        work_pool_name or PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME.value()
+    )
 
     if not image and not all(
         d.storage or d.entrypoint_type == EntrypointType.MODULE_PATH
@@ -1498,7 +1500,7 @@ async def adeploy(
         raise ValueError(
             "A work pool name must be provided when deploying a deployment. Either"
             " provide a work pool name when calling `deploy` or set"
-            " `PREFECT_DEFAULT_WORK_POOL_NAME` in your profile."
+            " `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME` in your profile."
         )
 
     if image and isinstance(image, str):
@@ -1685,7 +1687,7 @@ def deploy(
     Args:
         *deployments: A list of deployments to deploy.
         work_pool_name: The name of the work pool to use for these deployments. Defaults to
-            the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
+            the value of `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME`.
         image: The name of the Docker image to build, including the registry and
             repository. Pass a DockerImage instance to customize the Dockerfile used
             and build arguments.
@@ -1722,7 +1724,9 @@ def deploy(
             )
         ```
     """
-    work_pool_name = work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()
+    work_pool_name = (
+        work_pool_name or PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME.value()
+    )
 
     if not image and not all(
         d.storage or d.entrypoint_type == EntrypointType.MODULE_PATH
@@ -1737,7 +1741,7 @@ def deploy(
         raise ValueError(
             "A work pool name must be provided when deploying a deployment. Either"
             " provide a work pool name when calling `deploy` or set"
-            " `PREFECT_DEFAULT_WORK_POOL_NAME` in your profile."
+            " `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME` in your profile."
         )
 
     if image and isinstance(image, str):

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/flows.py

@@ -74,7 +74,7 @@ from prefect.logging.loggers import flow_run_logger
 from prefect.results import ResultSerializer, ResultStorage
 from prefect.schedules import Schedule
 from prefect.settings import (
-    PREFECT_DEFAULT_WORK_POOL_NAME,
+    PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME,
     PREFECT_FLOW_DEFAULT_RETRIES,
     PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS,
     PREFECT_TESTING_UNIT_TEST_MODE,
@@ -1468,7 +1468,7 @@ class Flow(Generic[P, R]):
         Args:
             name: The name to give the created deployment.
             work_pool_name: The name of the work pool to use for this deployment. Defaults to
-                the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
+                the value of `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME`.
             image: The name of the Docker image to build, including the registry and
                 repository. Pass a DockerImage instance to customize the Dockerfile used
                 and build arguments.
@@ -1534,11 +1534,12 @@ class Flow(Generic[P, R]):
             ```
         """
         if not (
-            work_pool_name := work_pool_name or PREFECT_DEFAULT_WORK_POOL_NAME.value()
+            work_pool_name := work_pool_name
+            or PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME.value()
         ):
             raise ValueError(
                 "No work pool name provided. Please provide a `work_pool_name` or set the"
-                " `PREFECT_DEFAULT_WORK_POOL_NAME` environment variable."
+                " `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME` environment variable."
             )
 
         from prefect.client.orchestration import get_client
@@ -1665,7 +1666,7 @@ class Flow(Generic[P, R]):
         Args:
             name: The name to give the created deployment.
             work_pool_name: The name of the work pool to use for this deployment. Defaults to
-                the value of `PREFECT_DEFAULT_WORK_POOL_NAME`.
+                the value of `PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME`.
             image: The name of the Docker image to build, including the registry and
                 repository. Pass a DockerImage instance to customize the Dockerfile used
                 and build arguments.

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/server/api/dependencies.py

@@ -17,7 +17,7 @@ from starlette.requests import Request
 
 from prefect._internal.compatibility.starlette import status
 from prefect.server import schemas
-from prefect.settings import PREFECT_API_DEFAULT_LIMIT
+from prefect.settings import PREFECT_SERVER_API_DEFAULT_LIMIT
 
 
 def provide_request_api_version(
@@ -111,10 +111,10 @@ def LimitBody() -> Any:
     def get_limit(
         limit: int = Body(
             None,
-            description="Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.",
+            description="Defaults to PREFECT_SERVER_API_DEFAULT_LIMIT if not provided.",
         ),
     ):
-        default_limit = PREFECT_API_DEFAULT_LIMIT.value()
+        default_limit = PREFECT_SERVER_API_DEFAULT_LIMIT.value()
         limit = limit if limit is not None else default_limit
         if not limit >= 0:
             raise HTTPException(

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/settings/__init__.py

@@ -34,12 +34,12 @@ if TYPE_CHECKING:
 
 def __getattr__(name: str) -> "Setting":
     from prefect.settings.legacy import (
-        _get_settings_fields,
+        _get_legacy_setting,
         _get_valid_setting_names,
     )
 
     if name in _get_valid_setting_names(Settings):
-        return _get_settings_fields(Settings)[name]
+        return _get_legacy_setting(name)
     raise AttributeError(f"{name} is not a Prefect setting.")
 
 

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/settings/legacy.py

@@ -140,28 +140,43 @@ def _get_settings_fields(
                 if accessor_prefix is None
                 else f"{accessor_prefix}.{field_name}"
             )
+            canonical_name = (
+                f"{settings.model_config.get('env_prefix')}{field_name.upper()}"
+            )
+            setting = Setting(
+                name=canonical_name,
+                default=field.default,
+                type_=field.annotation,
+                accessor=accessor,
+            )
+            settings_fields[canonical_name] = setting
+            settings_fields[accessor] = setting
             if field.validation_alias and isinstance(
                 field.validation_alias, AliasChoices
             ):
                 for alias in field.validation_alias.choices:
                     if not isinstance(alias, str):
                         continue
-                    setting = Setting(
-                        name=alias.upper(),
-                        default=field.default,
-                        type_=field.annotation,
-                        accessor=accessor,
-                    )
-                    settings_fields[setting.name] = setting
-                    settings_fields[setting.accessor] = setting
-            else:
-                setting = Setting(
-                    name=f"{settings.model_config.get('env_prefix')}{field_name.upper()}",
-                    default=field.default,
-                    type_=field.annotation,
-                    accessor=accessor,
-                )
-                settings_fields[setting.name] = setting
-                settings_fields[setting.accessor] = setting
+                    settings_fields[alias.upper()] = setting
 
     return settings_fields
+
+
+@cache
+def _get_legacy_setting(name: str) -> "Setting":
+    """
+    Return a Setting object for the given env var name.
+
+    Canonical names and accessors resolve to the canonical Setting. Legacy aliases
+    resolve to a distinct Setting whose `.name` is the alias while its `.accessor`
+    points to the canonical setting path.
+    """
+    canonical = _get_settings_fields(Settings)[name]
+    if name == canonical.name or name == canonical.accessor:
+        return canonical
+    return Setting(
+        name=name,
+        default=canonical.default(),
+        type_=canonical._type,
+        accessor=canonical.accessor,
+    )

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/settings/models/server/ui.py

@@ -20,8 +20,8 @@ class ServerUISettings(PrefectBaseSettings):
     )
 
     v2_enabled: bool = Field(
-        default=False,
-        description="Whether neutral UI entry points should default to the experimental V2 UI instead of V1 when the browser has no saved UI preference.",
+        default=True,
+        description="Whether neutral UI entry points should default to the V2 UI instead of V1 when the browser has no saved UI preference. Set to false to restore V1 as the default for browsers without a saved preference.",
     )
 
     api_url: Optional[str] = Field(

{prefect_client-3.7.9.dev4 → prefect_client-3.7.9.dev5}/src/prefect/settings/profiles.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import warnings
+from collections.abc import Mapping
 from pathlib import Path
 from typing import (
     Annotated,
@@ -19,6 +20,7 @@ from pydantic import (
     Field,
     ValidationError,
 )
+from typing_extensions import Self
 
 from prefect._internal.compatibility.backports import tomllib
 from prefect.exceptions import ProfileSettingsValidationError
@@ -29,23 +31,147 @@ from prefect.settings.models.root import Settings
 from prefect.utilities.collections import set_in_dict
 
 
+class _SettingsDict(dict):
+    """
+    A dictionary that stores profile settings using canonical Setting keys while
+    allowing lookup via legacy Setting aliases.
+
+    Canonical names are used for persistence and export; legacy keys transparently
+    resolve to the canonical entry for `__getitem__`, `get`, `__contains__`,
+    assignment, union, and equality checks.
+    """
+
+    def _canonical_key(self, key: Any) -> Any:
+        if isinstance(key, Setting):
+            settings_fields = _get_settings_fields(Settings)
+            canonical = settings_fields.get(key.name)
+            if canonical is None:
+                canonical = settings_fields[key.accessor]
+            return canonical
+        if isinstance(key, str):
+            settings_fields = _get_settings_fields(Settings)
+            canonical = settings_fields.get(key)
+            if canonical is None:
+                canonical = settings_fields.get(key.upper())
+            return canonical if canonical is not None else key
+        return key
+
+    def __getitem__(self, key: Any) -> Any:
+        return super().__getitem__(self._canonical_key(key))
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        super().__setitem__(self._canonical_key(key), value)
+
+    def __delitem__(self, key: Any) -> None:
+        super().__delitem__(self._canonical_key(key))
+
+    def __contains__(self, key: Any) -> bool:
+        return super().__contains__(self._canonical_key(key))
+
+    def get(self, key: Any, default: Any = None) -> Any:  # type: ignore[override]
+        return super().get(self._canonical_key(key), default)
+
+    def pop(self, key: Any, *args: Any) -> Any:
+        return super().pop(self._canonical_key(key), *args)
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:  # type: ignore[override]
+        return super().setdefault(self._canonical_key(key), default)
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        if args:
+            if len(args) > 1:
+                raise TypeError("update expected at most 1 argument")
+            other = args[0]
+            if isinstance(other, Mapping):
+                for k, v in other.items():
+                    self[k] = v
+            else:
+                for k, v in other:
+                    self[k] = v
+        for k, v in kwargs.items():
+            self[k] = v
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        return dict(self) == {self._canonical_key(k): v for k, v in other.items()}
+
+    def __ne__(self, other: object) -> bool:
+        eq = self.__eq__(other)
+        if eq is NotImplemented:
+            return NotImplemented
+        return not eq
+
+    def __ior__(self, other: Any) -> Self:
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        self.update(other)
+        return self
+
+    def __or__(self, other: Any) -> "_SettingsDict":
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        result = _SettingsDict()
+        result.update(self)
+        result.update(other)
+        return result
+
+    def __ror__(self, other: Any) -> "_SettingsDict":
+        if not isinstance(other, Mapping):
+            return NotImplemented
+        result = _SettingsDict()
+        result.update(other)
+        result.update(self)
+        return result
+
+
 def _cast_settings(
     settings: dict[str | Setting, Any] | Any,
 ) -> dict[Setting, Any]:
-    """For backwards compatibility, allow either Settings objects as keys or string references to settings."""
+    """For backwards compatibility, allow either Settings objects as keys or string references to settings.
+
+    Canonical setting names take precedence over legacy aliases. If both a canonical
+    name and an alias are present for the same setting, the canonical value is used.
+    """
     if not isinstance(settings, dict):
         raise ValueError("Settings must be a dictionary.")
-    casted_settings = {}
+
+    casted_settings: dict[Setting, Any] = {}
+    canonical_keys: set[Setting] = set()
+
+    settings_fields = _get_settings_fields(Settings)
+
+    def _resolve_key(k: str | Setting) -> tuple[Setting, bool]:
+        if isinstance(k, Setting):
+            canonical = settings_fields.get(k.name)
+            if canonical is None:
+                canonical = settings_fields[k.accessor]
+            is_canonical = k.name == canonical.name
+            return canonical, is_canonical
+        setting = settings_fields[k]
+        return setting, k == setting.name or k == setting.accessor
+
+    # First pass: canonical keys win over aliases regardless of input order.
     for k, value in settings.items():
         try:
-            if isinstance(k, str):
-                setting = _get_settings_fields(Settings)[k]
-            else:
-                setting = k
-            casted_settings[setting] = value
+            setting, is_canonical = _resolve_key(k)
         except KeyError as e:
             warnings.warn(f"Setting {e} is not recognized")
             continue
+        if is_canonical:
+            casted_settings[setting] = value
+            canonical_keys.add(setting)
+
+    # Second pass: keep alias values only when no canonical key was provided.
+    for k, value in settings.items():
+        try:
+            setting, is_canonical = _resolve_key(k)
+        except KeyError:
+            continue
+        if is_canonical or setting in canonical_keys:
+            continue
+        casted_settings[setting] = value
+
     return casted_settings
 
 
@@ -66,6 +192,10 @@ class Profile(BaseModel):
     )
     source: Optional[Path] = None
 
+    def model_post_init(self, __context: Any) -> None:
+        if not isinstance(self.settings, _SettingsDict):
+            self.__dict__["settings"] = _SettingsDict(self.settings)
+
     def to_environment_variables(self) -> dict[str, str]:
         """Convert the profile settings to a dictionary of environment variables."""
         return {