Initial commit

Author: kuyugama

.github/workflows/release.yaml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv and setup the python version
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install the project
+        run: uv sync --all-groups
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

.gitignore

@@ -0,0 +1,3 @@
+test.py
+modules/
+__pycache__

README.md

@@ -0,0 +1,105 @@
+# _# module-inject_
+
+**module-inject** is a Python library designed to inject configuration values into modules *before they are imported*, enabling centralized and declarative control over runtime behavior across dynamic or plugin-based systems.
+
+This is particularly useful in applications where modules need to be configured externally, but standard import mechanisms do not allow mutation of module-level state prior to execution.
+
+## Features
+
+- Inject values into modules before import-time execution
+- Fine-grained control with per-module and per-package scopes
+- Lazy and dynamic module loading after configuration
+- Optional type enforcement and stack-based namespace lookup
+
+## Installation
+
+```bash
+pip install module-inject
+```
+
+## Usage
+
+Consider a plugin system where plugins are python modules under a `plugins/` directory need to be initialized with context-specific parameters.
+
+### Example
+
+#### `main.py`
+
+```python
+from pathlib import Path
+from module_inject import Module
+
+# Create a controller for the package
+package = Module.from_import_path("plugins")
+
+# Set a package-scoped variable
+package.set(role="slave")
+
+# Set a variable for the current script
+Module.from_path(Path(__file__)).set(role="master")
+
+# Iterate over all module files and inject values before importing
+for path in Path("plugins").glob("*.py"):
+    module = Module.from_path(path)
+    module.set(variable=f"value for {module.import_path}")
+    module.load().init()
+```
+
+#### `plugins/interesting_plugin.py`
+
+```python
+import module_inject as module
+
+def init():
+    role = module.get("role", str, package=True)
+    print(role)
+
+# Module-level config access
+print(module.get("variable"))
+print(module.get_namespace())
+```
+
+### Output
+
+```
+value for plugins.interesting_plugin
+{'variable': 'value for plugins.interesting_plugin'}
+slave
+```
+
+## API
+
+### `Module.from_import_path(path: str) -> Module`
+
+Creates a `Module` controller for the given import path (e.g., `"plugins.interesting_plugin"`). 
+
+### `Module.from_path(path: Path) -> Module`
+
+Creates a `Module` controller from a filesystem path to a `.py` file. 
+Searches for the file in `sys.path` under the hood to resolve import path.
+
+### `module.get(key: str, type_: type[T] = None, package: bool = False, recursive: bool = False) -> T`
+
+Retrieves the value associated with `key`.
+If `type_` is set - checks if the value in namespace is instance of the provided type.
+
+If `package=True`, it will attempt to retrieve the value from the package scope rather than the module-specific scope.
+
+If `recursive=True`, it will walk over the call stack to find the name.
+
+### `module.get_namespace() -> dict`
+
+Returns a dictionary of all key-value pairs injected into the current module.
+
+### `Module.set(**kwargs) -> None`
+
+Sets key-value pairs to be injected into the associated module upon import.
+
+### `Module.load() -> types.ModuleType`
+
+Loads (imports) the target module with the injected configuration. Must be called to finalize injection.
+
+## Design Philosophy
+
+This library provides a low-level interface to orchestrate dynamic configuration of Python modules, particularly in systems requiring deferred or context-aware initialization. Unlike environment variables or global config objects, this approach allows values to be injected into module namespace dictionaries before execution.
+

module_inject/__init__.py

@@ -0,0 +1,66 @@
+import typing
+import inspect
+import collections.abc
+from pathlib import Path
+from .module import Module
+
+__all__ = ["get", "Module"]
+
+T = typing.TypeVar("T")
+
+
+def get_namespace(
+    package: bool = False,
+    get_path: typing.Callable[[], Path] = lambda: Path(inspect.stack()[2].filename),
+) -> collections.abc.Mapping[str, typing.Any]:
+    """
+    Get namespace for passed module path.
+
+    if package is set to true - gets namespace from directory in which module is stored.
+    """
+    caller_file = get_path()
+    if package:
+        caller_file = caller_file.parent
+
+    return Module.from_path(caller_file).namespace.copy()
+
+
+@typing.overload
+def get(name: str, *, package: bool = False, recursive: bool = False) -> typing.Any: ...
+@typing.overload
+def get(
+    name: str, type_: type[T], *, package: bool = False, recursive: bool = False
+) -> T: ...
+def get(
+    name: str,
+    type_: typing.Any = None,
+    *,
+    package: bool = False,
+    recursive: bool = False,
+) -> typing.Any:
+    """
+    Get value from caller's module namespace.
+
+    if package is set to True - gets value from module's package namespace.
+
+    if recursive is set to True - walks for all callstack to find the value and returns first entry.
+    """
+    file_paths = iter(map(lambda x: Path(x.filename), inspect.stack()[1:]))
+
+    while True:
+        try:
+            namespace = get_namespace(package, lambda: next(file_paths))
+        except StopIteration as exc:
+            raise KeyError(name) from exc
+
+        if name not in namespace:
+            if not recursive:
+                raise KeyError(name)
+            continue
+
+        value = namespace[name]
+
+        if type_ is not None and not isinstance(value, type_):
+            raise TypeError(f'Expected {type_!r} for "{name}", but got {type(value)!r}')
+
+        return value

module_inject/module.py

@@ -0,0 +1,52 @@
+import sys
+import types
+import typing
+import importlib
+from pathlib import Path
+
+
+def get_import_path(filepath: Path) -> str:
+    """Find module's import path using sys.path"""
+    for library in map(lambda x: Path(x).absolute(), sys.path):
+        if filepath.is_relative_to(library):
+            path = filepath.relative_to(library)
+            break
+    else:
+        raise ValueError("Module import path not found")
+
+    return ".".join(path.parts[:-1] + (path.stem,))
+
+
+class Module:
+    instances: dict[str, "Module"] = {}
+
+    def __init__(self, importpath: str) -> None:
+        self.import_path: str = importpath
+        self.namespace: dict[str, typing.Any] = {}
+
+        Module.instances[importpath] = self
+
+    @classmethod
+    def from_path(cls, path: Path) -> "Module":
+        """Get or create instance using filesystem path"""
+        import_path = get_import_path(path.absolute())
+
+        return cls.from_import_path(import_path)
+
+    @classmethod
+    def from_import_path(cls, import_path: str) -> "Module":
+        """Get or create instance using import path"""
+        if import_path in cls.instances:
+            return cls.instances[import_path]
+
+        return cls(import_path)
+
+    def set(self, **kwargs: typing.Any) -> None:
+        """
+        Set values into module's namespace. Shortcut for Module.namespace.update()
+        """
+        self.namespace.update(kwargs)
+
+    def load(self) -> types.ModuleType:
+        """Import the module"""
+        return importlib.import_module(self.import_path)

pyproject.toml

@@ -0,0 +1,10 @@
+[project]
+name = "module-inject"
+version = "0.0.1"
+description = "Module value injection"
+readme="README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.pyright]
+reportAny = false