GitLocker: The Coding Marketplace

Description:

howigothere 1.1.0

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

The name
Usage
Global setup
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.