Simple and readable Pure Python callbacks!
Project description
callpyback
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
andon_end
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 .
pip install callpyback
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_kwargs
- will receive parameters passed to the function decorated withCallPyBack
b) on_success()
callback MUST either accept no parameters or combination of the following:
func_result
- will receive return value of the function decorated withCallPyBack
func_kwargs
- will receive parameters passed to the function decorated withCallPyBack
c) on_failure()
callback MUST either accept no parameters or combination of the following:
func_exception
- will receive exception raised by the function decorated withCallPyBack
func_kwargs
- will receive parameters passed to the function decorated withCallPyBack
d) on_end()
callback MUST either accept no parameters or combination of the following:
func_result
- will receive return value of the function decorated withCallPyBack
func_exception
- will receive exception raised by the function decorated withCallPyBack
func_kwargs
- will receive parameters passed to the function decorated withCallPyBack
func_scope_vars
- will receive local variables of the function decorated withCallPyBack
, whose names were specified in thepass_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.
1. Decorating the function with CallPyBack
class decorator with callback functions specified
def on_success(func_result):
print(f'Done with a result: {func_result}!')
def on_failure(func_exception):
print(f'Failed with an error: {func_exception}!')
@CallPyBack(on_success=on_success, on_failure=on_failure)
def method()
pass
method()
2. Preconfigured CallPyBack
callback custom class
def on_success(func_result):
print(f'Done with a result: {func_result}!')
def on_failure(func_exception):
print(f'Failed with an error: {func_exception}!')
custom_callpyback = CallPyBack(
on_success=on_success,
on_failure=on_failure
)
@custom_callpyback
def method():
pass
method()
3. Using @background_callpyback
decorator to make callback execute on the background thread
@background_callpyback
def on_success(func_result):
print(f'Done with a result: {func_result}!')
def on_failure(func_exception):
print(f'Failed with an error: {func_exception}!')
custom_callpyback = CallPyBack(
on_success=on_success,
on_failure=on_failure
)
@custom_callpyback
def method():
pass
method()
In this case, on_success
will be executed on the background thread, while on_failure
will be executed in a blocking way.
4. Passing local variables of decorated function, specified in pass_vars
to on_end
callback
def on_end(func_result, func_scope_vars):
print(f'Done with a result: {func_result}!')
print(f'Local function variables: {func_scope_vars}')
custom_callpyback = CallPyBack(
on_end=on_end,
pass_vars=('a', 'b')
)
@custom_callpyback
def method():
a = 0
b = 1
return a
method()
5. Specifiyng default return value by default_return
parameter.
custom_callpyback = CallPyBack(
default_return=-1
)
@custom_callpyback
def method():
raise KeyError('fail')
result = method()
In this case, result will be equal to -1
specified in default_return
.
6. Specifiyng exception classes to be caught by exception_classes
parameter.
def on_failure(func_exception):
print(f'Failed with an error: {func_exception}!')
custom_callpyback = CallPyBack(
on_failure=on_failure,
exception_classes=(TypeError,)
)
@custom_callpyback
def method():
raise KeyError('fail')
result = method()
In this case, exception will be raised, which will not execute failure handler, but re-raise original exception.
Roadmap
- Add Changelog
- Support
on_call
,on_success
,on_failure
andon_end
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 - Add
asyncio
support for decorated function - Add
asyncio
support for callback function - TBD...
See the open issues for a full list of proposed features (and known issues).
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!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/feature-name
) - Commit your Changes (
git commit -m 'Add some FeatureName'
) - Push to the Branch (
git push origin feature/feature-name
) - Open a Pull Request
- Let us review your magical feature
License
Distributed under the MIT License. See LICENSE.txt
for more information.
Contact
Samuel Gregorovič - samuel-gregorovic - samuelgregorovic@gmail.com
Project Link: https://github.com/samuelgregorovic/callpyback
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.