https://github.com/deadpool2000/magicimporter
Smart Python import wrapper that makes your imports lazier, safer, and smarter.
https://github.com/deadpool2000/magicimporter
Last synced: 5 months ago
JSON representation
Smart Python import wrapper that makes your imports lazier, safer, and smarter.
- Host: GitHub
- URL: https://github.com/deadpool2000/magicimporter
- Owner: Deadpool2000
- License: mit
- Created: 2025-08-04T15:48:57.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-08-04T15:51:33.000Z (5 months ago)
- Last Synced: 2025-08-04T18:12:11.417Z (5 months ago)
- Language: Python
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🪄 magicimporter
**Smart Python import wrapper** that makes your imports lazier, safer, and smarter.
> Written by a developer who's tired of writing `try: import ... except: install ...` everywhere.
---
## 🚀 What It Does
magicimporter is a tiny utility that helps you:
✅ **Lazy-load modules** - defer importing until first access
✅ **Auto-install missing packages** - no more `pip install` errors
✅ **Avoid clutter** - wrap your imports cleanly and clearly
✅ **Support optional dependencies** - without breaking your app
Perfect for:
- Notebooks and prototyping
- Reducing startup time (e.g., in CLI tools)
- Handling optional packages gracefully
- Plug-and-play with any Python script
---
## 📦 Installation
### From PyPI (soon):
```bash
pip install magicimporter
```
### From source:
```bash
git clone https://github.com/Deadpool2000/magicimporter
cd magicimporter
pip install -e .
```
---
## 🔧 How to Use
### Basic Usage
```python
from magicimporter import magic_import
json = magic_import("json") # Just works like import
print(json.dumps({"hello": "world"}))
```
---
### Lazy Import (delay loading until accessed)
```python
np = magic_import("numpy", lazy=True)
# numpy isn’t imported until this line:
print(np.array([1, 2, 3]))
```
---
### Auto-Install Missing Packages
```python
requests = magic_import("requests", auto_install=True)
res = requests.get("https://httpbin.org/get")
print(res.status_code)
```
---
### Lazy + Auto-Install Together
```python
pandas = magic_import("pandas", lazy=True, auto_install=True)
# Nothing is loaded yet...
print("About to create DataFrame")
df = pandas.DataFrame({"a": [1, 2, 3]}) # Now pandas loads
print(df)
```
---
### Import Submodules
```python
os_path = magic_import("os.path", lazy=True)
print(os_path.basename("/foo/bar.txt"))
```
---
### Optional Dependencies Pattern
```python
try:
yaml = magic_import("pyyaml", auto_install=False)
config = yaml.safe_load(open("config.yaml"))
except ModuleNotFoundError:
print("Skipping YAML config support: dependency missing")
```
---
## 📁 Directory Structure
```txt
magicimporter/
├── magicimporter/
│ ├── __init__.py
│ ├── core.py # main logic
│ ├── lazy.py # lazy loader
│ └── installer.py # auto-installer
├── examples/
│ └── demo.py
├── tests/
│ └── test_magicimporter.py
├── setup.py
├── pyproject.toml
└── README.md
```
---
## 🧪 Running Tests
```bash
pytest tests/
```
You can also test individual features manually from `examples/demo.py`.
---
## 🧠 Why This Exists
You're writing a script or notebook and hit this:
```python
import somepackage # ModuleNotFoundError
```
Then you type:
```bash
pip install somepackage
```
And do it again. And again.
What if your code just handled that?
That's what magicimporter does.
It’s especially useful when:
- Building CLI tools with optional features
- Using heavy modules only in specific branches
- Rapid prototyping in notebooks or scripts
---
## 📌 Notes & Caveats
- Auto-install uses `subprocess` to call pip - no fancy API yet.
- Lazy import doesn't delay sub-imports inside a module (standard Python behavior).
- Use responsibly in production: implicit installs may surprise your users.
---
## 🛠️ Roadmap Ideas
- [ ] Async import support
- [ ] Config file or env variable overrides
- [ ] Warnings and logging customization
- [ ] Module-level caching
---
## 👨💻 Author
Made with care by Deadpool2000 – feel free to fork, extend, or PR ideas!
---
## 📄 License
MIT – use it, hack it, ship it.