How to Hook to Events
There are three different ways in which
byexample can be extended:
- define zones where to find examples
- support new languages: how to find them and how to run them
- perform arbitrary actions during the execution
byexample uses the concept of modules: a python file with some extension
classes defined there. Modules can be loaded using
from the command line.
What extension classes will depend of what you want to extend or customize.
how-to we will see how to hook to events and perform arbitrary
actions during the execution.
Let’s show this by example.
How to perform arbitrary actions during the execution: Concern
During the execution of the whole set of examples,
byexample will execute
some callbacks or hooks at particular moments like before running an example or
after it failed.
The set of hooks are collected into the
Concern interface (also known as
You can create and add your own to extend the capabilities of
- show the progress of the execution
- log / report generation for export
- log execution time history for future execution time prediction (estimate)
- turn on/off debugging, coverage and profile facilities
Eg: Dump the Script
Let’s imagine that we want to save in a file all the examples’ code without the expected strings nor anything else.
>>> from byexample.concern import Concern >>> class DumpScript(Concern): ... target = 'dump-script' ... ... def start_run(self, examples, runners, filepath): ... self.f = open(filepath + ".script") ... ... def end_run(self, failed, user_aborted, crashed): ... self.f.close() ... ... def start_example(self, example, options): ... self.f.write(example.source)
See the documentation of the class
byexample/concern.py to get a description of all the
possible hooks and when they are called.
byexample uses this mechanism to generate a progress bar in
Concern instance will be created once during the setup of
byexample and then it will be created once per job thread.
By default there is only one job thread but more threads can be added
If you want to share data among them you will have to use a
thread-safe structures created by a
sharer and store them
byexample 10.0.0. Before
10.0.0you were forced to use
multiprocessingby hand but in
10.0.0the concurrency model is hidden so you cannot relay on
byexamplemay not use processes at all!
namespaceare objects that hide the details while allowing you to have the same power.
If you extend
Concern and decide to implement your own
you must ensure that you call
passing to it all the keyword-only arguments that you received.
Once done that, you can use the
self.cfg property to access any
configuration set in
byexample including the flags/options set
__init__ you can also change the value of
target to something
different. For a
Concern this is typically used to enable/disable
the concern object based on the configuration by just setting
self.target = "some string" (enable) or
self.target = None
See Extension initialization for more about this and some troubleshooting.