chore: release v3.1.0

Author: kiarina

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-06-10
+
+### Added
+
+- Multi mode now automatically falls back to `DEFAULT_KEY` (`"default"`) when no active or default configuration is explicitly set.
+
 ## [3.0.0] - 2026-06-10
 
 ### Breaking Changes

pydantic_settings_manager/manager.py

@@ -143,26 +143,34 @@ def settings(self) -> T:
 
             target_key = self._active_key if self._active_key is not None else self._default_key
 
-            if target_key is not None:
-                # Resolve alias if target_key is an alias
-                resolved_key = self._resolve_alias(target_key)
-
-                if resolved_key not in self._cache:
-                    # Show both original and resolved key in error message if different
-                    if target_key != resolved_key:
-                        raise ValueError(
-                            f"Key '{target_key}' (resolved to '{resolved_key}') "
-                            f"does not exist in settings map"
-                        )
-                    else:
-                        raise ValueError(f"Key '{target_key}' does not exist in settings map")
-
-                return self._cache[resolved_key]
+            if target_key is None:
+                target_key = DEFAULT_KEY
 
-            raise ValueError(
-                "No active or default configuration is set. Set `manager.active_key`, "
-                "add `default` to user_config, or call `get_settings(<name>)`."
-            )
+            # Resolve alias if target_key is an alias
+            resolved_key = self._resolve_alias(target_key)
+
+            if resolved_key not in self._cache:
+                if (
+                    self._active_key is None
+                    and self._default_key is None
+                    and target_key == DEFAULT_KEY
+                ):
+                    raise ValueError(
+                        "No active or default configuration is set, "
+                        f"and fallback key '{DEFAULT_KEY}' does not exist in settings map. "
+                        "Set `manager.active_key`, add `default` to user_config, "
+                        "or use 'default' as a config key."
+                    )
+                # Show both original and resolved key in error message if different
+                if target_key != resolved_key:
+                    raise ValueError(
+                        f"Key '{target_key}' (resolved to '{resolved_key}') "
+                        f"does not exist in settings map"
+                    )
+                else:
+                    raise ValueError(f"Key '{target_key}' does not exist in settings map")
+
+            return self._cache[resolved_key]
 
     @property
     def user_config(self) -> dict[str, Any]:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-settings-manager"
-version = "3.0.0"
+version = "3.1.0"
 description = "A library for managing Pydantic settings objects"
 authors = [
     { name = "kiarina", email = "kiarinadawa@gmail.com" }

tests/test_manager.py

@@ -197,10 +197,25 @@ def test_no_default_and_no_active_key_raises_on_settings() -> None:
             "production": {"debug": False},
         },
     }
-    with pytest.raises(ValueError, match="No active or default configuration is set"):
+    with pytest.raises(
+        ValueError,
+        match="No active or default configuration is set, and fallback key 'default'",
+    ):
         _ = manager.settings
 
 
+def test_no_default_falls_back_to_default_key() -> None:
+    manager = SettingsManager(ExampleSettings, multi=True)
+    manager.user_config = {
+        "configs": {
+            "default": {"debug": True},
+            "production": {"debug": False},
+        },
+    }
+    # Should fallback to DEFAULT_KEY ("default")
+    assert manager.settings.debug is True
+
+
 # Multi Mode Tests