Metadata-Version: 2.1
Name: dyn-import-utils
Version: 0.3.2
Summary: A simple package for dynamic imports
Home-page: UNKNOWN
Author: Lior Zeltzer
Author-email: lior.etush.zeltzer@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# dyn_import_utils

`dyn_import_utils` is a Python utility for dynamically importing modules and packages from file paths. 
It simplifies importing code that resides outside the standard Python module search path.

---

## Features

- Dynamically import Python modules from arbitrary file paths.
- Load entire packages from directories containing `__init__.py`.
- Lightweight and easy to integrate into existing projects.
- The input path can be absolute or relative,
   in case of a relative path, the base path of the calling module is used
- Symbols can be injected from other modules or dictionaries
---

## Installation

Install `dyn_import_utils` via pip:

```bash
pip install dyn_import_utils
```

---

## Usage

### Lib import
```python
import dyn_import_utils
```

### Importing a Module
Use `import_module` to load a module dynamically from its file path:

```python
# Dynamically load a module
module = dyn_import_utils.import_module("path/to/module.py")

# Use the module
print(module.some_function())
```

### Importing a Package
Use `import_package` to load a package dynamically from its directory:

```python
# Dynamically load a package
package = dyn_import_utils.import_package("path/to/package")

# Use the package
print(package.some_function())
```

### Injecting Symbols
Both `import_module` and `import_package` support an optional `inject_symbols` parameter.
Symbols are injected **before** the module/package code is executed, so they are available
during the module's own initialization (e.g. at module top-level or in `__init__.py`).

#### Inject from a dictionary
Pass a `dict` mapping name strings to objects:

```python
injected_classes = {
    "InjectedClass1": InjectedClass1,
    "InjectedClass2": InjectedClass2,
}
module = dyn_import_utils.import_module("path/to/module.py", inject_symbols=injected_classes)
```

Inside `module.py`, `InjectedClass1` and `InjectedClass2` are available as globals:

```python
# module.py
obj = InjectedClass1()   # works — injected before execution
```

#### Inject from a module
Pass an existing module object — all its public attributes are injected:

```python
import my_helpers
module = dyn_import_utils.import_module("path/to/module.py", inject_symbols=my_helpers)
```

#### Inject from a list of dicts and/or modules
Pass a list combining any mix of dicts and modules:

```python
module = dyn_import_utils.import_module(
    "path/to/module.py",
    inject_symbols=[my_helpers, {"extra_value": 42}]
)
```

#### Using inject_symbols with import_package
`inject_symbols` works the same way for packages — symbols are injected into the package's
`__init__.py` namespace before it executes:

```python
package = dyn_import_utils.import_package(
    "path/to/package",
    inject_symbols={"injected_func": lambda x: x * 2}
)
```

> **Note:** `inject_symbols` only applies to the top-level module or `__init__.py`.
> Submodules within a package are not automatically injected.

---

### Adding a Directory to `sys.path`
Temporarily add a directory to the Python module search path:

```python
dyn_import_utils.add_sys_path("path/to/directory")
```

---

## Example

### Example Module: `hello.py`

```python
# hello.py
def greet():
    return "Hello, world!"
```

### Dynamically Loading the Module

```python
import dyn_import_utils

module = dyn_import_utils.import_module("hello.py")
print(module.greet())  # Output: Hello, world!
```

### Example with Symbol Injection

```python
# greeter.py  (to be dynamically imported)
message = injected_message   # 'injected_message' will be provided at import time

def greet():
    return message
```

```python
import dyn_import_utils

module = dyn_import_utils.import_module(
    "greeter.py",
    inject_symbols={"injected_message": "Hello from the host!"}
)
print(module.greet())  # Output: Hello from the host!
```

---

## License

`dyn_import_utils` is released under the MIT License. See the [LICENSE](LICENSE) file for more details.

---

## Links

- **PyPI**: [https://pypi.org/project/dyn_import_utils/](https://pypi.org/project/dyn_import_utils/)  



