Standard import hints

[jarrodmillman]

The following are standard import conventions for scientific Python packages:

import numpy as np
import scipy as sp
import matplotlib as mpl
import matplotlib.pyplot as plt
import pandas as pd
import networkx as nx

Recently in https://github.com/scipy/scipy/issues/13049 the question arose whether to assume these import conventions in docstring examples made sense in a cut and paste scenario. Even if we make everything "self-contained" in the docstrings, it is still reasonable to think that there will be little code snippets online that will potentially assume these conventions.

Would it be reasonable to add a suggestion for these (and maybe a few others) so that you got a Hint: something like this:

(nx) [jarrod@x15 ~]$ ipython
Python 3.9.9 (main, Nov 19 2021, 00:00:00)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.4.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: sequence = nx.random_powerlaw_tree_sequence(100, tries=5000)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [1], in <cell line: 1>()
----> 1 sequence = nx.random_powerlaw_tree_sequence(100, tries=5000)

NameError: name 'nx' is not defined

Hint: If you are using NetworkX, try `import networkx as nx` first

In [2]:

[MrMino]

I think it's ok to do that as long as the necessary changes aren't invasive/complex/hacky. I myself don't have much interest in it, but I'd be happy to review a PR that adds this.

[suzaku]

This behavior might be confusing to new developers working on non-scipy related domains if they happen to fail on one of the shorten names. Adding the necessary imports in the original document makes more sense to me. For example, the API reference of requests include import requests in every example. People following the documentation might not be using IPython, and if the document has a chance to instruct the user to use IPython, it can also introduce a profile that can automatically import those names.