satella.instrumentation.trace_back package¶
Submodules¶
satella.instrumentation.trace_back.classes module¶
- class satella.instrumentation.trace_back.classes.GenerationPolicy(enable_pickling=True, compress_at=131072, repr_length_limit=131072, compression_level=6)¶
Bases:
object
A policy that manages generating a traceback
For a “default” policy it’s pretty customizable
Override if need be, and pass the class (or instance) to Traceback
- Parameters:
enable_pickling (bool) – bool, whether to enable pickling at all
compress_at (int) – pickles longer than this (bytes) will be compressed
repr_length_limit (int) – maximum p_len of __repr__. None for no limit.
compression_level (int) – “1” is fastest, “9” is slowest
- compress_at: int¶
- compression_level: int¶
- enable_pickling: bool¶
- get_compression_level(data_to_pickle)¶
What compression level to use to pickle this?
- Parameters:
data_to_pickle (bytes) – pickle value
- Returns:
int, 1-9, where “1” is the fastest, and “9” is the slowest, but produces best compression
- Return type:
int
- process_repr(r)¶
Process the string obtained from __repr__ing
- Parameters:
r (str) – result of a __repr__ on value
- Returns:
processed result
- Return type:
str
- repr_length_limit: int¶
- should_compress(pickle_data)¶
Should this pickle undergo compression?
- Parameters:
pickle_data (bytes) – pickle value
- Returns:
bool
- Return type:
bool
- should_pickle(value)¶
Should this value be pickled?
- Parameters:
value (Any) – value candidate
- Returns:
bool
- Return type:
bool
- class satella.instrumentation.trace_back.classes.StackFrame(frame, policy)¶
Bases:
JSONAble
Class used to verily preserve stack frames. Picklable.
- Parameters:
frame (frame) –
policy (GenerationPolicy) –
- filename: str¶
- classmethod from_json(x)¶
- Parameters:
x (dict) –
- Return type:
- globals: Dict[str, StoredVariableValue]¶
- lineno: int¶
- locals: Dict[str, StoredVariableValue]¶
- name: str¶
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- class satella.instrumentation.trace_back.classes.StoredVariableValue(value, policy=None)¶
Bases:
JSONAble
Class used to store a variable value. Picklable.
- Attributes are:
.repr - a text representation obtained using repr .typeinfo - a text representation of variable’s type .pickle - bytes with pickled (optionally processed) value, or None if
not available
- .pickle_type - what is stored in .pickle?
None - nothing “pickle” - normal Python pickle “pickle/gzip” - Python pickle treated with zlib.compress “failed” - could not pickle, pickle contains a UTF-8 text with
human-readable exception reason
- “failed/gzip” - compression failed, pickle contains a UTF-8 text with
human-readable exception reason
If value cannot be pickled, it’s repr will be at least preserved.
Note that the value itself won’t be preserved.
- Parameters:
value (Any) – any Python value to preserve
policy (Optional[GenerationPolicy]) – policy to use (instance)
- classmethod from_json(x)¶
- Parameters:
x (dict) –
- Return type:
- load_value()¶
Return the value that this represents.
WARNING! This may result in importing things from environment, as pickle.loads will be called.
- Returns:
stored value - if picklable and was pickled
- Raises:
ValueError – value has failed to be pickled or was never pickled
- pickle: bytes¶
- pickle_type: str¶
- repr: str¶
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- type_: str¶
satella.instrumentation.trace_back.trace_back module¶
- class satella.instrumentation.trace_back.trace_back.Traceback(starting_frame=None, policy=<class 'satella.instrumentation.trace_back.classes.GenerationPolicy'>)¶
Bases:
JSONAble
- Class used to preserve exceptions and chains of stack frames.
Picklable.
If starting frame is not given, an exception must be in progress.
You can also convert it to a secure representation, ie. one that will be completely JSON and thus safe to load from untrusted sources. You will not lose the unpicklability of them by doing so, as they can be safely reconstructed (pickle will be encoded as base64 string).
- Parameters:
starting_frame (Optional[Union[Exception, frame]]) – frame to start tracking the traceback from. Must be either None, in which case an exception must be in progress and will be taken else must be an instance of <class ‘frame’>.
policy – policy for traceback generation
- Raises:
ValueError – there is no traceback to get info from! Is any exception in process?
- formatted_traceback¶
- frames: List[StackFrame]¶
- classmethod from_pickle(pick)¶
Load a traceback from a pickle
- Parameters:
pick (Union[BytesIO, bytes]) – either bytes or a BytesIO to load it from
- Returns:
previously serialized Traceback
- Raises:
ValueError – unserialized object is not a Traceback!
- Return type:
- pickle()¶
Returns this instance, pickled
- Return type:
bytes
- pickle_to(stream)¶
Pickle self to target stream
- Parameters:
stream (BinaryIO) –
- Return type:
None
- pretty_format()¶
Return a multi-line, pretty-printed representation of all exception data.
- Returns:
text
- Return type:
str
- pretty_print(output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)¶
Pretty-print the exception
- Parameters:
output (TextIO) – a file-like object in text mode
- Returns:
unicode
- Return type:
None
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- satella.instrumentation.trace_back.trace_back.frame_from_traceback(tb)¶
Extract the bottom stack frame from a traceback
- Parameters:
tb (TracebackType) – traceback to extract the frame
- Returns:
bottom stack frame
- Return type:
frame
- satella.instrumentation.trace_back.trace_back.get_current_traceback()¶
A shorthand form for
Traceback().pretty_format()
.- Return type:
str
Module contents¶
- class satella.instrumentation.trace_back.GenerationPolicy(enable_pickling=True, compress_at=131072, repr_length_limit=131072, compression_level=6)¶
Bases:
object
A policy that manages generating a traceback
For a “default” policy it’s pretty customizable
Override if need be, and pass the class (or instance) to Traceback
- Parameters:
enable_pickling (bool) – bool, whether to enable pickling at all
compress_at (int) – pickles longer than this (bytes) will be compressed
repr_length_limit (int) – maximum p_len of __repr__. None for no limit.
compression_level (int) – “1” is fastest, “9” is slowest
- compress_at: int¶
- compression_level: int¶
- enable_pickling: bool¶
- get_compression_level(data_to_pickle)¶
What compression level to use to pickle this?
- Parameters:
data_to_pickle (bytes) – pickle value
- Returns:
int, 1-9, where “1” is the fastest, and “9” is the slowest, but produces best compression
- Return type:
int
- process_repr(r)¶
Process the string obtained from __repr__ing
- Parameters:
r (str) – result of a __repr__ on value
- Returns:
processed result
- Return type:
str
- repr_length_limit: int¶
- should_compress(pickle_data)¶
Should this pickle undergo compression?
- Parameters:
pickle_data (bytes) – pickle value
- Returns:
bool
- Return type:
bool
- should_pickle(value)¶
Should this value be pickled?
- Parameters:
value (Any) – value candidate
- Returns:
bool
- Return type:
bool
- class satella.instrumentation.trace_back.StackFrame(frame, policy)¶
Bases:
JSONAble
Class used to verily preserve stack frames. Picklable.
- Parameters:
frame (frame) –
policy (GenerationPolicy) –
- filename: str¶
- classmethod from_json(x)¶
- Parameters:
x (dict) –
- Return type:
- globals: Dict[str, StoredVariableValue]¶
- lineno: int¶
- locals: Dict[str, StoredVariableValue]¶
- name: str¶
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- class satella.instrumentation.trace_back.StoredVariableValue(value, policy=None)¶
Bases:
JSONAble
Class used to store a variable value. Picklable.
- Attributes are:
.repr - a text representation obtained using repr .typeinfo - a text representation of variable’s type .pickle - bytes with pickled (optionally processed) value, or None if
not available
- .pickle_type - what is stored in .pickle?
None - nothing “pickle” - normal Python pickle “pickle/gzip” - Python pickle treated with zlib.compress “failed” - could not pickle, pickle contains a UTF-8 text with
human-readable exception reason
- “failed/gzip” - compression failed, pickle contains a UTF-8 text with
human-readable exception reason
If value cannot be pickled, it’s repr will be at least preserved.
Note that the value itself won’t be preserved.
- Parameters:
value (Any) – any Python value to preserve
policy (Optional[GenerationPolicy]) – policy to use (instance)
- classmethod from_json(x)¶
- Parameters:
x (dict) –
- Return type:
- load_value()¶
Return the value that this represents.
WARNING! This may result in importing things from environment, as pickle.loads will be called.
- Returns:
stored value - if picklable and was pickled
- Raises:
ValueError – value has failed to be pickled or was never pickled
- pickle: bytes¶
- pickle_type: str¶
- repr: str¶
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- type_: str¶
- class satella.instrumentation.trace_back.Traceback(starting_frame=None, policy=<class 'satella.instrumentation.trace_back.classes.GenerationPolicy'>)¶
Bases:
JSONAble
- Class used to preserve exceptions and chains of stack frames.
Picklable.
If starting frame is not given, an exception must be in progress.
You can also convert it to a secure representation, ie. one that will be completely JSON and thus safe to load from untrusted sources. You will not lose the unpicklability of them by doing so, as they can be safely reconstructed (pickle will be encoded as base64 string).
- Parameters:
starting_frame (Optional[Union[Exception, frame]]) – frame to start tracking the traceback from. Must be either None, in which case an exception must be in progress and will be taken else must be an instance of <class ‘frame’>.
policy – policy for traceback generation
- Raises:
ValueError – there is no traceback to get info from! Is any exception in process?
- formatted_traceback¶
- frames: List[StackFrame]¶
- classmethod from_pickle(pick)¶
Load a traceback from a pickle
- Parameters:
pick (Union[BytesIO, bytes]) – either bytes or a BytesIO to load it from
- Returns:
previously serialized Traceback
- Raises:
ValueError – unserialized object is not a Traceback!
- Return type:
- pickle()¶
Returns this instance, pickled
- Return type:
bytes
- pickle_to(stream)¶
Pickle self to target stream
- Parameters:
stream (BinaryIO) –
- Return type:
None
- pretty_format()¶
Return a multi-line, pretty-printed representation of all exception data.
- Returns:
text
- Return type:
str
- pretty_print(output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)¶
Pretty-print the exception
- Parameters:
output (TextIO) – a file-like object in text mode
- Returns:
unicode
- Return type:
None
- to_json()¶
Return a JSON-able representation of this object
- Return type:
dict
- satella.instrumentation.trace_back.frame_from_traceback(tb)¶
Extract the bottom stack frame from a traceback
- Parameters:
tb (TracebackType) – traceback to extract the frame
- Returns:
bottom stack frame
- Return type:
frame
- satella.instrumentation.trace_back.get_current_traceback()¶
A shorthand form for
Traceback().pretty_format()
.- Return type:
str