monkay 0.0.1__tar.gz

monkay-0.0.1/.github/workflows/docs_build.yml.

@@ -0,0 +1,56 @@
+name: Deploy Monkay site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [$default-branch]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      HUGO_VERSION: 0.128.0
+    steps:
+      - uses: "actions/checkout@v4"
+      - uses: "actions/setup-python@v5"
+      - name: "Install hatch"
+        run: "pip install hatch"
+      - name: Build Pages
+        run "hatch run docs:build"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

monkay-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Test Suite
+
+on:
+  push:
+    branches:
+      - "**"
+jobs:
+  tests:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: "ubuntu-latest"
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: "actions/checkout@v4"
+      - uses: "actions/setup-python@v5"
+        with:
+          python-version: "${{ matrix.python-version }}"
+          allow-prereleases: true
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-hatch
+      - name: "Install dependencies"
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: "pip install hatch"
+      - name: "Run linting"
+        run: "hatch fmt --check"
+      - name: "Run mypy"
+        run: "hatch run types:check"
+      - name: "Run tests"
+        run: "hatch test"

monkay-0.0.1/.gitignore

@@ -0,0 +1,29 @@
+# folders
+*.egg-info/
+.hypothesis/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.ruff
+.tox/
+.venv/
+venv/
+.vscode/
+__pycache__/
+virtualenv/
+build/
+dist/
+node_modules/
+results/
+
+# files
+**/*.so
+*.sqlite
+*.iml
+.DS_Store
+.coverage
+.coverage.*
+.python-version
+coverage.*
+docker-compose.override.yml
+compose.override.yml

monkay-0.0.1/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2024 <COPYRIGHT HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

monkay-0.0.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.3
+Name: monkay
+Version: 0.0.1
+Summary: The ultimate preload, settings, lazy import manager.
+Project-URL: Documentation, https://github.com/devkral/monkay#readme
+Project-URL: Issues, https://github.com/devkral/monkay/issues
+Project-URL: Source, https://github.com/devkral/monkay
+Author-email: alex <devkral@web.de>
+Keywords: lazy-imports,monkey-patching,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.9
+Provides-Extra: settings
+Requires-Dist: pydantic-settings; extra == 'settings'
+Description-Content-Type: text/markdown
+
+# monkay
+
+[![PyPI - Version](https://img.shields.io/pypi/v/monkay.svg)](https://pypi.org/project/monkay)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/monkay.svg)](https://pypi.org/project/monkay)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```shell
+pip install monkay
+```
+
+## License
+
+`monkay` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

monkay-0.0.1/README.md

@@ -0,0 +1,21 @@
+# monkay
+
+[![PyPI - Version](https://img.shields.io/pypi/v/monkay.svg)](https://pypi.org/project/monkay)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/monkay.svg)](https://pypi.org/project/monkay)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```shell
+pip install monkay
+```
+
+## License
+
+`monkay` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

monkay-0.0.1/docs/helpers.md

@@ -0,0 +1,9 @@
+# Helpers
+
+
+Monkay comes with two helpers
+
+- `load(path, allow_splits=":.")`: Load a path like Monkay. `allow_splits` allows to configure if attributes are seperated via . or :.
+  When both are specified, both split ways are possible (Default).
+- `load_any(module_path, potential_attrs, *, non_first_deprecated=False)`: Checks for a module if any attribute name matches. Return attribute value or raises ImportError when non matches.
+  When `non_first_deprecated` is `True`, a DeprecationMessage is issued for the non-first attribute which matches. This can be handy for deprecating module interfaces.

monkay-0.0.1/docs/index.md

@@ -0,0 +1,20 @@
+# Home
+
+## What is Monkay for?
+
+Imagine a large software project which evolves. Old names should be deprecated. Imports
+should be lazy so sideeffects are minimized.
+But on the other hand you have self-registering parts like extensions or like Django models.
+
+Multiple threads access application parts and tests with different settings are also a requirement
+now things get really complicated.
+
+This project solves the problems.
+Monkay is a monkey-patcher with async features, preload and extension support (and some more).
+Extension registrations can be reordered so there are also no dependency issues and extensions can build on each other.
+Tests are possible by an async friendly approach via context variables so every situation can be easily tested.
+
+For application frameworks Monkay provides settings which can also temporarily overwritten like in Django and
+optionally setting names for preloads and extensions.
+
+You may want to continue to the [Tutorial](tutorial.md)

monkay-0.0.1/docs/release-notes.md

@@ -0,0 +1,5 @@
+# Release notes
+
+## Version 0.0.1
+
+Initial release

monkay-0.0.1/docs/tutorial.md

@@ -0,0 +1,230 @@
+# Tutorial
+
+## How to use
+
+### Installation
+
+``` shell
+pip install monkay
+# or
+# pip install monkay[settings]
+```
+
+### Usage
+
+Probably in the main `__init__.py` you define something like this:
+
+``` python
+monkay = Monkay(
+    # required for autohooking
+    globals(),
+    with_extensions=True,
+    with_instance=True,
+    settings_path="settings_path:Settings",
+    preloads=["tests.targets.module_full_preloaded1:load"],
+    settings_preload_name="preloads",
+    settings_extensions_name="extensions",
+    lazy_imports={"bar": "tests.targets.fn_module:bar"},
+    deprecated_lazy_imports={
+        "deprecated": {
+            "path": "tests.targets.fn_module:deprecated",
+            "reason": "old",
+            "new_attribute": "super_new",
+        }
+    },
+)
+```
+
+
+When providing your own `__all__` variable **after** providing Monkay or you want more controll, you can provide
+
+`skip_all_update=True`
+
+and update the `__all__` value via `Monkay.update_all_var` if wanted.
+
+#### Using settings
+
+Settings can be an initialized pydantic settings variable or a class.
+When pointing to a class the class is automatically called without arguments.
+
+Let's do the configuration like Django via environment variable:
+
+``` python title="__init__.py"
+import os
+monkay = Monkay(
+    globals(),
+    with_extensions=True,
+    with_instance=True,
+    settings_path=os.environ.get("MONKAY_SETTINGS", "example.default.path.settings:Settings"),
+    settings_preload_name="preloads",
+    settings_extensions_name="extensions",
+)
+```
+
+``` python title="settings.py"
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    preloads: list[str] = []
+    extensions: list[Any] = []
+
+```
+
+And voila settings are now available from monkay.settings. This works only when all settings arguments are
+set via environment or defaults.
+
+When having explicit variables this is also possible:
+
+``` python title="explicit_settings.py"
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    preloads: list[str]
+    extensions: list[Any]
+
+settings = Settings(preloads=[], extensions=[])
+```
+Note here the lowercase settings
+
+``` python title="__init__.py"
+import os
+from monkay import Monkay
+monkay = Monkay(
+    globals(),
+    with_extensions=True,
+    with_instance=True,
+    settings_path=os.environ.get("MONKAY_SETTINGS", "example.default.path.settings:settings"),
+    settings_preload_name="preloads",
+    settings_extensions_name="extensions",
+)
+```
+
+#### Pathes
+
+Like shown in the examples pathes end with a `:` for an attribute. But sometimes a dot is nicer.
+This is why you can also use a dot in most cases. A notable exception are preloads where `:` are marking loading functions.
+
+#### Preloads
+
+Preloads are required in case some parts of the application are self-registering but no extensions.
+
+There are two kinds of preloads
+
+1. Module preloads. Simply a module is imported via `import_module`. Self-registrations are executed
+2. Functional preloads. With a `:`. The function name behind the `:` is executed and it is
+   expected that the function does the preloading. The module however is still preloaded.
+
+
+``` python title="preloader.py"
+from importlib import import_module
+
+def preloader():
+    for i in ["foo.bar", "foo.err"]:
+        import_module(i)
+
+```
+
+``` python title="settings.py"
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    preloads: list[str] = ["preloader:preloader"]
+```
+
+##### Lazy imports
+
+When using lazy imports the globals get an `__getattr__` injected. A potential old `__getattr__` is used as fallback when provided **before**
+initializing the Monkay instance:
+
+`module attr > monkay __getattr__ > former __getattr__ or Error`.
+
+
+Lazy imports of the `lazy_imports` parameter/attribute are defined in a dict with the key as the pseudo attribute and the value the forward.
+
+There are also `deprecated_lazy_imports` which have as value a dictionary with the key-values
+
+- `path`: Forward path.
+- `reason` (Optional): Deprecation reason.
+- `new_attribute` (Optional): Upgrade path.
+
+#### Using the instance feature
+
+The instance feature is activated by providing a boolean (or a string for an explicit name) to the `with_instance`
+parameter.
+
+For entrypoints you can set now the instance via `set_instance`. A good entrypoint is the init and using the settings:
+
+
+``` python title="__init__.py"
+import os
+from monkay import Monkay, load
+
+monkay = Monkay(
+    globals(),
+    with_extensions=True,
+    with_instance=True,
+    settings_path=os.environ.get("MONKAY_SETTINGS", "example.default.path.settings:settings"),
+    settings_preload_name="preloads",
+    settings_extensions_name="extensions",
+)
+
+monkay.set_instance(load(settings.APP_PATH))
+```
+
+#### Using the extensions feature
+
+Extensions work well together with the instances features.
+
+An extension is a class implementing the ExtensionProtocol:
+
+``` python title="Extension protocol"
+from typing import Protocol
+
+@runtime_checkable
+class ExtensionProtocol(Protocol[L]):
+    name: str
+
+    def apply(self, monkay_instance: Monkay[L]) -> None: ...
+
+```
+
+
+A name (can be dynamic) and the apply method are required. The instance itself is easily retrieved from
+the monkay instance.
+
+``` python title="settings.py"
+from dataclasses import dataclass
+import copy
+from pydantic_settings import BaseSettings
+
+class App:
+    extensions: list[Any]
+
+@dataclass
+class Extension:
+    name: str = "hello"
+
+    def apply(self, monkay_instance: Monkay) -> None:
+        monkay_instance.instance.extensions.append(copy.copy(self))
+
+class Settings(BaseSettings):
+    preloads: list[str] = ["preloader:preloader"]
+    extensions: list[Any] = [Extension]
+    APP_PATH: str = "settings.App"
+
+```
+
+##### Reordering extension order dynamically
+
+During apply it is possible to call `monkay.ensure_extension(name | Extension)`. When providing an extension
+it is automatically initialized though not added to extensions.
+Every name is called once and extensions in `monkay.extensions` have priority. They will applied instead when providing
+a same named extension via ensure_extension.
+
+##### Reordering extension order dynamically2
+
+There is a second more complicated way to reorder:
+
+via the parameter `extension_order_key_fn`. It takes a key function which is expected to return a lexicographic key capable for ordering.
+
+You can however intermix both.

monkay-0.0.1/mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: Monkay
+site_description: The ultimate preload, settings, lazy import manager..
+site_url: https://devkral.github.io/monkay
+
+nav:
+  - Home: index.md
+  - Tutorial: tutorial.md
+  - Helpers: helpers.md

monkay-0.0.1/monkay/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2024-present alex <devkral@web.de>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.1"

monkay-0.0.1/monkay/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2024-present alex <devkral@web.de>
+#
+# SPDX-License-Identifier: MIT
+
+from .base import DeprecatedImport, ExtensionProtocol, Monkay, load, load_any
+
+__all__ = [
+    "Monkay",
+    "DeprecatedImport",
+    "ExtensionProtocol",
+    "load",
+    "load_any",
+]

monkay-0.0.1/monkay/base.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable, Generator, Iterable, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import cached_property, partial
+from importlib import import_module
+from inspect import isclass
+from itertools import chain
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Protocol,
+    TypedDict,
+    TypeVar,
+    cast,
+    runtime_checkable,
+)
+
+if TYPE_CHECKING:
+    from pydantic_settings import BaseSettings
+
+L = TypeVar("L")
+
+
+class DeprecatedImport(TypedDict):
+    path: str
+    reason: str
+    new_attribute: str
+
+
+def load(path: str, allow_splits: str = ":.") -> Any:
+    splitted = path.rsplit(":", 1) if ":" in allow_splits else []
+    if len(splitted) < 2 and "." in allow_splits:
+        splitted = path.rsplit(".", 1)
+    if len(splitted) != 2:
+        raise ValueError(f"invalid path: {path}")
+    module = import_module(splitted[0])
+    return getattr(module, splitted[1])
+
+
+def load_any(
+    path: str, attrs: Sequence[str], *, non_first_deprecated: bool = False
+) -> Any | None:
+    module = import_module(path)
+    first_name: None | str = None
+
+    for attr in attrs:
+        if hasattr(module, attr):
+            if non_first_deprecated and first_name is not None:
+                warnings.warn(
+                    f'"{attr}" is deprecated, use "{first_name}" instead.',
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            return getattr(module, attr)
+        if first_name is None:
+            first_name = attr
+    raise ImportError(f"Could not import any of the attributes:.{', '.join(attrs)}")
+
+
+@runtime_checkable
+class ExtensionProtocol(Protocol[L]):
+    name: str
+
+    def apply(self, monkay_instance: Monkay[L]) -> None: ...
+
+
+def _stub_previous_getattr(name: str) -> Any:
+    raise AttributeError(f'Module has no attribute: "{name}" (Monkay).')
+
+
+class Monkay(Generic[L]):
+    _instance: None | L = None
+    _instance_var: ContextVar[L | None] | None = None
+    # extensions are pretended to always exist, we check the _extensions_var
+    _extensions: dict[str, ExtensionProtocol[L]]
+    _extensions_var: None | ContextVar[None | dict[str, ExtensionProtocol[L]]] = None
+    _extensions_applied: None | ContextVar[dict[str, ExtensionProtocol[L]] | None] = (
+        None
+    )
+    _settings_var: ContextVar[BaseSettings | None] | None = None
+
+    def __init__(
+        self,
+        global_dict: dict,
+        *,
+        with_instance: str | bool = False,
+        with_extensions: str | bool = False,
+        extension_order_key_fn: None | Callable[[ExtensionProtocol[L]], Any] = None,
+        settings_path: str = "",
+        preloads: Iterable[str] = (),
+        settings_preload_name: str = "",
+        settings_extensions_name: str = "",
+        lazy_imports: dict[str, str] | None = None,
+        deprecated_lazy_imports: dict[str, DeprecatedImport] | None = None,
+        settings_ctx_name: str = "monkay_settings_ctx",
+        extensions_applied_ctx_name: str = "monkay_extensions_applied_ctx",
+        skip_all_update: bool = False,
+    ) -> None:
+        if with_instance is True:
+            with_instance = "monkay_instance_ctx"
+        with_instance = with_instance
+        if with_extensions is True:
+            with_extensions = "monkay_extensions_ctx"
+        with_extensions = with_extensions
+
+        self._cache_imports: dict[str, Any] = {}
+        self.lazy_imports = lazy_imports or {}
+        self.deprecated_lazy_imports = deprecated_lazy_imports or {}
+        assert set(
+            self.lazy_imports
+        ).isdisjoint(
+            self.deprecated_lazy_imports
+        ), f"Lazy imports and lazy deprecated imports share: {', '.join(set(self.lazy_imports).intersection(self.deprecated_lazy_imports))}"
+        self.settings_path = settings_path
+        if self.settings_path:
+            self._settings_var = global_dict[settings_ctx_name] = ContextVar(
+                settings_ctx_name, default=None
+            )
+
+        self.settings_preload_name = settings_preload_name
+        self.settings_extensions_name = settings_extensions_name
+
+        self._handle_preloads(preloads)
+        if self.lazy_imports or self.deprecated_lazy_imports:
+            getter: Callable[..., Any] = self.module_getter
+            if "__getattr__" in global_dict:
+                getter = partial(getter, chained_getter=global_dict["__getattr__"])
+            global_dict["__getattr__"] = getter
+            if not skip_all_update:
+                all_var = global_dict.setdefault("__all__", [])
+                global_dict["__all__"] = self.update_all_var(all_var)
+        if with_instance:
+            self._instance_var = global_dict[with_instance] = ContextVar(
+                with_instance, default=None
+            )
+        if with_extensions:
+            self.extension_order_key_fn = extension_order_key_fn
+            self._extensions = {}
+            self._extensions_var = global_dict[with_extensions] = ContextVar(
+                with_extensions, default=None
+            )
+            self._extensions_applied_var = global_dict[extensions_applied_ctx_name] = (
+                ContextVar(extensions_applied_ctx_name, default=None)
+            )
+            self._handle_extensions()
+
+    @property
+    def instance(self) -> L | None:
+        assert self._instance_var is not None, "Monkay not enabled for instances"
+        instance: L | None = self._instance_var.get()
+        if instance is None:
+            instance = self._instance
+        return instance
+
+    def set_instance(
+        self,
+        instance: L,
+        apply_extensions: bool = True,
+        use_extension_overwrite: bool = True,
+    ) -> 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:
+            raise RuntimeError("Other apply process in the same context is active.")
+        self._instance = instance
+        if apply_extensions and self._extensions_var is not None:
+            self.apply_extensions(use_overwrite=use_extension_overwrite)
+
+    @contextmanager
+    def with_instance(
+        self,
+        instance: L | None,
+        apply_extensions: bool = False,
+        use_extension_overwrite: bool = True,
+    ) -> Generator:
+        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:
+            raise RuntimeError("Other apply process in the same context is active.")
+        token = self._instance_var.set(instance)
+        try:
+            if apply_extensions and self._extensions_var is not None:
+                self.apply_extensions(use_overwrite=use_extension_overwrite)
+            yield
+        finally:
+            self._instance_var.reset(token)
+
+    def apply_extensions(self, use_overwrite: bool = True) -> None:
+        assert self._extensions_var is not None, "Monkay not enabled for extensions"
+        extensions: dict[str, ExtensionProtocol[L]] | None = (
+            self._extensions_var.get() if use_overwrite else None
+        )
+        if extensions is None:
+            extensions = self._extensions
+        extensions_applied = self._extensions_applied_var.get()
+        if extensions_applied is not None:
+            raise RuntimeError("Other apply process in the same context is active.")
+        extensions_ordered: Iterable[tuple[str, ExtensionProtocol[L]]] = cast(
+            dict[str, ExtensionProtocol[L]], extensions
+        ).items()
+
+        if self.extension_order_key_fn is not None:
+            extensions_ordered = sorted(
+                extensions_ordered,
+                key=self.extension_order_key_fn,  # type:  ignore
+            )
+        extensions_applied = set()
+        token = self._extensions_applied_var.set(extensions_applied)
+        try:
+            for name, extension in extensions_ordered:
+                if name in extensions_applied:
+                    continue
+                extensions_applied.add(name)
+                extension.apply(self)
+        finally:
+            self._extensions_applied_var.reset(token)
+
+    def ensure_extension(self, name_or_extension: str | ExtensionProtocol[L]) -> None:
+        assert self._extensions_var is not None, "Monkay not enabled for extensions"
+        extensions: dict[str, ExtensionProtocol[L]] | None = self._extensions_var.get()
+        if extensions is None:
+            extensions = self._extensions
+        if isinstance(name_or_extension, str):
+            name = name_or_extension
+            extension = extensions.get(name)
+        elif not isclass(name_or_extension) and isinstance(
+            name_or_extension, ExtensionProtocol
+        ):
+            name = name_or_extension.name
+            extension = extensions.get(name, name_or_extension)
+        else:
+            raise RuntimeError(
+                'Provided extension "{name_or_extension}" does not implement the ExtensionProtocol'
+            )
+        if name in self._extensions_applied_var.get():
+            return
+
+        if extension is None:
+            raise RuntimeError(f'Extension: "{name}" does not exist.')
+        self._extensions_applied_var.get().add(name)
+        extension.apply(self)
+
+    def add_extension(
+        self,
+        extension: ExtensionProtocol[L]
+        | type[ExtensionProtocol[L]]
+        | Callable[[], ExtensionProtocol[L]],
+        use_overwrite: bool = True,
+    ) -> None:
+        assert self._extensions_var is not None, "Monkay not enabled for extensions"
+        extensions: dict[str, ExtensionProtocol[L]] | None = (
+            self._extensions_var.get() if use_overwrite else None
+        )
+        if extensions is None:
+            extensions = self._extensions
+        if callable(extension) or isclass(extension):
+            extension = extension()
+        if not isinstance(extension, ExtensionProtocol):
+            raise ValueError(f"Extension {extension} is not compatible")
+        extensions[extension.name] = extension
+
+    @contextmanager
+    def with_extensions(
+        self,
+        extensions: dict[str, ExtensionProtocol[L]] | None,
+        apply_extensions: bool = False,
+    ) -> Generator:
+        assert self._extensions_var is not None, "Monkay not enabled for extensions"
+        token = self._extensions_var.set(extensions)
+        try:
+            yield
+        finally:
+            self._extensions_var.reset(token)
+
+    def update_all_var(self, all_var: Sequence[str]) -> list[str]:
+        if not isinstance(all_var, list):
+            all_var = list(all_var)
+        all_var_set = set(all_var)
+        if self.lazy_imports or self.deprecated_lazy_imports:
+            for var in chain(
+                self.lazy_imports,
+                self.deprecated_lazy_imports,
+            ):
+                if var not in all_var_set:
+                    all_var.append(var)
+        return all_var
+
+    @cached_property
+    def _settings(self) -> BaseSettings:
+        settings: Any = load(self.settings_path)
+        if isclass(settings):
+            settings = settings()
+        return settings
+
+    @property
+    def settings(self) -> BaseSettings:
+        assert self._settings_var is not None, "Monkay not enabled for settings"
+        settings = self._settings_var.get()
+        if settings is None:
+            settings = self._settings
+        return settings
+
+    @contextmanager
+    def with_settings(self, settings: BaseSettings | None) -> Generator:
+        assert self._settings_var is not None, "Monkay not enabled for settings"
+        token = self._settings_var.set(settings)
+        try:
+            yield
+        finally:
+            self._settings_var.reset(token)
+
+    def module_getter(
+        self, key: str, *, chained_getter: Callable[[str], Any] = _stub_previous_getattr
+    ) -> Any:
+        lazy_import = self.lazy_imports.get(key)
+        if lazy_import is None:
+            deprecated = self.deprecated_lazy_imports.get(key)
+            if deprecated is not None:
+                lazy_import = deprecated["path"]
+                warn_strs = [f'Attribute: "{key}" is deprecated.']
+                if deprecated.get("reason"):
+                    warn_strs.append(f"Reason: {deprecated["reason"]}.")
+                if deprecated.get("new_attribute"):
+                    warn_strs.append(f'Use "{deprecated["new_attribute"]}" instead.')
+                warnings.warn("\n".join(warn_strs), DeprecationWarning, stacklevel=2)
+
+        if lazy_import is None:
+            return chained_getter(key)
+        if key not in self._cache_imports:
+            self._cache_imports[key] = load(lazy_import)
+        return self._cache_imports[key]
+
+    def _handle_preloads(self, preloads: Iterable[str]) -> None:
+        if self.settings_preload_name:
+            preloads = chain(
+                preloads, getattr(self.settings, self.settings_preload_name)
+            )
+        for preload in preloads:
+            splitted = preload.rsplit(":", 1)
+            try:
+                module = import_module(splitted[0])
+            except ImportError:
+                module = None
+            if module is not None and len(splitted) == 2:
+                getattr(module, splitted[1])()
+
+    def _handle_extensions(self) -> None:
+        if self.settings_extensions_name:
+            for extension in getattr(self.settings, self.settings_extensions_name):
+                self.add_extension(extension, use_overwrite=False)

monkay-0.0.1/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "monkay"
+dynamic = ["version"]
+description = 'The ultimate preload, settings, lazy import manager.'
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["monkey-patching", "settings", "lazy-imports"]
+authors = [
+  { name = "alex", email = "devkral@web.de" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = []
+
+[project.optional-dependencies]
+settings = [
+  "pydantic-settings"
+]
+
+[project.urls]
+Documentation = "https://github.com/devkral/monkay#readme"
+Issues = "https://github.com/devkral/monkay/issues"
+Source = "https://github.com/devkral/monkay"
+
+[tool.hatch.version]
+path = "monkay/__about__.py"
+
+[tool.hatch.envs.default]
+dependencies = [
+  "pydantic_settings"
+]
+
+[tool.hatch.envs.docs]
+dependencies = [
+  "mkdocs",
+]
+[tool.hatch.envs.docs.scripts]
+build = "mkdocs build"
+serve = "mkdocs serve --dev-addr localhost:8000"
+
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:monkay tests}"
+
+
+[tool.hatch.envs.hatch-test]
+extra-dependencies = [
+  "click",
+  "pydantic_settings"
+]
+
+
+[tool.coverage.run]
+source_pkgs = ["monkay", "tests"]
+branch = true
+parallel = true
+omit = [
+  "monkay/__about__.py",
+]
+
+[tool.coverage.paths]
+monkay = ["monkay", "*/monkay/monkay"]
+tests = ["tests", "*/monkay/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[ruff]
+line-length = 99
+fix = true
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "C", "B", "I", "UP", "SIM"]
+ignore = ["E501", "B008", "C901", "B026", "SIM115"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 99
+max-doc-length = 120
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+ignore_missing_imports = true
+check_untyped_defs = true
+ignore_errors = true

monkay-0.0.1/tests/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024-present alex <devkral@web.de>
+#
+# SPDX-License-Identifier: MIT

monkay-0.0.1/tests/targets/extension.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+
+from monkay import Monkay
+
+
+@dataclass
+class Extension:
+    name: str = "default"
+
+    def apply(self, app: Monkay) -> None:
+        assert isinstance(app, Monkay)
+        assert app.instance.is_fake_app
+        print(f"{self.name} called")
+
+
+@dataclass
+class BrokenExtension1:
+    name: str = "broken1"
+
+    def apply(self, app: Monkay) -> None:
+        app.ensure_extension("non-existent")
+
+
+@dataclass
+class BrokenExtension2:
+    name: str = "broken2"
+
+    def apply(self, app: Monkay) -> None:
+        # not allowed here
+        app.apply_extensions()
+
+
+@dataclass
+class NonExtension:
+    name: str

monkay-0.0.1/tests/targets/fn_module.py

@@ -0,0 +1,6 @@
+def bar():
+    return "bar"
+
+
+def deprecated():
+    return "deprecated"

monkay-0.0.1/tests/targets/module_full.py

@@ -0,0 +1,34 @@
+from monkay import Monkay
+
+extras = {"foo": lambda: "foo"}
+
+
+def __getattr__(name: str):
+    try:
+        return extras[name]
+    except KeyError as exc:
+        raise AttributeError from exc
+
+
+class FakeApp:
+    is_fake_app: bool = True
+    pass
+
+
+monkay = Monkay(
+    globals(),
+    with_extensions=True,
+    with_instance=True,
+    settings_path="tests.targets.settings:Settings",
+    preloads=["tests.targets.module_full_preloaded1:load"],
+    settings_preload_name="preloads",
+    settings_extensions_name="extensions",
+    lazy_imports={"bar": "tests.targets.fn_module:bar"},
+    deprecated_lazy_imports={
+        "deprecated": {
+            "path": "tests.targets.fn_module:deprecated",
+            "reason": "old",
+            "new_attribute": "super_new",
+        }
+    },
+)

monkay-0.0.1/tests/targets/module_full_preloaded1.py

@@ -0,0 +1,2 @@
+def load():
+    from . import module_full_preloaded1_fn  # noqa

monkay-0.0.1/tests/targets/settings.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+from monkay import load
+
+
+class SettingsExtension:
+    name: str = "settings_extension2"
+
+    def apply(self, app: Any) -> None:
+        print(f"{self.name} called")
+
+
+class Settings(BaseSettings):
+    preloads: list[str] = ["tests.targets.module_preloaded1"]
+    extensions: list[Any] = [
+        lambda: load("tests.targets.extension:Extension")(name="settings_extension1"),
+        SettingsExtension,
+    ]

monkay-0.0.1/tests/test_basic.py

@@ -0,0 +1,152 @@
+import contextlib
+import sys
+from io import StringIO
+
+import pytest
+
+from monkay import Monkay, load, load_any
+
+
+@pytest.fixture(autouse=True, scope="function")
+def cleanup():
+    for name in [
+        "module_full_preloaded1_fn",
+        "module_full_preloaded1",
+        "module_preloaded1",
+        "module_full",
+        "fn_module",
+    ]:
+        sys.modules.pop(f"tests.targets.{name}", None)
+    yield
+
+
+def test_preloaded():
+    assert "tests.targets.module_full" not in sys.modules
+    import tests.targets.module_full as mod
+
+    assert "tests.targets.fn_module" not in sys.modules
+
+    assert "tests.targets.module_full" in sys.modules
+    assert "tests.targets.module_full_preloaded1" in sys.modules
+    assert "tests.targets.module_full_preloaded1_fn" in sys.modules
+    assert "tests.targets.module_preloaded1" in sys.modules
+    assert "tests.targets.extension" in sys.modules
+
+    with contextlib.redirect_stdout(StringIO()):
+        mod.bar  # noqa
+
+    assert "tests.targets.fn_module" in sys.modules
+
+
+def test_attrs():
+    import tests.targets.module_full as mod
+
+    assert isinstance(mod.monkay, Monkay)
+
+    assert mod.foo() == "foo"
+    assert mod.bar() == "bar"
+    with pytest.warns(DeprecationWarning) as record:
+        assert mod.deprecated() == "deprecated"
+    assert (
+        record[0].message.args[0]
+        == 'Attribute: "deprecated" is deprecated.\nReason: old.\nUse "super_new" instead.'
+    )
+
+
+def test_load_any():
+    assert load_any("tests.targets.fn_module", ["not_existing", "bar"]) is not None
+    with pytest.warns(DeprecationWarning) as records:
+        assert (
+            load_any(
+                "tests.targets.fn_module",
+                ["not_existing", "bar"],
+                non_first_deprecated=True,
+            )
+            is not None
+        )
+    assert (
+        load_any(
+            "tests.targets.fn_module",
+            ["bar", "not_existing"],
+            non_first_deprecated=True,
+        )
+        is not None
+    )
+    assert str(records[0].message) == '"bar" is deprecated, use "not_existing" instead.'
+    with pytest.raises(ImportError):
+        assert load_any("tests.targets.fn_module", ["not-existing"]) is None
+    with pytest.raises(ImportError):
+        assert load_any("tests.targets.fn_module", []) is None
+    with pytest.raises(ImportError):
+        load_any("tests.targets.not_existing", ["bar"])
+
+
+def test_extensions(capsys):
+    import tests.targets.module_full as mod
+    from tests.targets.extension import NonExtension
+
+    captured = capsys.readouterr()
+    assert captured.out == captured.err == ""
+
+    app = mod.FakeApp()
+    mod.monkay.set_instance(app)
+    captured_out = capsys.readouterr().out
+    assert captured_out == "settings_extension1 called\nsettings_extension2 called\n"
+    with pytest.raises(ValueError):
+        mod.monkay.add_extension(NonExtension(name="foo"))  # type: ignore
+    assert capsys.readouterr().out == ""
+
+    # order
+
+    class ExtensionA:
+        name: str = "A"
+
+        def apply(self, monkay: Monkay) -> None:
+            monkay.ensure_extension("B")
+            with pytest.raises(RuntimeError):
+                monkay.ensure_extension("D")
+            print("A")
+
+    class ExtensionB:
+        name: str = "B"
+
+        def apply(self, monkay: Monkay) -> None:
+            monkay.ensure_extension("A")
+            monkay.ensure_extension(ExtensionC())
+            print("B")
+
+    class ExtensionC:
+        name: str = "C"
+
+        def apply(self, monkay: Monkay) -> None:
+            monkay.ensure_extension(ExtensionA())
+            print("C")
+
+    with mod.monkay.with_extensions({"B": ExtensionB(), "A": ExtensionA()}):
+        mod.monkay.apply_extensions()
+
+    assert capsys.readouterr().out == "A\nC\nB\n"
+    with mod.monkay.with_extensions(
+        {
+            "C": ExtensionC(),
+            "B": ExtensionB(),
+        }
+    ):
+        mod.monkay.apply_extensions()
+
+    assert capsys.readouterr().out == "B\nA\nC\n"
+
+
+def test_app(capsys):
+    import tests.targets.module_full as mod
+
+    app = mod.FakeApp()
+    mod.monkay.set_instance(app)
+    assert mod.monkay.instance is app
+    captured_out = capsys.readouterr().out
+    assert captured_out == "settings_extension1 called\nsettings_extension2 called\n"
+    app2 = mod.FakeApp()
+    with mod.monkay.with_instance(app2):
+        assert mod.monkay.instance is app2
+        assert capsys.readouterr().out == ""
+    assert capsys.readouterr().out == ""