[](https://badge.fury.io/py/hooker)
# Arcane Hooker
I'm a hooker from Silvermoon City. Let me show you the Arcane way to Python
---
Hooker is a hooking library that tries to simplify event firing and catching.
It gives the ability to plugin creators to create plugins for many different
parts, without having to break the logic in separate destinations, if it's not
needed. The main features include:
- Event declaration with help message support
- `Waterfall` events that pass their output as arguments to next hook
- Simple CLI tool to view all defined events of a project and its help messages
- Functions decorators to hook on events
- Dependency requirement for hooks (`a` hook has to be run before `b`)
- `HOOKER_SCRIPTS` environmental variable allows to load additional scripts (aka plugins)
- Wildcard hooks that are fired on all events
- When a hook accepts the `__retvals__` argument, the returned values of the previous
hooks (and the whole hook functions) will be passed into it as an [OrderedDict](https://docs.python.org/3/library/collections.html#collections.OrderedDict)
- Python 2 compatibility - I'll try to keep that for as long as I can
Terminology:
- `Project`: A project that uses Hooker
- `Plugin`: A piece of code that adds functionality to a `Project` using `hooks`
- `Event`: A name for something that `Plugins` can hook on. It is called on specific times
(that the `Project` author has programmed) so that `Plugins` can add functionality
- `Hook`: A function that the `Plugin` creator wrote and is declared as hook using
the `@hooker.hook` decorator. Contains at least one `Event` name (or none if its a wildcard
hook) and optionally `Dependencies`
- `Dependency`: A `Hook` can declare to be called after a plugin has run. `Dependency` can
include the name(s) of the python module(s) (**NOT** the function name) that include hooks
that need to be run before the `Hook`
For documentation check the [wiki](https://satori-ng.github.io/hooker/)
## Installation
`pip install -U hooker`
## Usage
To find defined hooks in a project use `python -m hooker <python file/module directory>`
Example:
`$ py -m hooker example/crypter/crypter.py`
```
pre_open_in: Input file will open. Arguments: path<str>. Return: path<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:6
pre_open_out: Output file will open. Arguments: path<str>. Return: path<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:7
encrypt: Encrypt data. Arguments: data<bytearray>. Return: data<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:8
decrypt: Decrypt data. Arguments: data<bytearray>. Return: data<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:9
```
As a Project Author to use hooker you have to declare an event and then fire it
Example:
```python
# project.py
import hooker
hooker.EVENTS.append("test", "Fired after Hello World is printed")
print("Hello World")
hooker.EVENTS["test"]()
```
As a Plugin Creator to extend a project using hooker, you have to create a function
using the `@hooker.hook` decorator and define the event you want to hook on:
Example:
```python
# my_plugin.py
import hooker
@hooker.hook("test")
def hello():
print("Goodbye World")
```
Now to use the plugin, you either have to `import` it in the project, or execute the
project using the environment variable `HOOKER_SCRIPTS` as follows:
`$ HOOKER_SCRIPTS=my_plugin python project.py`
```
Hello World
Goodbye World
```
## Used in
- [Satori](https://github.com/satori-ng) - The reason this project exists
- [wormnest](https://github.com/operatorequals/wormnest) - A Web Server to hide stuff
---
While the code is not a mess, I'm using a fair bit of python magic.
The target is to provide the simplest and most convenient API for
both project and plugin authors.
If you have a better way to do something, at least open an issue to
discuss it, I'm very interested!
Happy Hacking! :)
Raw data
{
"_id": null,
"home_page": "https://github.com/satori-ng/hooker",
"name": "hooker",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "hook,event,plugin,extension,module",
"author": "Satori-NG org",
"author_email": "satori_ng@email.com",
"download_url": "https://files.pythonhosted.org/packages/88/08/4f230331da52f7c1c06778fadaa1be33ac224ef669163f77ff7700ba3377/hooker-1.0.2.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/hooker)\n\n\n\n# Arcane Hooker\n\nI'm a hooker from Silvermoon City. Let me show you the Arcane way to Python\n\n---\n\nHooker is a hooking library that tries to simplify event firing and catching.\nIt gives the ability to plugin creators to create plugins for many different\nparts, without having to break the logic in separate destinations, if it's not\nneeded. The main features include:\n\n- Event declaration with help message support\n- `Waterfall` events that pass their output as arguments to next hook\n- Simple CLI tool to view all defined events of a project and its help messages\n- Functions decorators to hook on events\n- Dependency requirement for hooks (`a` hook has to be run before `b`)\n- `HOOKER_SCRIPTS` environmental variable allows to load additional scripts (aka plugins)\n- Wildcard hooks that are fired on all events\n- When a hook accepts the `__retvals__` argument, the returned values of the previous\nhooks (and the whole hook functions) will be passed into it as an [OrderedDict](https://docs.python.org/3/library/collections.html#collections.OrderedDict)\n- Python 2 compatibility - I'll try to keep that for as long as I can\n\nTerminology:\n\n- `Project`: A project that uses Hooker\n- `Plugin`: A piece of code that adds functionality to a `Project` using `hooks`\n- `Event`: A name for something that `Plugins` can hook on. It is called on specific times\n(that the `Project` author has programmed) so that `Plugins` can add functionality\n- `Hook`: A function that the `Plugin` creator wrote and is declared as hook using\nthe `@hooker.hook` decorator. Contains at least one `Event` name (or none if its a wildcard\nhook) and optionally `Dependencies`\n- `Dependency`: A `Hook` can declare to be called after a plugin has run. `Dependency` can\ninclude the name(s) of the python module(s) (**NOT** the function name) that include hooks\nthat need to be run before the `Hook`\n\nFor documentation check the [wiki](https://satori-ng.github.io/hooker/)\n\n## Installation\n\n`pip install -U hooker`\n\n## Usage\n\nTo find defined hooks in a project use `python -m hooker <python file/module directory>`\n\nExample:\n\n`$ py -m hooker example/crypter/crypter.py`\n```\npre_open_in: Input file will open. Arguments: path<str>. Return: path<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:6\npre_open_out: Output file will open. Arguments: path<str>. Return: path<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:7\nencrypt: Encrypt data. Arguments: data<bytearray>. Return: data<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:8\ndecrypt: Decrypt data. Arguments: data<bytearray>. Return: data<str> - /home/dzervas/Lab/satori/hooker/example/crypter/crypter.py:9\n```\n\nAs a Project Author to use hooker you have to declare an event and then fire it\n\nExample:\n```python\n# project.py\nimport hooker\n\nhooker.EVENTS.append(\"test\", \"Fired after Hello World is printed\")\n\nprint(\"Hello World\")\nhooker.EVENTS[\"test\"]()\n```\n\nAs a Plugin Creator to extend a project using hooker, you have to create a function\nusing the `@hooker.hook` decorator and define the event you want to hook on:\n\nExample:\n```python\n# my_plugin.py\nimport hooker\n\n@hooker.hook(\"test\")\ndef hello():\n print(\"Goodbye World\")\n``` \n\nNow to use the plugin, you either have to `import` it in the project, or execute the\nproject using the environment variable `HOOKER_SCRIPTS` as follows:\n\n`$ HOOKER_SCRIPTS=my_plugin python project.py`\n```\nHello World\nGoodbye World\n```\n\n## Used in\n\n- [Satori](https://github.com/satori-ng) - The reason this project exists\n- [wormnest](https://github.com/operatorequals/wormnest) - A Web Server to hide stuff\n\n---\n\nWhile the code is not a mess, I'm using a fair bit of python magic.\nThe target is to provide the simplest and most convenient API for\nboth project and plugin authors.\n\nIf you have a better way to do something, at least open an issue to\ndiscuss it, I'm very interested!\n\nHappy Hacking! :)\n",
"bugtrack_url": null,
"license": "",
"summary": "An arcane-powered python hooking library for sane humans",
"version": "1.0.2",
"split_keywords": [
"hook",
"event",
"plugin",
"extension",
"module"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "151d12d351e52ac8b896338ca79d69153e38b90813faeadca37038b4a818af7f",
"md5": "48c58cd460587e07ff0edbca759d984e",
"sha256": "19f9ca06f2e1bddb6a0c475d6f4bd5f1f9d66eca68bf1c53a8cf0a3793c5521e"
},
"downloads": -1,
"filename": "hooker-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48c58cd460587e07ff0edbca759d984e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15828,
"upload_time": "2023-03-27T13:47:30",
"upload_time_iso_8601": "2023-03-27T13:47:30.363319Z",
"url": "https://files.pythonhosted.org/packages/15/1d/12d351e52ac8b896338ca79d69153e38b90813faeadca37038b4a818af7f/hooker-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "88084f230331da52f7c1c06778fadaa1be33ac224ef669163f77ff7700ba3377",
"md5": "5ee6abb5c7a3b84e76eff36df7fad200",
"sha256": "dcc72c8045ac3449e1661d70514219e96193182316d42cd9738118be3880010b"
},
"downloads": -1,
"filename": "hooker-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5ee6abb5c7a3b84e76eff36df7fad200",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27937,
"upload_time": "2023-03-27T13:47:32",
"upload_time_iso_8601": "2023-03-27T13:47:32.653099Z",
"url": "https://files.pythonhosted.org/packages/88/08/4f230331da52f7c1c06778fadaa1be33ac224ef669163f77ff7700ba3377/hooker-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-27 13:47:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "satori-ng",
"github_project": "hooker",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "hooker"
}
JSON
