# πͺ 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Deadpool2000/magicimporter",
"name": "magicimporter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "import lazy pip auto-install utility dev-tools",
"author": "Salil",
"author_email": "d2kyt@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/bf/13/76c76a0d4d5705044646226b7a88755fe0c679b6376fce606c7eabbfe385/magicimporter-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83e\ude84 magicimporter\r\n\r\n**Smart Python import wrapper** that makes your imports lazier, safer, and smarter.\r\n\r\n> Written by a developer who's tired of writing `try: import ... except: install ...` everywhere.\r\n\r\n---\r\n\r\n## \ud83d\ude80 What It Does\r\n\r\nmagicimporter is a tiny utility that helps you:\r\n\r\n\u2705 **Lazy-load modules** - defer importing until first access \r\n\u2705 **Auto-install missing packages** - no more `pip install` errors \r\n\u2705 **Avoid clutter** - wrap your imports cleanly and clearly \r\n\u2705 **Support optional dependencies** - without breaking your app\r\n\r\nPerfect for:\r\n- Notebooks and prototyping\r\n- Reducing startup time (e.g., in CLI tools)\r\n- Handling optional packages gracefully\r\n- Plug-and-play with any Python script\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From PyPI (soon):\r\n```bash\r\npip install magicimporter\r\n```\r\n\r\n### From source:\r\n```bash\r\ngit clone https://github.com/Deadpool2000/magicimporter\r\ncd magicimporter\r\npip install -e .\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udd27 How to Use\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom magicimporter import magic_import\r\n\r\njson = magic_import(\"json\") # Just works like import\r\nprint(json.dumps({\"hello\": \"world\"}))\r\n```\r\n\r\n---\r\n\r\n### Lazy Import (delay loading until accessed)\r\n\r\n```python\r\nnp = magic_import(\"numpy\", lazy=True)\r\n\r\n# numpy isn\u2019t imported until this line:\r\nprint(np.array([1, 2, 3]))\r\n```\r\n\r\n---\r\n\r\n### Auto-Install Missing Packages\r\n\r\n```python\r\nrequests = magic_import(\"requests\", auto_install=True)\r\n\r\nres = requests.get(\"https://httpbin.org/get\")\r\nprint(res.status_code)\r\n```\r\n\r\n---\r\n\r\n### Lazy + Auto-Install Together\r\n\r\n```python\r\npandas = magic_import(\"pandas\", lazy=True, auto_install=True)\r\n\r\n# Nothing is loaded yet...\r\nprint(\"About to create DataFrame\")\r\n\r\ndf = pandas.DataFrame({\"a\": [1, 2, 3]}) # Now pandas loads\r\nprint(df)\r\n```\r\n\r\n---\r\n\r\n### Import Submodules\r\n\r\n```python\r\nos_path = magic_import(\"os.path\", lazy=True)\r\nprint(os_path.basename(\"/foo/bar.txt\"))\r\n```\r\n\r\n---\r\n\r\n### Optional Dependencies Pattern\r\n\r\n```python\r\ntry:\r\n yaml = magic_import(\"pyyaml\", auto_install=False)\r\n config = yaml.safe_load(open(\"config.yaml\"))\r\nexcept ModuleNotFoundError:\r\n print(\"Skipping YAML config support: dependency missing\")\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udcc1 Directory Structure\r\n\r\n```txt\r\nmagicimporter/\r\n\u251c\u2500\u2500 magicimporter/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 core.py # main logic\r\n\u2502 \u251c\u2500\u2500 lazy.py # lazy loader\r\n\u2502 \u2514\u2500\u2500 installer.py # auto-installer\r\n\u251c\u2500\u2500 examples/\r\n\u2502 \u2514\u2500\u2500 demo.py\r\n\u251c\u2500\u2500 tests/\r\n\u2502 \u2514\u2500\u2500 test_magicimporter.py\r\n\u251c\u2500\u2500 setup.py\r\n\u251c\u2500\u2500 pyproject.toml\r\n\u2514\u2500\u2500 README.md\r\n```\r\n\r\n---\r\n\r\n## \ud83e\uddea Running Tests\r\n\r\n```bash\r\npytest tests/\r\n```\r\n\r\nYou can also test individual features manually from `examples/demo.py`.\r\n\r\n---\r\n\r\n## \ud83e\udde0 Why This Exists\r\n\r\nYou're writing a script or notebook and hit this:\r\n\r\n```python\r\nimport somepackage # ModuleNotFoundError\r\n```\r\n\r\nThen you type:\r\n\r\n```bash\r\npip install somepackage\r\n```\r\n\r\nAnd do it again. And again. \r\nWhat if your code just handled that? \r\nThat's what magicimporter does.\r\n\r\nIt\u2019s especially useful when:\r\n- Building CLI tools with optional features\r\n- Using heavy modules only in specific branches\r\n- Rapid prototyping in notebooks or scripts\r\n\r\n---\r\n\r\n## \ud83d\udccc Notes & Caveats\r\n\r\n- Auto-install uses `subprocess` to call pip - no fancy API yet.\r\n- Lazy import doesn't delay sub-imports inside a module (standard Python behavior).\r\n- Use responsibly in production: implicit installs may surprise your users.\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0f Roadmap Ideas\r\n\r\n- [ ] Async import support\r\n- [ ] Config file or env variable overrides\r\n- [ ] Warnings and logging customization\r\n- [ ] Module-level caching\r\n\r\n---\r\n\r\n## \ud83d\udc68\u200d\ud83d\udcbb Author\r\n\r\nMade with care by Deadpool2000 \u2013 feel free to fork, extend, or PR ideas.\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nMIT \u2013 use it, hack it, ship it.\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Smart Python import wrapper with lazy load and auto-install",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/Deadpool2000/magicimporter#readme",
"Homepage": "https://github.com/Deadpool2000/magicimporter",
"Issues": "https://github.com/Deadpool2000/magicimporter/issues",
"Source": "https://github.com/Deadpool2000/magicimporter"
},
"split_keywords": [
"import",
"lazy",
"pip",
"auto-install",
"utility",
"dev-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7eaa54e09a485886abc39ad968320cc985b1d50b0248b332a8f4a237228195c0",
"md5": "d29e2011f33e4f9113be567364c703b0",
"sha256": "189f7c0a49ad145c728d86c8a9d4f99eab81e6ed80e43971017a4982b310563f"
},
"downloads": -1,
"filename": "magicimporter-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d29e2011f33e4f9113be567364c703b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5409,
"upload_time": "2025-08-04T15:41:00",
"upload_time_iso_8601": "2025-08-04T15:41:00.783672Z",
"url": "https://files.pythonhosted.org/packages/7e/aa/54e09a485886abc39ad968320cc985b1d50b0248b332a8f4a237228195c0/magicimporter-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf1376c76a0d4d5705044646226b7a88755fe0c679b6376fce606c7eabbfe385",
"md5": "a435709a3291c9b89f198f5551564cb2",
"sha256": "cac9375a6a3f05bb25e02e518aabd69d1e67e28ca0c2ac85216c579501b720db"
},
"downloads": -1,
"filename": "magicimporter-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a435709a3291c9b89f198f5551564cb2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5031,
"upload_time": "2025-08-04T15:41:02",
"upload_time_iso_8601": "2025-08-04T15:41:02.329230Z",
"url": "https://files.pythonhosted.org/packages/bf/13/76c76a0d4d5705044646226b7a88755fe0c679b6376fce606c7eabbfe385/magicimporter-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 15:41:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Deadpool2000",
"github_project": "magicimporter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "magicimporter"
}