satella.instrumentation package

Subpackages

Submodules

satella.instrumentation.dump_frames_on module

satella.instrumentation.dump_frames_on.dump_frames_on(sig_no=None, stack_frame=None, output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Dump all stack frames of all threads including the values of all the local variables.

Parameters:
  • sig_no (Optional[int]) – signal received. Default is None.

  • stack_frame (Optional[frame]) – Stack frame. Default is None.

  • output (TextIO) – output to print to. Default is stderr

Returns:

satella.instrumentation.dump_frames_on.install_dump_frames_on(signal_number, output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Instruct Python to dump all frames onto output, along with their local variables upon receiving given signal

Parameters:
  • signal_number (int) –

  • output (TextIO) –

Module contents

class satella.instrumentation.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.StackFrame(frame, policy)

Bases: JSONAble

Class used to verily preserve stack frames. Picklable.

Parameters:
filename: str
classmethod from_json(x)
Parameters:

x (dict) –

Return type:

StackFrame

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.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:

StoredVariableValue

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.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_json(x)
Parameters:

x (dict) –

Return type:

Traceback

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:

Traceback

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.dump_frames_on(sig_no=None, stack_frame=None, output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Dump all stack frames of all threads including the values of all the local variables.

Parameters:
  • sig_no (Optional[int]) – signal received. Default is None.

  • stack_frame (Optional[frame]) – Stack frame. Default is None.

  • output (TextIO) – output to print to. Default is stderr

Returns:

satella.instrumentation.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.get_current_traceback()

A shorthand form for Traceback().pretty_format().

Return type:

str

satella.instrumentation.install_dump_frames_on(signal_number, output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Instruct Python to dump all frames onto output, along with their local variables upon receiving given signal

Parameters:
  • signal_number (int) –

  • output (TextIO) –