| Name | simplug JSON |
| Version |
0.4.3
JSON |
| download |
| home_page | https://github.com/pwwang/simplug |
| Summary | A simple plugin system for python with async hooks supported |
| upload_time | 2024-07-21 06:36:07 |
| maintainer | None |
| docs_url | None |
| author | pwwang |
| requires_python | <4.0,>=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# simplug
A simple plugin system for python with async hooks supported
## Installation
```shell
pip install -U simplug
```
## Examples
### A toy example
```python
from simplug import Simplug
simplug = Simplug('project')
class MySpec:
"""A hook specification namespace."""
@simplug.spec
def myhook(self, arg1, arg2):
"""My special little hook that you can customize."""
class Plugin_1:
"""A hook implementation namespace."""
@simplug.impl
def myhook(self, arg1, arg2):
print("inside Plugin_1.myhook()")
return arg1 + arg2
class Plugin_2:
"""A 2nd hook implementation namespace."""
@simplug.impl
def myhook(self, arg1, arg2):
print("inside Plugin_2.myhook()")
return arg1 - arg2
simplug.register(Plugin_1, Plugin_2)
results = simplug.hooks.myhook(arg1=1, arg2=2)
print(results)
```
```shell
inside Plugin_1.myhook()
inside Plugin_2.myhook()
[3, -1]
```
Note that the hooks are executed in the order the plugins are registered. This is different from `pluggy`.
### A complete example
See `examples/complete/`.
Running `python -m examples.complete` gets us:
```shell
Your food. Enjoy some egg, egg, egg, salt, pepper, egg, egg
Some condiments? We have pickled walnuts, steak sauce, mushy peas, mint sauce
```
After install the plugin:
```shell
> pip install --editable examples.complete.plugin
> python -m examples.complete # run again
```
```shell
Your food. Enjoy some egg, egg, egg, salt, pepper, egg, egg, lovely spam, wonderous spam
Some condiments? We have pickled walnuts, mushy peas, mint sauce, spam sauce
Now this is what I call a condiments tray!
```
## Usage
### Definition of hooks
Hooks are specified and implemented by decorating the functions with `simplug.spec` and `simplug.impl` respectively.
`simplug` is initialized by:
```python
simplug = Simplug('project')
```
The `'project'` is a unique name to mark the project, which makes sure `Simplug('project')` get the same instance each time.
Note that if `simplug` is initialized without `project`, then a name is generated automatically as such `project-0`, `project-1`, etc.
Hook specification is marked by `simplug.spec`:
```python
simplug = Simplug('project')
@simplug.spec
def setup(args):
...
```
`simplug.spec` can take some arguments:
- `required`: Whether this hook is required to be implemented in plugins
- `result`: An enumerator to specify the way to collec the results.
- `SimplugResult.ALL`: Collect all results from all plugins
- `SimplugResult.ALL_AVAILS`: Get all the results from the hook, as a list, not including `None`s
- `SimplugResult.ALL_FIRST`: Executing all implementations and get the first result
- `SimplugResult.ALL_LAST`: Executing all implementations and get the last result
- `SimplugResult.TRY_ALL_FIRST`: Executing all implementations and get the first result, if no result is returned, return `None`
- `SimplugResult.TRY_ALL_LAST`: Executing all implementations and get the last result, if no result is returned, return `None`
- `SimplugResult.ALL_FIRST_AVAIL`: Executing all implementations and get the first non-`None` result
- `SimplugResult.ALL_LAST_AVAIL`: Executing all implementations and get the last non-`None` result
- `SimplugResult.TRY_ALL_FIRST_AVAIL`: Executing all implementations and get the first non-`None` result, if no result is returned, return `None`
- `SimplugResult.TRY_ALL_LAST_AVAIL`: Executing all implementations and get the last non-`None` result, if no result is returned, return `None`
- `SimplugResult.FIRST`: Get the first result, don't execute other implementations
- `SimplugResult.LAST`: Get the last result, don't execute other implementations
- `SimplugResult.TRY_FIRST`: Get the first result, don't execute other implementations, if no result is returned, return `None`
- `SimplugResult.TRY_LAST`: Get the last result, don't execute other implementations, if no result is returned, return `None`
- `SimplugResult.FIRST_AVAIL`: Get the first non-`None` result, don't execute other implementations
- `SimplugResult.LAST_AVAIL`: Get the last non-`None` result, don't execute other implementations
- `SimplugResult.TRY_FIRST_AVAIL`: Get the first non-`None` result, don't execute other implementations, if no result is returned, return `None`
- `SimplugResult.TRY_LAST_AVAIL`: Get the last non-`None` result, don't execute other implementations, if no result is returned, return `None`
- `SimplugResult.SINGLE`: Get the result from a single implementation
- `SimplugResult.TRY_SINGLE`: Get the result from a single implementation, if no result is returned, return `None`
- A callable to collect the result, take `calls` as the argument, a 3-element tuple with first element as the implementation, second element as the positional arguments, and third element as the keyword arguments.
Hook implementation is marked by `simplug.impl`, which takes no additional arguments.
The name of the function has to match the name of the function by `simplug.spec`. And the signatures of the specification function and the implementation function have to be the same in terms of names. This means you can specify default values in the specification function, but you don't have to write the default values in the implementation function.
Note that default values in implementation functions will be ignored.
Also note if a hook specification is under a namespace, it can take `self` as argument. However, this argument will be ignored while the hook is being called (`self` will be `None`, and you still have to specify it in the function definition).
### Loading plugins from setuptools entrypoint
You have to call `simplug.load_entrypoints(group)` after the hook specifications are defined to load the plugins registered by setuptools entrypoint. If `group` is not given, the project name will be used.
### The plugin registry
The plugins are registered by `simplug.register(*plugins)`. Each plugin of `plugins` can be either a python object or a str denoting a module that can be imported by `importlib.import_module`.
The python object must have an attribute `name`, `__name__` or `__class.__name__` for `simplug` to determine the name of the plugin. If the plugin name is determined from `__name__` or `__class__.__name__`, it will be lowercased.
If a plugin is loaded from setuptools entrypoint, then the entrypoint name will be used (no matter what name is defined inside the plugin)
You can enable or disable a plugin temporarily after registration by:
```python
simplug.disable('plugin_name')
simplug.enable('plugin_name')
```
You can use following methods to inspect the plugin registry:
- `simplug.get_plugin`: Get the plugin by name
- `simplug.get_all_plugins`: Get a dictionary of name-plugin mappings of all plugins
- `simplug.get_all_plugin_names`: Get the names of all plugins, in the order it will be executed.
- `simplug.get_enabled_plugins`: Get a dictionary of name-plugin mappings of all enabled plugins
- `simplug.get_enabled_plugin_names`: Get the names of all enabled plugins, in the order it will be executed.
### Calling hooks
Hooks are call by `simplug.hooks.<hook_name>(<arguments>)` and results are collected based on the `result` argument passed in `simplug.spec` when defining hooks.
### Async hooks
It makes no big difference to define an async hook:
```python
@simplug.spec
async def async_hook(arg):
...
# to supress warnings for sync implementation
@simplug.spec(warn_sync_impl_on_async=False)
async def async_hook(arg):
...
```
One can implement this hook in either an async or a sync way. However, when implementing it in a sync way, a warning will be raised. To suppress the warning, one can pass a `False` value of argument `warn_sync_impl_on_async` to `simplug.spec`.
To call the async hooks (`simplug.hooks.async_hook(arg)`), you will just need to call it like any other async functions (using `asyncio.run`, for example)
## API
https://pwwang.github.io/simplug/
Raw data
{
"_id": null,
"home_page": "https://github.com/pwwang/simplug",
"name": "simplug",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "pwwang",
"author_email": "pwwang@pwwang.com",
"download_url": "https://files.pythonhosted.org/packages/d3/2a/b5738e577a00f5ba33f6ce620569897fdff912abda942ad91abe7063e7a4/simplug-0.4.3.tar.gz",
"platform": null,
"description": "# simplug\n\nA simple plugin system for python with async hooks supported\n\n## Installation\n\n```shell\npip install -U simplug\n```\n\n## Examples\n\n### A toy example\n\n```python\nfrom simplug import Simplug\n\nsimplug = Simplug('project')\n\nclass MySpec:\n \"\"\"A hook specification namespace.\"\"\"\n\n @simplug.spec\n def myhook(self, arg1, arg2):\n \"\"\"My special little hook that you can customize.\"\"\"\n\nclass Plugin_1:\n \"\"\"A hook implementation namespace.\"\"\"\n\n @simplug.impl\n def myhook(self, arg1, arg2):\n print(\"inside Plugin_1.myhook()\")\n return arg1 + arg2\n\nclass Plugin_2:\n \"\"\"A 2nd hook implementation namespace.\"\"\"\n\n @simplug.impl\n def myhook(self, arg1, arg2):\n print(\"inside Plugin_2.myhook()\")\n return arg1 - arg2\n\nsimplug.register(Plugin_1, Plugin_2)\nresults = simplug.hooks.myhook(arg1=1, arg2=2)\nprint(results)\n```\n\n```shell\ninside Plugin_1.myhook()\ninside Plugin_2.myhook()\n[3, -1]\n```\n\nNote that the hooks are executed in the order the plugins are registered. This is different from `pluggy`.\n\n### A complete example\n\nSee `examples/complete/`.\n\nRunning `python -m examples.complete` gets us:\n\n```shell\nYour food. Enjoy some egg, egg, egg, salt, pepper, egg, egg\nSome condiments? We have pickled walnuts, steak sauce, mushy peas, mint sauce\n```\n\nAfter install the plugin:\n\n```shell\n> pip install --editable examples.complete.plugin\n> python -m examples.complete # run again\n```\n\n```shell\nYour food. Enjoy some egg, egg, egg, salt, pepper, egg, egg, lovely spam, wonderous spam\nSome condiments? We have pickled walnuts, mushy peas, mint sauce, spam sauce\nNow this is what I call a condiments tray!\n```\n\n## Usage\n\n### Definition of hooks\n\nHooks are specified and implemented by decorating the functions with `simplug.spec` and `simplug.impl` respectively.\n\n`simplug` is initialized by:\n\n```python\nsimplug = Simplug('project')\n```\n\nThe `'project'` is a unique name to mark the project, which makes sure `Simplug('project')` get the same instance each time.\n\nNote that if `simplug` is initialized without `project`, then a name is generated automatically as such `project-0`, `project-1`, etc.\n\nHook specification is marked by `simplug.spec`:\n\n```python\nsimplug = Simplug('project')\n\n@simplug.spec\ndef setup(args):\n ...\n```\n\n`simplug.spec` can take some arguments:\n\n- `required`: Whether this hook is required to be implemented in plugins\n- `result`: An enumerator to specify the way to collec the results.\n - `SimplugResult.ALL`: Collect all results from all plugins\n - `SimplugResult.ALL_AVAILS`: Get all the results from the hook, as a list, not including `None`s\n - `SimplugResult.ALL_FIRST`: Executing all implementations and get the first result\n - `SimplugResult.ALL_LAST`: Executing all implementations and get the last result\n - `SimplugResult.TRY_ALL_FIRST`: Executing all implementations and get the first result, if no result is returned, return `None`\n - `SimplugResult.TRY_ALL_LAST`: Executing all implementations and get the last result, if no result is returned, return `None`\n - `SimplugResult.ALL_FIRST_AVAIL`: Executing all implementations and get the first non-`None` result\n - `SimplugResult.ALL_LAST_AVAIL`: Executing all implementations and get the last non-`None` result\n - `SimplugResult.TRY_ALL_FIRST_AVAIL`: Executing all implementations and get the first non-`None` result, if no result is returned, return `None`\n - `SimplugResult.TRY_ALL_LAST_AVAIL`: Executing all implementations and get the last non-`None` result, if no result is returned, return `None`\n - `SimplugResult.FIRST`: Get the first result, don't execute other implementations\n - `SimplugResult.LAST`: Get the last result, don't execute other implementations\n - `SimplugResult.TRY_FIRST`: Get the first result, don't execute other implementations, if no result is returned, return `None`\n - `SimplugResult.TRY_LAST`: Get the last result, don't execute other implementations, if no result is returned, return `None`\n - `SimplugResult.FIRST_AVAIL`: Get the first non-`None` result, don't execute other implementations\n - `SimplugResult.LAST_AVAIL`: Get the last non-`None` result, don't execute other implementations\n - `SimplugResult.TRY_FIRST_AVAIL`: Get the first non-`None` result, don't execute other implementations, if no result is returned, return `None`\n - `SimplugResult.TRY_LAST_AVAIL`: Get the last non-`None` result, don't execute other implementations, if no result is returned, return `None`\n - `SimplugResult.SINGLE`: Get the result from a single implementation\n - `SimplugResult.TRY_SINGLE`: Get the result from a single implementation, if no result is returned, return `None`\n - A callable to collect the result, take `calls` as the argument, a 3-element tuple with first element as the implementation, second element as the positional arguments, and third element as the keyword arguments.\n\nHook implementation is marked by `simplug.impl`, which takes no additional arguments.\n\nThe name of the function has to match the name of the function by `simplug.spec`. And the signatures of the specification function and the implementation function have to be the same in terms of names. This means you can specify default values in the specification function, but you don't have to write the default values in the implementation function.\n\nNote that default values in implementation functions will be ignored.\n\nAlso note if a hook specification is under a namespace, it can take `self` as argument. However, this argument will be ignored while the hook is being called (`self` will be `None`, and you still have to specify it in the function definition).\n\n### Loading plugins from setuptools entrypoint\n\nYou have to call `simplug.load_entrypoints(group)` after the hook specifications are defined to load the plugins registered by setuptools entrypoint. If `group` is not given, the project name will be used.\n\n### The plugin registry\n\nThe plugins are registered by `simplug.register(*plugins)`. Each plugin of `plugins` can be either a python object or a str denoting a module that can be imported by `importlib.import_module`.\n\nThe python object must have an attribute `name`, `__name__` or `__class.__name__` for `simplug` to determine the name of the plugin. If the plugin name is determined from `__name__` or `__class__.__name__`, it will be lowercased.\n\nIf a plugin is loaded from setuptools entrypoint, then the entrypoint name will be used (no matter what name is defined inside the plugin)\n\nYou can enable or disable a plugin temporarily after registration by:\n\n```python\nsimplug.disable('plugin_name')\nsimplug.enable('plugin_name')\n```\n\nYou can use following methods to inspect the plugin registry:\n\n- `simplug.get_plugin`: Get the plugin by name\n- `simplug.get_all_plugins`: Get a dictionary of name-plugin mappings of all plugins\n- `simplug.get_all_plugin_names`: Get the names of all plugins, in the order it will be executed.\n- `simplug.get_enabled_plugins`: Get a dictionary of name-plugin mappings of all enabled plugins\n- `simplug.get_enabled_plugin_names`: Get the names of all enabled plugins, in the order it will be executed.\n\n### Calling hooks\n\nHooks are call by `simplug.hooks.<hook_name>(<arguments>)` and results are collected based on the `result` argument passed in `simplug.spec` when defining hooks.\n\n### Async hooks\n\nIt makes no big difference to define an async hook:\n\n```python\n@simplug.spec\nasync def async_hook(arg):\n ...\n\n# to supress warnings for sync implementation\n@simplug.spec(warn_sync_impl_on_async=False)\nasync def async_hook(arg):\n ...\n```\n\nOne can implement this hook in either an async or a sync way. However, when implementing it in a sync way, a warning will be raised. To suppress the warning, one can pass a `False` value of argument `warn_sync_impl_on_async` to `simplug.spec`.\n\nTo call the async hooks (`simplug.hooks.async_hook(arg)`), you will just need to call it like any other async functions (using `asyncio.run`, for example)\n\n## API\n\nhttps://pwwang.github.io/simplug/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple plugin system for python with async hooks supported",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/pwwang/simplug",
"Repository": "https://github.com/pwwang/simplug"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5195405c13348ffcbee9f32237c048710b7c31ce571130cd8a846f2cab9aef5c",
"md5": "1a5591ef445b5cc8b65fd7c16eadd278",
"sha256": "393087afb99e3df83054a967ebf57a2b6fda8addda084d241ddd6470f06de78a"
},
"downloads": -1,
"filename": "simplug-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1a5591ef445b5cc8b65fd7c16eadd278",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 11391,
"upload_time": "2024-07-21T06:36:05",
"upload_time_iso_8601": "2024-07-21T06:36:05.952622Z",
"url": "https://files.pythonhosted.org/packages/51/95/405c13348ffcbee9f32237c048710b7c31ce571130cd8a846f2cab9aef5c/simplug-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d32ab5738e577a00f5ba33f6ce620569897fdff912abda942ad91abe7063e7a4",
"md5": "c8a13d47956164c5c65c5ce0491cdfca",
"sha256": "2a3332af56ecc1addc72d9950ecb17b7f9e08f04a8a766540946798f8b428672"
},
"downloads": -1,
"filename": "simplug-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "c8a13d47956164c5c65c5ce0491cdfca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 13710,
"upload_time": "2024-07-21T06:36:07",
"upload_time_iso_8601": "2024-07-21T06:36:07.322268Z",
"url": "https://files.pythonhosted.org/packages/d3/2a/b5738e577a00f5ba33f6ce620569897fdff912abda942ad91abe7063e7a4/simplug-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-21 06:36:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pwwang",
"github_project": "simplug",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "simplug"
}
