Changes:

- return/yield values set
- explain how to easily build forwarders

docs/release-notes.md

@@ -6,6 +6,7 @@
 
 - Settings forwards and a liberalized settings_path parameter.
 - Assignments to the settings attribute.
+- `with_` and `set_` operations returning set object.
 
 ### Fixed
 

docs/specials.md

@@ -175,3 +175,51 @@ takes place in the main settings).
 
 You can also use the `with_...` functions with None. This disables the overwrite for the scope.
 It is used in set_instance when applying extensions.
+
+## Echoed values
+
+The `with_` and `set_` methods return the passed variable as contextmanager value.
+
+e.g.
+
+``` python
+
+with monkay.with_settings(Settings()) as new_settings:
+    # do things with the settings overwrite
+
+    # disable the overwrite
+    with monkay.with_settings(None) as new_settings2:
+        # echoed is None
+        assert new_settings2 is None
+        # settings are the old settings again
+        assert monkay.settings is old_settings
+
+```
+
+
+## Forwarder
+
+Sometimes you have an old settings place and want to forward it to the monkay one.
+Here does no helper exist but a forwarder is easy to write:
+
+``` python
+from typing import Any, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .global_settings import EdgySettings
+
+
+class SettingsForward:
+    def __getattribute__(self, name: str) -> Any:
+        import edgy
+
+        return getattr(edgy.monkay.settings, name)
+
+# we want to pretend the forward is the real object
+settings = cast("EdgySettings", SettingsForward())
+
+__all__ = ["settings"]
+
+
+
+```

monkay/base.py

@@ -258,7 +258,7 @@ def set_instance(
         *,
         apply_extensions: bool = True,
         use_extensions_overwrite: bool = True,
-    ) -> None:
+    ) -> INSTANCE | None:
         assert self._instance_var is not None, "Monkay not enabled for instances"
         # need to address before the instance is swapped
         if apply_extensions and self._extensions_applied_var.get() is not None:
@@ -268,6 +268,7 @@ def set_instance(
             # unapply a potential instance overwrite
             with self.with_instance(None):
                 self.apply_extensions(use_overwrite=use_extensions_overwrite)
+        return instance
 
     @contextmanager
     def with_instance(
@@ -276,7 +277,7 @@ def with_instance(
         *,
         apply_extensions: bool = False,
         use_extensions_overwrite: bool = True,
-    ) -> Generator:
+    ) -> Generator[INSTANCE | None]:
         assert self._instance_var is not None, "Monkay not enabled for instances"
         # need to address before the instance is swapped
         if apply_extensions and self._extensions_var is not None and self._extensions_applied_var.get() is not None:
@@ -285,7 +286,7 @@ def with_instance(
         try:
             if apply_extensions and self._extensions_var is not None:
                 self.apply_extensions(use_overwrite=use_extensions_overwrite)
-            yield
+            yield instance
         finally:
             self._instance_var.reset(token)
 
@@ -368,14 +369,14 @@ def with_extensions(
         extensions: dict[str, ExtensionProtocol[INSTANCE, SETTINGS]] | None,
         *,
         apply_extensions: bool = False,
-    ) -> Generator:
+    ) -> Generator[dict[str, ExtensionProtocol[INSTANCE, SETTINGS]] | None]:
         # why None, for temporary using the real extensions
         assert self._extensions_var is not None, "Monkay not enabled for extensions"
         token = self._extensions_var.set(extensions)
         try:
             if apply_extensions and self.instance is not None:
                 self.apply_extensions()
-            yield
+            yield extensions
         finally:
             self._extensions_var.reset(token)
 
@@ -555,12 +556,12 @@ def settings(self) -> None:
         self.__dict__.pop("_loaded_settings", None)
 
     @contextmanager
-    def with_settings(self, settings: SETTINGS | None) -> Generator:
+    def with_settings(self, settings: SETTINGS | None) -> Generator[SETTINGS | None]:
         assert self._settings_var is not None, "Monkay not enabled for settings"
         # why None, for temporary using the real settings
         token = self._settings_var.set(settings)
         try:
-            yield
+            yield settings
         finally:
             self._settings_var.reset(token)
 

tests/test_settings.py

@@ -39,8 +39,9 @@ def test_settings_overwrite():
     settings_path = mod.monkay._settings_definition
     assert isinstance(settings_path, str)
     new_settings = old_settings.model_copy(update={"preloadd": []})
-    with mod.monkay.with_settings(new_settings):
+    with mod.monkay.with_settings(new_settings) as yielded:
         assert mod.monkay.settings is new_settings
+        assert mod.monkay.settings is yielded
         assert mod.monkay.settings is not old_settings
         # overwriting settings doesn't affect temporary scope
         mod.monkay.settings = mod.monkay._settings_definition