Warning

This project is being split into 3 separate projects:

  • friendly_traceback,

  • friendly, and

  • friendly_idle.

The documentation does not reflect this change.

If you are a end-user, just install friendly until further notice.

Todo

This is just a first draft that will need more work.

Why import *?

In many pages of this documentation, you will see that I suggest to use something like from friendly.X import *. This is often mentioned as being a bad practice, since it “pollutes” the current namespace with various names whose origin become difficult to trace.

If you have tried the friendly console, or read the previous pages in this documentation, you will have seen various useful functions such as what(), where(), why(), etc., which can be used in an interactive mode. You can think of these functions as useful additions to Python’s builtins, such as dir(), vars(), etc. These functions are meant to be used in interactive sessions.

The usual suggested alternatives to importing everything are the following:

  1. Import only what’s needed. For example:

    from friendly.X import what, where, why

  2. Import as a namespace; something like:

    from friendly import X
# or
import friendly.X as Y

One problem with the first suggestion is that friendly has many other functions that are potentially useful. So this might require another import statement, from friendly.X import something_else when wanting to use something_else. Trying to import all the possibly relevant functions by explicitly naming them in a single import statement is not really practical.

Using the second alternative means that, instead of simply writing why(), one might have to write something like X.why(). A potential problem with this second approach is that friendly.X might contain many other names, such as __path__, __spec__, etc., as well as other functions which are meant to be used only within module X which are not useful but would show up when doing something like dir(X) or help(X).

When creating a special module friendly.X for a specific environment, such as friendly.idle to be used with Python’s IDLE, I define __all__ so that only the relevant objects are imported when doing from friendly.X import *.

If you do not wish to do so, I suggest instead the following:

from friendly.X import Friendly
# or
from friendly.X import Friendly as some_other_name

Friendly is a special object which includes all the potentially useful functions as methods.

Warning

This might not be true. As I write this, Friendly does not include run, install, and possibly others.

By this, I mean that Friendly.why() is equivalent to writing why(). Friendly is also imported if you do from friendly.X import *.

As mentioned previously, [Friendly object], Friendly can be used to easily obtain a list of useful functions, without needing to consult the documentation.