<h1 align="center">ihook</h1>
<div align="center">
[](https://codecov.io/github/JezaChen/ihook)
</div>
`ihook` is a Python module that allows you to configure functions to call when importing modules.
It supports both case-sensitive and case-insensitive module names and can handle hooks for modules that are imported using methods of `importlib`.
## Features
- Hook for modules that are imported.
- Support for case-sensitive and case-insensitive module names.
- Chain multiple hooks for the same or different modules.
- Handle hooks for sub-packages and namespace packages.
## Installation
You can install `ihook` using `pip`:
```sh
pip install ihook
```
## Usage
### Registering Hooks
You can register hooks using the `@on_import` decorator or by calling the `on_import` function directly.
#### Using the Decorator
```python
import ihook
@ihook.on_import('math')
def on_math_import():
print('math module imported')
import math # This will trigger the hook and print 'math module imported'
```
#### Using the Function Directly
```python
import ihook
def on_socket_import():
print('socket module imported')
ihook.on_import('socket', on_socket_import)
import socket # This will trigger the hook and print 'socket module imported'
```
### Case-Insensitive Hooks
You can register hooks for module names in a case-insensitive manner by setting the `case_sensitive` parameter to `False`.
```python
import ihook
@ihook.on_import('SocKet', case_sensitive=False)
def on_socket_import():
print('socket module imported (case-insensitive)')
import socket # This will trigger the hook and print 'socket module imported (case-insensitive)'
```
### Hooks with Module Information
You can define hooks that take a `ModuleInfo` parameter, which provides more detailed information about the imported module.
You can handle direct access to the module object using the `module_object` attribute.
```python
import ihook
@ihook.on_import('socket')
def on_socket_import(module_info: ihook.ModuleInfo):
print(f'{module_info.module_name} module imported')
print(f'Module object: {module_info.module_object}')
import socket # This will trigger the hook and print module information
```
### Clearing Hooks
You can clear all registered hooks using the `clear_hooks` function.
```python
import ihook
ihook.clear_hooks() # This will clear all registered hooks
```
### Un-patching
If you want to disable the hooking mechanism, you can use `unpatch_meta_path` to restore the original import mechanism.
This function **does not remove the registered hooks but disables the hooking mechanism**.
```python
import ihook
ihook.unpatch_meta_path() # This will restore the original import mechanism
```
You can use `patch_meta_path` to re-enable the hooking mechanism. The registered hooks will still be available.
## Advanced Usage
### Handling Importlib
You can register hooks for modules that are imported or reloaded using `importlib`.
```python
import ihook
@ihook.on_import('hashlib')
def on_hashlib_import():
print('hashlib module imported')
import importlib
hashlib = importlib.import_module('hashlib') # This will trigger the hook and print 'hashlib module imported'
importlib.reload(hashlib) # This will trigger the hook again and print 'hashlib module imported'
```
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/JezaChen/ihook",
"name": "ihook",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "hook import importlib",
"author": "Jianzhang Chen",
"author_email": "jezachen@163.com",
"download_url": "https://files.pythonhosted.org/packages/35/f2/6c245ca6b1f17ff6766839911fb90fc29a1a489236e179144dd8470cd73a/ihook-0.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">ihook</h1>\n\n<div align=\"center\">\n\n[](https://codecov.io/github/JezaChen/ihook)\n\n\n\n</div>\n\n`ihook` is a Python module that allows you to configure functions to call when importing modules.\nIt supports both case-sensitive and case-insensitive module names and can handle hooks for modules that are imported using methods of `importlib`.\n\n## Features\n\n- Hook for modules that are imported.\n- Support for case-sensitive and case-insensitive module names.\n- Chain multiple hooks for the same or different modules.\n- Handle hooks for sub-packages and namespace packages.\n\n## Installation\n\nYou can install `ihook` using `pip`:\n\n```sh\npip install ihook\n```\n\n## Usage\n\n### Registering Hooks\n\nYou can register hooks using the `@on_import` decorator or by calling the `on_import` function directly.\n\n#### Using the Decorator\n\n```python\nimport ihook\n\n@ihook.on_import('math')\ndef on_math_import():\n print('math module imported')\n\nimport math # This will trigger the hook and print 'math module imported'\n```\n\n#### Using the Function Directly\n\n```python\nimport ihook\n\ndef on_socket_import():\n print('socket module imported')\n\nihook.on_import('socket', on_socket_import)\n\nimport socket # This will trigger the hook and print 'socket module imported'\n```\n\n### Case-Insensitive Hooks\n\nYou can register hooks for module names in a case-insensitive manner by setting the `case_sensitive` parameter to `False`.\n\n```python\nimport ihook\n\n@ihook.on_import('SocKet', case_sensitive=False)\ndef on_socket_import():\n print('socket module imported (case-insensitive)')\n\nimport socket # This will trigger the hook and print 'socket module imported (case-insensitive)'\n```\n\n### Hooks with Module Information\n\nYou can define hooks that take a `ModuleInfo` parameter, which provides more detailed information about the imported module.\nYou can handle direct access to the module object using the `module_object` attribute.\n\n```python\nimport ihook\n\n@ihook.on_import('socket')\ndef on_socket_import(module_info: ihook.ModuleInfo):\n print(f'{module_info.module_name} module imported')\n print(f'Module object: {module_info.module_object}')\n\nimport socket # This will trigger the hook and print module information\n```\n\n### Clearing Hooks\n\nYou can clear all registered hooks using the `clear_hooks` function.\n\n```python\nimport ihook\n\nihook.clear_hooks() # This will clear all registered hooks\n```\n\n### Un-patching\n\nIf you want to disable the hooking mechanism, you can use `unpatch_meta_path` to restore the original import mechanism.\nThis function **does not remove the registered hooks but disables the hooking mechanism**.\n\n```python\nimport ihook\n\nihook.unpatch_meta_path() # This will restore the original import mechanism\n```\n\nYou can use `patch_meta_path` to re-enable the hooking mechanism. The registered hooks will still be available.\n\n\n## Advanced Usage\n\n### Handling Importlib\n\nYou can register hooks for modules that are imported or reloaded using `importlib`.\n\n```python\nimport ihook\n\n@ihook.on_import('hashlib')\ndef on_hashlib_import():\n print('hashlib module imported')\n\nimport importlib\nhashlib = importlib.import_module('hashlib') # This will trigger the hook and print 'hashlib module imported'\nimportlib.reload(hashlib) # This will trigger the hook again and print 'hashlib module imported'\n```\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "`ihook` is a Python module that allows you to configure functions to call when importing modules.",
"version": "0.2",
"project_urls": {
"Homepage": "https://github.com/JezaChen/ihook"
},
"split_keywords": [
"hook",
"import",
"importlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd2274c60e68c359e2e4021ae3e07863048ed0206a67d468b54a31fc1b66cb63",
"md5": "635eb788ccfa24a7921a9c570e3514fc",
"sha256": "ff9c19ddb33040f9c69ce38476b0606cf87a680179f04376555d288ecd1ce1e8"
},
"downloads": -1,
"filename": "ihook-0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "635eb788ccfa24a7921a9c570e3514fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 7348,
"upload_time": "2024-12-29T08:10:01",
"upload_time_iso_8601": "2024-12-29T08:10:01.871718Z",
"url": "https://files.pythonhosted.org/packages/dd/22/74c60e68c359e2e4021ae3e07863048ed0206a67d468b54a31fc1b66cb63/ihook-0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "35f26c245ca6b1f17ff6766839911fb90fc29a1a489236e179144dd8470cd73a",
"md5": "876beffe27cabeaa1348fd5428d3c931",
"sha256": "33a6afd111a9fa2ab6fdf561590fe02e643aa9c12d4e5b5015c6493128e80392"
},
"downloads": -1,
"filename": "ihook-0.2.tar.gz",
"has_sig": false,
"md5_digest": "876beffe27cabeaa1348fd5428d3c931",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 11805,
"upload_time": "2024-12-29T08:10:04",
"upload_time_iso_8601": "2024-12-29T08:10:04.472122Z",
"url": "https://files.pythonhosted.org/packages/35/f2/6c245ca6b1f17ff6766839911fb90fc29a1a489236e179144dd8470cd73a/ihook-0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-29 08:10:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JezaChen",
"github_project": "ihook",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ihook"
}
JSON
