howigothere 1.1.0

Python module to create a condensed stack preview

HowIGotHere

A package containing a single function howigothere that returns a condensed stack preview. Useful for debugging to easily trace how some call was made, even through a jungle of calls made by frameworks and other packages.

To see it in action, you can run example.py or, if you didn't install the package but you only downloaded this repository, ./try_me.sh example.py. Both approaches require that settings-collector is installed. The result should look like this:

Content

1. The name
2. Usage
3. Global setup
4. Local setup

The name

The name of the package is "How I Got Here?". If your question is "How I Go There?", wherever "there" might be, you'll need to ask some other package.

Usage

Make an import:

from howigothere import howigothere

and then call

print(howigothere())  # or logger.debug(howigothere())

somewhere in your code.

Global setup

This package relies on settings-collector to collect settings from various frameworks. This means that you can set it up through standard mechanisms of the framework used by your project.

For example, if you are using Django, you can set the separator colour by defining HOWIGOTHERE__COLOR_SEP (note two underscores before COLOR, but only one after it) in your Django settings. The frameworks' settings character casing is respected, so - for example - in TurboGears this will be howigothere__color_sep

If you don't use a framework (or, at least, not one supported by settings-collector), you can also use sc_settings (settings-collector's dict-like equivalent of frameworks' configs) and do something this:

from settings_collector import sc_settings

sc_settings["howigothere__color_sep"] = colorama.Fore.RED

For more details, please see the documentation of settings-collector.

If the setup (either in sc_settings or in framework's settings) contains settings-collector's scopes, you can specify the scope to use like this:

howigothere(namespace="some_scope")

Local setup

Lastly, you can also configure values when calling the function. For example,

howigothere(color_sep=colorama.Fore.RED)

Here is the list of all arguments accepted by the function. All but namespace are also available in sc_settings and frameworks' settings. The default values are as shown, unless overridden in sc_settings or framework's setup.

• namespace [default: None]: If set, it is used as scope identifier in settings_collector.
• keep_dirs [default: 1]: The number of directories to keep in output (None to keep them all). For example, if set to 2, path /a/b/c/d/e/f.py will be displayed as d/e/f.py. This is to reduce the output while still being able to distinguish between files with the same name.
• sep [default: " > "]: Separator between calls.
• call_format [default: "{function} ({path}:{lineno})"]: The format of each call.
• no_color [default: False]: If set to True, colours won't be used even if they are properly defined. This is useful if you want to have properly coloured printouts most of the times, but you sometimes want to add these to some logging system that doesn't support your preferred way of colouring text.
• start_from_dir [default: None]: If set, output is suppressed until the first file having start_from_dir as its parent. This can also be a tuple of strings, in which case encountering any of them starts the output.

To add to those, colours can also be redefined. Their defaults depend on the presence of colorama package (if it's not there, these are all empty strings by default). The displayed defaults assume that colorama is installed and that its Fore and Style constants are imported.

• color_reset [default: Style.RESET_ALL]: This is added to the end of each colourisable chunk (separator, function name, etc.).
• color_sep [default: "", i.e., no colouring]: The colour used for the separators between calls.
• color_func[ default: Style.BRIGHT + Fore.GREEN]: The colour used for functions' names in each call.
• color_path [default: Style.BRIGHT + Fore.CYAN]: The colour used for path of the each file containing called functions.
• color_lineno [default: Fore.CYAN]: The colour used for the line numbers where calls were made.

There is also support for showing arguments to calls in the stack, turned off by default for backwards compatibility. The arguments controlling this are:

• show_args [default: False]: A switch determining if the arguments should be shown or not.
• color_arg_name [default: Style.BRIGHT + Fore.BLUE]: The colour used for arguments' names.
• color_arg_eq [default: Style.BRIGHT + Fore.GREEN]: The colour used for the equality sign between arguments' names and values.
• color_arg_value [default: Style.BRIGHT + Fore.YELLOW]: The colour used for arguments' values.