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:
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:
# external_module/helper.py
def greet(name):
return f"Hello, {name}!"
From main.py, you can import helper.py like this:
# 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.
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.
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.pyfile.as_(str, optional): The name for the module insys.modules. If not provided, a name is generated from the file path.here(str, optional): The base directory to resolve relative paths. IfNone, it's determined from the caller's file (__file__) or the current working directory.cwd(bool): IfTrueandhereisNone, 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 inimport_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 tofrom module import *.
expose_members(module, members)
- Imports specified
membersfrom the givenmoduleinto the caller's global scope.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for magicalimport 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| magicalimport-0.9.2.tar.gz | 6.3 kB | Without provenance | Details for magicalimport-0.9.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| magicalimport-0.9.2-py3-none-any.whl | Python 3 | none | any | Details for magicalimport-0.9.2-py3-none-any.whl |
Total release size: 13.5 kB
Release files / magicalimport-0.9.2.tar.gz
| Download URL | magicalimport-0.9.2.tar.gz |
|---|---|
| Size | 6.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fcdc657196db955684d65e0a40b88c036f0bca4ee8a48100e4fe2ad78252db80
|
|
BLAKE2b-256 checksum How to use checksums |
b8108e4ff6e0829283de50458a3e4a137fe218777627077e641b32d2ba74f765
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.28.1
|
Release files / magicalimport-0.9.2-py3-none-any.whl
| Download URL | magicalimport-0.9.2-py3-none-any.whl |
|---|---|
| Size | 7.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
08a326ece05932caaf9be8eae865a42e85afda1c2642411063ab816a8872f0b2
|
|
BLAKE2b-256 checksum How to use checksums |
f805a2a8f0ae1cbcfe6cece7edcc2b48d9e14023c797ea4ae8581eae85d1540a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
python-httpx/0.28.1
|
Security for magicalimport 0.9.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.