# magicalimport
[](https://badge.fury.io/py/magicalimport)
[](https://travis-ci.org/podhmo/magicalimport)
`magicalimport` is a Python library that provides a flexible way to import modules and symbols directly from their physical file paths.
## Motivation
In some cases, you might want to import a Python module that is not part of a standard package or is not located in Python's `sys.path`. For example:
* Loading a plugin from a user-specified path.
* Using a Python script as a configuration file.
* Dynamically loading modules in a script or a tool.
Standard import mechanisms can be cumbersome in these scenarios. `magicalimport` simplifies this by allowing you to import modules directly using their file paths.
A key feature of this library is its special handling of `.py` files. The `import_module` function can distinguish between a regular module path (like `my_package.my_module`) and a direct file path (like `./path/to/my_module.py`), providing a unified interface for both.
## Installation
You can install `magicalimport` using pip:
```bash
pip install magicalimport
```
## Basic Usage
Let's say you have the following directory structure:
```
.
├── my_app
│ └── main.py
└── external_module
└── helper.py
```
And `helper.py` contains:
```python
# external_module/helper.py
def greet(name):
return f"Hello, {name}!"
```
From `main.py`, you can import `helper.py` like this:
```python
# my_app/main.py
import os
from magicalimport import import_from_physical_path
# Assuming the script is run from the project root
helper_path = os.path.abspath("../external_module/helper.py")
helper = import_from_physical_path(helper_path)
print(helper.greet("world"))
# => Hello, world!
```
## Special Handling of .py Files
The `import_module` function is a convenient wrapper that combines Python's standard `importlib.import_module` with `import_from_physical_path`. It automatically detects whether the provided path is a file path ending in `.py` or a regular module path.
```python
from magicalimport import import_module
# Imports a regular module
http_client = import_module("http.client")
print(http_client.HTTPConnection)
# Imports a .py file directly
helper = import_module("./external_module/helper.py")
print(helper.greet("again"))
```
This allows you to use the same function for both types of imports, simplifying your code.
## Importing Symbols
You can also import a specific symbol (a class, function, or variable) from a module using `import_symbol`. The symbol is specified using a string in the format `path/to/module.py:symbol_name`.
```python
from magicalimport import import_symbol
# Import the 'greet' function directly
greet_func = import_symbol("./external_module/helper.py:greet")
print(greet_func("from symbol"))
# => Hello, from symbol!
# You can also import from standard libraries
HTTPConnection = import_symbol("http.client:HTTPConnection")
print(HTTPConnection)
```
## API Reference
### `import_from_physical_path(path, as_=None, here=None, cwd=True)`
* `path` (str): The relative or absolute path to the `.py` file.
* `as_` (str, optional): The name for the module in `sys.modules`. If not provided, a name is generated from the file path.
* `here` (str, optional): The base directory to resolve relative paths. If `None`, it's determined from the caller's file (`__file__`) or the current working directory.
* `cwd` (bool): If `True` and `here` is `None`, the current working directory is used as the base.
### `import_module(module_path, here=None, cwd=True)`
* `module_path` (str): A module path (e.g., `my_package.my_module`) or a file path (e.g., `./my_module.py`).
* `here`, `cwd`: Same as in `import_from_physical_path`.
### `import_symbol(sym, here=None, sep=":")`
* `sym` (str): The string representing the symbol to import, in the format `<module_path>:<symbol_name>`.
* `here`: Same as above.
* `sep` (str): The separator between the module path and the symbol name.
### `expose_all_members(module)`
* Imports all members (that don't start with `_`) from the given module into the caller's global scope, similar to `from module import *`.
### `expose_members(module, members)`
* Imports specified `members` from the given `module` into the caller's global scope.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "magicalimport",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "file path, import, physical address",
"author": null,
"author_email": "podhmo <ababjam61+github@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b8/10/8e4ff6e0829283de50458a3e4a137fe218777627077e641b32d2ba74f765/magicalimport-0.9.2.tar.gz",
"platform": null,
"description": "# magicalimport\n\n[](https://badge.fury.io/py/magicalimport)\n[](https://travis-ci.org/podhmo/magicalimport)\n\n`magicalimport` is a Python library that provides a flexible way to import modules and symbols directly from their physical file paths.\n\n## Motivation\n\nIn some cases, you might want to import a Python module that is not part of a standard package or is not located in Python's `sys.path`. For example:\n\n* Loading a plugin from a user-specified path.\n* Using a Python script as a configuration file.\n* Dynamically loading modules in a script or a tool.\n\nStandard import mechanisms can be cumbersome in these scenarios. `magicalimport` simplifies this by allowing you to import modules directly using their file paths.\n\nA key feature of this library is its special handling of `.py` files. The `import_module` function can distinguish between a regular module path (like `my_package.my_module`) and a direct file path (like `./path/to/my_module.py`), providing a unified interface for both.\n\n## Installation\n\nYou can install `magicalimport` using pip:\n\n```bash\npip install magicalimport\n```\n\n## Basic Usage\n\nLet's say you have the following directory structure:\n\n```\n.\n\u251c\u2500\u2500 my_app\n\u2502 \u2514\u2500\u2500 main.py\n\u2514\u2500\u2500 external_module\n \u2514\u2500\u2500 helper.py\n```\n\nAnd `helper.py` contains:\n\n```python\n# external_module/helper.py\ndef greet(name):\n return f\"Hello, {name}!\"\n```\n\nFrom `main.py`, you can import `helper.py` like this:\n\n```python\n# my_app/main.py\nimport os\nfrom magicalimport import import_from_physical_path\n\n# Assuming the script is run from the project root\nhelper_path = os.path.abspath(\"../external_module/helper.py\")\nhelper = import_from_physical_path(helper_path)\n\nprint(helper.greet(\"world\"))\n# => Hello, world!\n```\n\n## Special Handling of .py Files\n\nThe `import_module` function is a convenient wrapper that combines Python's standard `importlib.import_module` with `import_from_physical_path`. It automatically detects whether the provided path is a file path ending in `.py` or a regular module path.\n\n```python\nfrom magicalimport import import_module\n\n# Imports a regular module\nhttp_client = import_module(\"http.client\")\nprint(http_client.HTTPConnection)\n\n# Imports a .py file directly\nhelper = import_module(\"./external_module/helper.py\")\nprint(helper.greet(\"again\"))\n```\n\nThis allows you to use the same function for both types of imports, simplifying your code.\n\n## Importing Symbols\n\nYou can also import a specific symbol (a class, function, or variable) from a module using `import_symbol`. The symbol is specified using a string in the format `path/to/module.py:symbol_name`.\n\n```python\nfrom magicalimport import import_symbol\n\n# Import the 'greet' function directly\ngreet_func = import_symbol(\"./external_module/helper.py:greet\")\n\nprint(greet_func(\"from symbol\"))\n# => Hello, from symbol!\n\n# You can also import from standard libraries\nHTTPConnection = import_symbol(\"http.client:HTTPConnection\")\nprint(HTTPConnection)\n```\n\n## API Reference\n\n### `import_from_physical_path(path, as_=None, here=None, cwd=True)`\n\n* `path` (str): The relative or absolute path to the `.py` file.\n* `as_` (str, optional): The name for the module in `sys.modules`. If not provided, a name is generated from the file path.\n* `here` (str, optional): The base directory to resolve relative paths. If `None`, it's determined from the caller's file (`__file__`) or the current working directory.\n* `cwd` (bool): If `True` and `here` is `None`, the current working directory is used as the base.\n\n### `import_module(module_path, here=None, cwd=True)`\n\n* `module_path` (str): A module path (e.g., `my_package.my_module`) or a file path (e.g., `./my_module.py`).\n* `here`, `cwd`: Same as in `import_from_physical_path`.\n\n### `import_symbol(sym, here=None, sep=\":\")`\n\n* `sym` (str): The string representing the symbol to import, in the format `<module_path>:<symbol_name>`.\n* `here`: Same as above.\n* `sep` (str): The separator between the module path and the symbol name.\n\n### `expose_all_members(module)`\n\n* Imports all members (that don't start with `_`) from the given module into the caller's global scope, similar to `from module import *`.\n\n### `expose_members(module, members)`\n\n* Imports specified `members` from the given `module` into the caller's global scope.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "importing a module by physical file path",
"version": "0.9.2",
"project_urls": {
"Homepage": "https://github.com/podhmo/magicalimport"
},
"split_keywords": [
"file path",
" import",
" physical address"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f805a2a8f0ae1cbcfe6cece7edcc2b48d9e14023c797ea4ae8581eae85d1540a",
"md5": "db8278a9d0cd1e2c8ac4ce4129264570",
"sha256": "08a326ece05932caaf9be8eae865a42e85afda1c2642411063ab816a8872f0b2"
},
"downloads": -1,
"filename": "magicalimport-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db8278a9d0cd1e2c8ac4ce4129264570",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7159,
"upload_time": "2025-07-21T13:25:14",
"upload_time_iso_8601": "2025-07-21T13:25:14.954873Z",
"url": "https://files.pythonhosted.org/packages/f8/05/a2a8f0ae1cbcfe6cece7edcc2b48d9e14023c797ea4ae8581eae85d1540a/magicalimport-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b8108e4ff6e0829283de50458a3e4a137fe218777627077e641b32d2ba74f765",
"md5": "9fbc7b7c798d140c4d5d34c9ad1f820f",
"sha256": "fcdc657196db955684d65e0a40b88c036f0bca4ee8a48100e4fe2ad78252db80"
},
"downloads": -1,
"filename": "magicalimport-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "9fbc7b7c798d140c4d5d34c9ad1f820f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6306,
"upload_time": "2025-07-21T13:25:16",
"upload_time_iso_8601": "2025-07-21T13:25:16.392628Z",
"url": "https://files.pythonhosted.org/packages/b8/10/8e4ff6e0829283de50458a3e4a137fe218777627077e641b32d2ba74f765/magicalimport-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 13:25:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "podhmo",
"github_project": "magicalimport",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "magicalimport"
}
JSON
