<a id="readme-top"></a>
# callpyback
[](https://python.org)
[](https://github.com/samuelgregorovic/callpyback/actions/workflows/build.yaml)
[](https://coveralls.io/github/samuelgregorovic/callpyback)
[](https://badge.fury.io/py/callpyback)
[](https://snyk.io/test/github/samuelgregorovic/callpyback)
[](https://codeclimate.com/github/samuelgregorovic/callpyback/maintainability)
[](https://github.com/samuelgregorovic/callpyback/issues)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://pepy.tech/project/callpyback)
[](https://www.repostatus.org/#active)
[](https://github.com/samuelgregorovic/callpyback/pulse)
## Description
"callpyback" is a comprehensive Python library designed to help developers add callbacks to their functions with ease. It comes with a range of powerful features that make it easy to customize the behavior of your functions in different stages of their execution.
You can specify callbacks for on_call, on_success, on_failure, and on_end, and customize the default return value from the decorated function. Additionally, you can pass local scope variables of the decorated function to the on_end callback and define expected exceptions to trigger the on_failure callback. If desired, you can also omit callbacks, falling back to default behavior, and choose which parameters of the callback function to use. Furthermore, with the @background_callback decorator, you can execute callbacks on the background, making it easier to manage concurrency in your code.
## Features
- Support `on_call`, `on_success`, `on_failure` and `on_end` callbacks
- Pass decorated function **kwargs and function itself to callbacks
- Option to specify default return from the decorated function
- Option to pass local scope variables of the decorated function to the `on_end` callback
- Option to specify exception classes to be expected and invoke `on_failure` callback
- Option to omit callbacks - default callback
- Option to omit callback's function parameters (specify only those which you need)
- Option to execute callbacks on the background (new thread) via `@background_callpyback` decorator
### Instalation
Package is currently available under the same name at [](https://badge.fury.io/py/callpyback).
`pip install callpyback`
<p align="right">(<a href="#readme-top">back to top</a>)</p>
### Usage
### ! important note !
In latest version of `callpyback`, when declaring callback functions, following rules must be obeyed:
a) `on_call()` callback MUST eitheraccept no parameters or combination of the following:
- `func` - will receive reference to decorated function
- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`
b) `on_success()` callback MUST either accept no parameters or combination of the following:
- `func` - will receive reference to decorated function
- `func_result` - will receive return value of the function decorated with `CallPyBack`
- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`
c) `on_failure()` callback MUST either accept no parameters or combination of the following:
- `func` - will receive reference to decorated function
- `func_exception` - will receive exception raised by the function decorated with `CallPyBack`
- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`
d) `on_end()` callback MUST either accept no parameters or combination of the following:
- `func` - will receive reference to decorated function
- `func_result` - will receive return value of the function decorated with `CallPyBack`
- `func_exception` - will receive exception raised by the function decorated with `CallPyBack`
- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`
- `func_scope_vars` - will receive local variables of the function decorated with `CallPyBack`, whose names were specified in the `pass_vars` decorator parameter.
These rules are enforced to allow omitting parameters in the callback function. This is useful when some of these parameters are not needed for the callback function. If those rules are not obeyed, error will be raised during the initialization of the `CallPyBack` decorator class.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
#### Prerequisites
Consider following callbacks:
```python
def on_call(func, func_kwargs):
print('-----ON CALL CALLBACK-----')
func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())
print(f'Function `{func.__name__}` called with parameters: {func_kwargs_repr}.\n')
@background_callpyback
def on_success(func, func_result, func_kwargs):
print('-----ON SUCCESS CALLBACK-----')
func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())
print(f'Function `{func.__name__}` successfully done with a result: {func_result}.')
print(f'Was called with parameters: {func_kwargs_repr}\n')
@background_callpyback
def on_failure(func, func_exception, func_kwargs):
print('-----ON FAILURE CALLBACK-----')
func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())
print(f'Function `{func.__name__} failed with an error: {func_exception}!')
print(f'Was called with parameters: {func_kwargs_repr}\n')
@background_callpyback
def on_end(func, func_result, func_exception, func_kwargs, func_scope_vars):
print('-----ON END CALLBACK-----')
func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())
func_scope_vars_repr = ', '.join(f'{key}={val}' for key, val in func_scope_vars.items())
if func_exception:
print(f'Function `{func.__name__} failed with an error: {func_exception}!')
else:
print('No exception was raised')
print(f'Function `{func.__name__}` done with a result: {func_result}.')
print(f'Was called with parameters: {func_kwargs_repr}')
print(f'Local variables of the function: {func_scope_vars_repr}')
```
and initialization of a decorator:
```python
custom_callpyback = CallPyBack(
on_call=on_call,
on_success=on_success,
on_failure=on_failure,
on_end=on_end,
default_return='default',
exception_classes=(RuntimeError,),
pass_vars=('a',)
)
```
These will be used in following examples:
#### 1. Decorated function executes without error
```python
@custom_callpyback
def method(x, y, z=None):
a = 42
return x + y
result = method(1, 2)
print(f'Result: {result}')
```
will result in
```bash
-----ON CALL CALLBACK-----
Function `method` called with parameters: x=1, y=2, z=None.
Result: 3
-----ON SUCCESS CALLBACK-----
Function `method` successfully done with a result: 3.
Was called with parameters: x=1, y=2, z=None
-----ON END CALLBACK-----
No exception was raised
Function `method` done with a result: 3.
Was called with parameters: x=1, y=2, z=None
Local variables of the function: a=42
```
`on_success` and `on_end` will be executed on the background thread, while `on_call` will be executed in a blocking way and `on_failure` will not be called.
#### 2. Decorated function raises an error
```python
@custom_callpyback
def method(x, y, z=None):
a = 42
raise RuntimeError("some error")
result = method(1, 2)
print(f'Result: {result}')
```
will result in
```bash
-----ON CALL CALLBACK-----
Function `method` called with parameters: x=1, y=2, z=None.
-----ON FAILURE CALLBACK-----
Function `method` failed with an error: some error!
Was called with parameters: x=1, y=2, z=None
-----ON END CALLBACK-----
Function `method` failed with an error: some error!
Function `method` done with a result: default.
Was called with parameters: x=1, y=2, z=None
Local variables of the function: a=42
```
`on_failure` and `on_end` will be executed on the background thread, while `on_call` will be executed in a blocking way and `on_success` will not be called.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
## Roadmap
- [x] Add Changelog
- [x] Support `on_call`, `on_success`, `on_failure` and `on_end` callbacks
- [x] Option to specify default return from the decorated function
- [x] Option to pass local scope variables of the decorated function to the `on_end` callback
- [x] Option to specify exception classes to be expected and invoke `on_failure` callback
- [x] Option to omit callbacks - default callback
- [x] Option to omit callback's function parameters (specify only those which you need)
- [x] Option to execute callbacks on the background (new thread) via `@background_callpyback` decorator
- [x] Option to pass decorated function reference to all callbacks
- [ ] To be determined...
See the [open issues](https://github.com/samuelgregorovic/callpyback/issues) for a full list of proposed features (and known issues).
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- CONTRIBUTING -->
## Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/feature-name`)
3. Commit your Changes (`git commit -m 'Add some FeatureName'`)
4. Push to the Branch (`git push origin feature/feature-name`)
5. Open a Pull Request
6. Let us review your magical feature
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- LICENSE -->
## License
Distributed under the MIT License. See [`LICENSE.txt`](https://github.com/samuelgregorovic/callpyback/blob/main/LICENSE.txt) for more information.
<p align="right">(<a href="#readme-top">back to top</a>)</p>
<!-- CONTACT -->
## Contact
Samuel Gregorovič - [samuel-gregorovic](https://www.linkedin.com/in/samuel-gregorovic) - samuelgregorovic@gmail.com
Project Link: [https://github.com/samuelgregorovic/callpyback](https://github.com/samuelgregorovic/callpyback)
<p align="right">(<a href="#readme-top">back to top</a>)</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/samuelgregorovic/callpyback",
"name": "callpyback",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "callpyback,callback,python,pure,pythonic,background",
"author": "samuelgregorovic",
"author_email": "samuelgregorovic@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/d1/31ada295099e3a315f8f24b8f9f671e7fa6e12ccdafc603921055aeb8157/callpyback-1.2.1.tar.gz",
"platform": null,
"description": "<a id=\"readme-top\"></a> \n\n# callpyback\n[](https://python.org)\n[](https://github.com/samuelgregorovic/callpyback/actions/workflows/build.yaml)\n[](https://coveralls.io/github/samuelgregorovic/callpyback)\n[](https://badge.fury.io/py/callpyback)\n[](https://snyk.io/test/github/samuelgregorovic/callpyback)\n[](https://codeclimate.com/github/samuelgregorovic/callpyback/maintainability)\n[](https://github.com/samuelgregorovic/callpyback/issues)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\n[](https://pepy.tech/project/callpyback)\n[](https://www.repostatus.org/#active)\n[](https://github.com/samuelgregorovic/callpyback/pulse)\n\n## Description\n\"callpyback\" is a comprehensive Python library designed to help developers add callbacks to their functions with ease. It comes with a range of powerful features that make it easy to customize the behavior of your functions in different stages of their execution. \n\nYou can specify callbacks for on_call, on_success, on_failure, and on_end, and customize the default return value from the decorated function. Additionally, you can pass local scope variables of the decorated function to the on_end callback and define expected exceptions to trigger the on_failure callback. If desired, you can also omit callbacks, falling back to default behavior, and choose which parameters of the callback function to use. Furthermore, with the @background_callback decorator, you can execute callbacks on the background, making it easier to manage concurrency in your code.\n\n## Features\n\n- Support `on_call`, `on_success`, `on_failure` and `on_end` callbacks\n- Pass decorated function **kwargs and function itself to callbacks\n- Option to specify default return from the decorated function\n- Option to pass local scope variables of the decorated function to the `on_end` callback\n- Option to specify exception classes to be expected and invoke `on_failure` callback\n- Option to omit callbacks - default callback\n- Option to omit callback's function parameters (specify only those which you need)\n- Option to execute callbacks on the background (new thread) via `@background_callpyback` decorator\n\n### Instalation\nPackage is currently available under the same name at [](https://badge.fury.io/py/callpyback).\n\n`pip install callpyback`\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n\n### Usage\n\n### ! important note !\nIn latest version of `callpyback`, when declaring callback functions, following rules must be obeyed:\n\na) `on_call()` callback MUST eitheraccept no parameters or combination of the following:\n- `func` - will receive reference to decorated function\n- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`\n\nb) `on_success()` callback MUST either accept no parameters or combination of the following:\n- `func` - will receive reference to decorated function\n- `func_result` - will receive return value of the function decorated with `CallPyBack`\n- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`\n\nc) `on_failure()` callback MUST either accept no parameters or combination of the following:\n- `func` - will receive reference to decorated function\n- `func_exception` - will receive exception raised by the function decorated with `CallPyBack`\n- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`\n\nd) `on_end()` callback MUST either accept no parameters or combination of the following:\n- `func` - will receive reference to decorated function\n- `func_result` - will receive return value of the function decorated with `CallPyBack`\n- `func_exception` - will receive exception raised by the function decorated with `CallPyBack`\n- `func_kwargs` - will receive parameters passed to the function decorated with `CallPyBack`\n- `func_scope_vars` - will receive local variables of the function decorated with `CallPyBack`, whose names were specified in the `pass_vars` decorator parameter.\n\nThese rules are enforced to allow omitting parameters in the callback function. This is useful when some of these parameters are not needed for the callback function. If those rules are not obeyed, error will be raised during the initialization of the `CallPyBack` decorator class.\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n#### Prerequisites\nConsider following callbacks:\n```python\ndef on_call(func, func_kwargs):\n print('-----ON CALL CALLBACK-----')\n func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())\n print(f'Function `{func.__name__}` called with parameters: {func_kwargs_repr}.\\n')\n\n@background_callpyback\ndef on_success(func, func_result, func_kwargs):\n print('-----ON SUCCESS CALLBACK-----')\n func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())\n print(f'Function `{func.__name__}` successfully done with a result: {func_result}.')\n print(f'Was called with parameters: {func_kwargs_repr}\\n')\n\n@background_callpyback\ndef on_failure(func, func_exception, func_kwargs):\n print('-----ON FAILURE CALLBACK-----')\n func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())\n print(f'Function `{func.__name__} failed with an error: {func_exception}!')\n print(f'Was called with parameters: {func_kwargs_repr}\\n')\n\n@background_callpyback\ndef on_end(func, func_result, func_exception, func_kwargs, func_scope_vars):\n print('-----ON END CALLBACK-----')\n func_kwargs_repr = ', '.join(f'{key}={val}' for key, val in func_kwargs.items())\n func_scope_vars_repr = ', '.join(f'{key}={val}' for key, val in func_scope_vars.items())\n if func_exception:\n print(f'Function `{func.__name__} failed with an error: {func_exception}!')\n else:\n print('No exception was raised')\n print(f'Function `{func.__name__}` done with a result: {func_result}.')\n print(f'Was called with parameters: {func_kwargs_repr}')\n print(f'Local variables of the function: {func_scope_vars_repr}')\n```\nand initialization of a decorator:\n```python\ncustom_callpyback = CallPyBack(\n on_call=on_call,\n on_success=on_success,\n on_failure=on_failure,\n on_end=on_end,\n default_return='default', \n exception_classes=(RuntimeError,),\n pass_vars=('a',)\n)\n```\nThese will be used in following examples:\n\n#### 1. Decorated function executes without error\n```python\n\n@custom_callpyback\ndef method(x, y, z=None):\n a = 42\n return x + y\n\nresult = method(1, 2)\nprint(f'Result: {result}')\n```\nwill result in\n```bash\n-----ON CALL CALLBACK-----\nFunction `method` called with parameters: x=1, y=2, z=None.\n\nResult: 3\n\n-----ON SUCCESS CALLBACK-----\nFunction `method` successfully done with a result: 3.\nWas called with parameters: x=1, y=2, z=None\n\n-----ON END CALLBACK-----\nNo exception was raised\nFunction `method` done with a result: 3.\nWas called with parameters: x=1, y=2, z=None\nLocal variables of the function: a=42\n\n```\n`on_success` and `on_end` will be executed on the background thread, while `on_call` will be executed in a blocking way and `on_failure` will not be called.\n\n#### 2. Decorated function raises an error\n```python\n\n@custom_callpyback\ndef method(x, y, z=None):\n a = 42\n raise RuntimeError(\"some error\")\n\nresult = method(1, 2)\nprint(f'Result: {result}')\n```\nwill result in\n```bash\n-----ON CALL CALLBACK-----\nFunction `method` called with parameters: x=1, y=2, z=None.\n\n-----ON FAILURE CALLBACK-----\nFunction `method` failed with an error: some error!\nWas called with parameters: x=1, y=2, z=None\n\n-----ON END CALLBACK-----\nFunction `method` failed with an error: some error!\nFunction `method` done with a result: default.\nWas called with parameters: x=1, y=2, z=None\nLocal variables of the function: a=42\n\n```\n`on_failure` and `on_end` will be executed on the background thread, while `on_call` will be executed in a blocking way and `on_success` will not be called.\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n## Roadmap\n\n- [x] Add Changelog\n- [x] Support `on_call`, `on_success`, `on_failure` and `on_end` callbacks\n- [x] Option to specify default return from the decorated function\n- [x] Option to pass local scope variables of the decorated function to the `on_end` callback\n- [x] Option to specify exception classes to be expected and invoke `on_failure` callback\n- [x] Option to omit callbacks - default callback\n- [x] Option to omit callback's function parameters (specify only those which you need)\n- [x] Option to execute callbacks on the background (new thread) via `@background_callpyback` decorator\n- [x] Option to pass decorated function reference to all callbacks\n- [ ] To be determined...\n\nSee the [open issues](https://github.com/samuelgregorovic/callpyback/issues) for a full list of proposed features (and known issues).\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n\n<!-- CONTRIBUTING -->\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/feature-name`)\n3. Commit your Changes (`git commit -m 'Add some FeatureName'`)\n4. Push to the Branch (`git push origin feature/feature-name`)\n5. Open a Pull Request\n6. Let us review your magical feature\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n\n<!-- LICENSE -->\n## License\n\nDistributed under the MIT License. See [`LICENSE.txt`](https://github.com/samuelgregorovic/callpyback/blob/main/LICENSE.txt) for more information.\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n\n<!-- CONTACT -->\n## Contact\n\nSamuel Gregorovi\u010d - [samuel-gregorovic](https://www.linkedin.com/in/samuel-gregorovic) - samuelgregorovic@gmail.com\n\nProject Link: [https://github.com/samuelgregorovic/callpyback](https://github.com/samuelgregorovic/callpyback)\n\n<p align=\"right\">(<a href=\"#readme-top\">back to top</a>)</p>\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Simple and readable Pure Python callbacks!",
"version": "1.2.1",
"split_keywords": [
"callpyback",
"callback",
"python",
"pure",
"pythonic",
"background"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50d131ada295099e3a315f8f24b8f9f671e7fa6e12ccdafc603921055aeb8157",
"md5": "56ce335ea9a3ebc372ce53d201fb95ec",
"sha256": "973473e5431d240021ac296e2f338aac2d743a3190f9bea43d5b09f953eb20ad"
},
"downloads": -1,
"filename": "callpyback-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "56ce335ea9a3ebc372ce53d201fb95ec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16458,
"upload_time": "2023-02-07T19:02:40",
"upload_time_iso_8601": "2023-02-07T19:02:40.725142Z",
"url": "https://files.pythonhosted.org/packages/50/d1/31ada295099e3a315f8f24b8f9f671e7fa6e12ccdafc603921055aeb8157/callpyback-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-07 19:02:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "samuelgregorovic",
"github_project": "callpyback",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "astroid",
"specs": [
[
"==",
"2.14.1"
]
]
},
{
"name": "attrs",
"specs": [
[
"==",
"22.2.0"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"23.1.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2022.12.7"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.3"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"6.5.0"
]
]
},
{
"name": "coveralls",
"specs": [
[
"==",
"3.3.1"
]
]
},
{
"name": "dill",
"specs": [
[
"==",
"0.3.6"
]
]
},
{
"name": "docopt",
"specs": [
[
"==",
"0.6.2"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.1.0"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.12.0"
]
]
},
{
"name": "lazy-object-proxy",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"0.4.3"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"23.0"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.11.0"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"2.6.2"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.10.0"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.2.1"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
"==",
"4.0.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.28.2"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "tomli",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "tomlkit",
"specs": [
[
"==",
"0.11.6"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.4.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.14"
]
]
},
{
"name": "wrapt",
"specs": [
[
"==",
"1.14.1"
]
]
}
],
"lcname": "callpyback"
}
JSON
