Commit 28dd2841 authored by Cyril Guilloud's avatar Cyril Guilloud
Browse files

doc about capture_exceptions contextmanager

parent d54f7b27
Pipeline #46649 passed with stages
in 98 minutes and 24 seconds
......@@ -242,14 +242,19 @@ def capture_exceptions(raise_index=-1, excepthook=None):
do_C()
The inner contexts protect the execution by capturing any exception
raised. This allows the next contexts to run. When leaving the main
context, the last exception is raised, if any. If the `raise_index`
argument is set to `0`, the first exception is raised instead. This
behavior can also be disabled by setting `raise_index` to None. The
other exceptions are processed through the given excepthook, which
defaults to `sys.excepthook`. A list containing the information about
the raised exception can be retreived using the `exception_infos`
attribute of the `capture` object or the raised exception.
raised. This allows the next contexts to run. When leaving the main context,
the last exception is raised, if any.
If the `raise_index` argument is set to `0`, the first exception is raised
instead. This behavior can also be disabled by setting `raise_index` to
None.
The other exceptions are processed through the given excepthook, which
defaults to `sys.excepthook`.
A list containing the information about the raised exception can be
retreived using the `exception_infos` attribute of the `capture` object or
the raised exception.
"""
assert raise_index in (0, -1, None)
......
......@@ -62,6 +62,105 @@ return scan
```
## Exceptions
### capture_exceptions() context manager
`capture_exceptions()` is a context manager to capture and manage multiple
exceptions.
Usage:
```python
with capture_exceptions() as capture:
with capture():
do_A()
with capture():
do_B()
with capture():
do_C()
```
The inner contexts (`with capture()`) protect the execution by capturing any
exception raised. This allows the next contexts to run. When leaving the main
context (`with capture_exceptions()`), the **last** exception (potentially raised by
by `do_C()` here) is raised, if any.
If the `raise_index` argument is set to `0`, the **first** exception is raised
instead. This behavior can also be disabled by setting `raise_index` to
**None**.
The other exceptions are processed through the given excepthook, which
defaults to `sys.excepthook`.
A list containing the information about the raised exception can be
retreived using the `exception_infos` attribute of the `capture` object or
the raised exception.
Example:
```python
print("-------------------- capture_exc START ------------------")
def my_exc_handler(exc_type, exc_value, exc_traceback):
print(" +++ FBF:", "exc_type=", exc_type,
"exc_value=", exc_value,
"exc_traceback=", exc_traceback, flush=True)
with capture_exceptions(raise_index=None, excepthook=my_exc_handler) as capture:
with capture():
print("try to print 123/0", flush=True)
print(123/0)
print("")
with capture():
print("try to decode a str", flush=True)
print("ee".decode())
if capture.failed:
print("oh no, you cannot decode a str")
exc_type, exc_value, exc_traceback = capture.exception_infos[-1]
print(f"it has raised a '{exc_type}' exception")
print("")
with capture():
print("try to print toto (not def)", flush=True)
print(toto)
print("-------------------- capture_exc END ------------------", flush=True)
```
The previous example produce this (long lines are wrapped for clarity) at
execution:
`raised` is set to None so no exception is raised.
```python
-------------------- capture_exc START ------------------
try to print 123/0
+++ FBF: exc_type= <class 'ZeroDivisionError'>
exc_value= division by zero
exc_traceback= <traceback object at 0x7faa58be65f0>
try to decode a str
+++ FBF: exc_type= <class 'AttributeError'>
exc_value= 'str' object has no attribute 'decode'
exc_traceback= <traceback object at 0x7faa58be6230>
oh no, you cannot decode a str
it has raised a '<class 'AttributeError'>' exception
try to print toto (not def)
+++ FBF: exc_type= <class 'NameError'>
exc_value= name 'toto' is not defined
exc_traceback= <traceback object at 0x7faa58c267d0>
-------------------- capture_exc END ------------------
```
## informing the user
`bliss.common.user_status_info` provides a mechanism to send information to the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment