fedeclaudi / pyinspect

find functions when you can't remember their name

pyinspect - the python package for lazy programmers

Don't remember a function's name? Use pyinspect to look for it.
Don't remember what a function does? Use pyinspect to print its source code directly to your terminal.
Can't figure out why you keep getting an error? Use pyinspect's fancy tracebacks to figure it out
Still can't figure it out, but too lazy to google it? Use pyinspect to print Stack Overflow's top answer for your error message directly to your terminal!

... and a bunch of other features to make your life easier when coding.

An example of how `pyinspect` can be used to find and inspect functions lazily.

Table of Contents

1. Installing pyinspect
2. When you can't remember a variable's name...
3. When you can't remember a function's name...
4. When you can't remember what a function does
5. When you can't fix that bug...
6. When you still can't fix that bug...
7. When you got a question, ask Google
8. When you...

Installing pyinspect

It's as simple as:

pip install pyinspect

When you can't remember a variable's name..

Allright, you've defined a bunch of variables and now can't remember the name or content of the one you need. Fear not, becuse you can use pyinspect to print all variables in your local scope:

    import pyinspect as pi

    a = 'my variable'
    b = 'another variable'

    pi.what()  # print all local variables

or to look at a single variable in detail with:

    my_favourite_number = 21
    pi.what(a)

This will show you the variable content, where it has been defined and some of its attributes and methods. Something like:

When you can't remember a function's name...

That's okay! You can use pyinspect to search for a function by its name! E.g. to look for functions with searc in their name in pyinspect:

# import pyinspect
import pyinspect as pi

# Find the functions you're looking for
pi.search(pi, name='what')

This results in a table with all the function's matching your search name:

note: search also looks for functions in sub-modules of the module given. e.g. search(matplotlib, 'plot') will look for methods across the entire matplotlib library!

pyinspect.find can also be used to find class methods. For example to look for a method with export in the name in rich.console.Console:

pi.search(Console, 'export')

note: search also looks for methods matching your query among the parents of the class you passed. Use include_parents=False when calling search to restrict the search to just the class you've passed. Methods of the parent class are highlighted in a different color!

PRO TIP: if you don't pass a search name to pyinspect.search (e.g. pyinspect.find(Console)), pyinspect.search will print all functions and methods.

When you can't remember what a function does

Okay, you've found the function you need, that's great. But how does it work? You could openthe file where it's defined, scroll down to it etc... but this pyinspect, the package for lazy programmers! Instead of going thruogh that hastle why not printing the function's code directly to your terminal with a simple command:

# import pyinspect
import pyinspect as pi

# Look at how pyinspect.search works
pi.showme(pi.search)

which yields:

When you can't fix that bug...

Sometimes you know what's causing an error, sometimes you don't. When you don't, it helps to know what the variables involved in the error are, possibly without having to go through the extra work of debugging stuff!

Once again pyinspect has a labour-saving solution: an advanced traceback functionality that gives you all the information you need to fix your bug (hopefully!). Just install pyinspect's traceback at the start of your script: when get an error you'll get a helpful summary of what's going on with your code!

E.g.:

# import pyinspect and install the traceback handler
import pyinspect as pi

pi.install_traceback()  # use hide_locals=True to hide locals panels from your traceback

# make some buggy code
import numpy as np

a = np.ones(5)
b = "ignore this"  # a local variable not being used
c = np.zeros(4)  # ooops, wrong size

a + c  # this will give an error

and this is the traceback:

note: although we defined three variables (a, b, c) only two where in the line causing the error (a + c). pyinspect then highlights a and c in the traceback as this is what you need to know to fix your bug. If you want pyinspect to only show the variables in the error line pass relevant_only=True to pi.install_traceback()

pro tips:

• if you want to show all items in the local scope (e.g. also imported modules, not just variables) then you can use all_locals=True in pi.install_traceback()
• if you don't want the locals to be shown at all, then use hide_locals=True
• if you want more or less extensive tracebacks, you can use keep_frames to decide how many frames to shown in nested tracebacks (i.e when a function a calls a function b and the error comes up in b, do you want to see only the locals in b or in a and b?)

When you still can't fix that bug...

Time to do what any real programmer does in this situation... google it / copy-paste an answer from Stack Overflow. But that involves pulling up your browser, opening a new tab, typing stuf... too much work!

When an error comes up, pyinspect gives you the opportunity to automate this work away by doing the googling for you. You can do that in two ways:

1. passing enable_prompt=True to install_traceback: after the error traceback a prompt will come up asking if you want to look for solutions online, type y.
2. In a terminal window use the why command and pyinspect will automatically lookup solutions to the last error you've had [note you need to have installed pyinspect's tracebacks for it to record errors].

Either way, you get 3 things:

• A description of your error
• Links to the top 3 results on Google
• A neat render of a Stack Overflow question and answer related to your error.

Check it out:

When you got a question, ask Google

Ever found yourself googling the same basic command over and over because you keep forgetting what the syntax is? If you do (and I know you do), or if you have any other question, now you can look for answers directly in python with pynspect.ask. Using it is fairly simple:

pi.ask("python Concatenate two lists?")

note: you can also use ask in your terminal to lookup answers to your questions. E.g.:

ask "Python how to concatenate strings"

When you...

pyinspect has a few more useful little features you might find yourself using from time to time. One of our favourites is panels: a simple why to print neat messages to terminal, for when you need to communicate with your users.

import pyinspect as pi


pi.warn('This is a warning', 'Ooops, something might be wrong!')


pi.ok('You got this!', 'Panels are simple, but nice. Checkout `pyinspect.panels` to see what other kind of panels there are!')

You can also use Report, a more advanced panel which allows you to create a more structured and detailed panel (see pi.whats_pi()):

As an example, see how I've used Report to render my CV

Contributing

Contributions are welcome! Start a pull request if you have a change you'd like to submit or open an issue to report a bug or request a new feature to be added to pyinspect

Aknowledgements

pyinspect is mostly a thin wrapper on top of the awesome rich library, so a huge thank you goes to @willmcgugan for the great job done with rich.

pyinspect's Issues

Broader function search

Currently pyinspect.search looks for a function only in a given module. For instance if rich is passed, it will effectively only look into rich.__init__, but what if we want to look for a function in the whole package (e.g. find functions in rich.console, rich.traceback... )?

pyinspect.find.find_module_function should be endowed with the power to recursively inspect all sub modules of the given module.

The outcome of this should be reflected in the summary table.

traceback: highlight part of line causing problems

See suggestions here.
Use executing to identify the part of the error line causing problems and highlight it in the traceback.

Minimum rich version requirement

Specify minimum rich version requirement to prevent
ImportError: cannot import name 'inspect' from 'rich' (C:\Users\lpetrucco\AppData\Roaming\Python\Python37\site-packages\rich_init_.py)

Improved testing

Currently most testing just involves running stuff and hoping than no errors come up.

That's good bu t it would be better to do something like rich which captures the console output and matches it to pre-defined strings.

This can be done by using pyinspect._rich.console (which will be released when dev is merged) and replace it with a Console recording the output to a io.StringIO object.

traceback should ignore modules and other possibly confusing stuff

The default of the traceback locals should be to show only variables. Functions, classes and methods should be optional to reduce unnecessary overhead.

Truncate tracebacks

When there's a lot of nested frames tracebacks can be too long, add an option to truncate long tracebacks, and make sure error is always visible.

Improved traceback -> locals inspection

When printing locals, it'd be good to add information that the user is likely to need. For instance, variables that are np.ndarray could come with the shape, list object with their length etc...

exceptions.print_exception should show a `local` panel similar to tracebacks

Currently print_exception shows the locals panel as shown by rich.scope.render_scope, but it should show something more similar to what comes up with exceptions raise by pi.install_traceback() for consistency across the package.

update README

README is outdated

search function in module finds duplicates

e.g. search(brianrender, 'color') finds colorMap` multiple times (in modules that import it).
It also returns variables, not just functions!

add tests and coverage report

`print_function` should handle class methods better

print_function should detect which class the method came from and print some info about the class as well.

Release to pypi including requests requirement

import pyinspect leads to ModuleNotFoundError: No module named 'requests'. requests is listed in setup.py here but not in the files on https://pypi.org/project/pyinspect/#files

_get_type_info TypeError for some arrays

In _exceptions._get_type_info, if the obj passed is a numpy array but not one with numbers as elements (e.g. an array of matplotlib axes, the info part gives errors.

Fix and cover in testing.

[New Feature] Nested Report

Add a new Report class to more easily add nested reports to achieve this kind of look:

See how it's implemented in my CV

Additionally: add option to remove info from Report's print