DOC: consistent imports ('import pandas as pd' et al)

[jorisvandenbossche]

Throughout the docs, many different imports are used, not always visible to the reader. And ideally, I think this would be a bit more uniform. I think we need:

• consistent imports
• visible imports

So the code snippets can be ran without having to know what should be imported, apart from the default imports.
But in that case, of course, we have to decide/agree on which imports to use.

---

I think import pandas as pd is regarded as recommended? But still, it is not used that much in the docs. So I was wondering, does everybody agree to use that in all docs (and is it just a case of "it is the intention, but no one did it")?
So everywhere pd.DataFrame and pd.Series, or do we still want the convenience of using DataFrame(..)/Series(..) without the pd (so to only from pandas import DataFrame, Series, and use pd. for all the rest)?

So: Question 1: do we use import pandas as pd for everything or not?

---

Then we have the often used imports from other packages. I think this is standard, and should not need discussion:

import numpy as np
import matplotlib.pyplot as plt

But for the datetime package, the imports are not really uniform. The following two imports are both used mixed in the docs, but are not compatible with each other:

import datetime
from datetime import datetime

So: Question 2: How do we import datetime?

Further, there are some other imports used a lot, like from numpy.random import randn or from numpy import nan.

For other non-pandas imports, I propose that they should always use the standard import (eg np) or be done explicitely where used, and never hidden (as it is now the case sometimes, eg from dateutil.relativedelta import relativedelta)

So: Question 3: Do we agree that all other non-pandas imports should be done explicitely?

This means that imports in the suppressed code block like the following will be removed:

from numpy import nan
randn = np.random.randn
randint = np.random.randint
from dateutil.relativedelta import relativedelta
import random
import os
import csv

---

Third issue: there are also some pandas imports of non top-level things.

For pandas submodules, imports like this appear in the docs:

from pandas.tseries.api import *
from pandas.tseries.offsets import *

from pandas.core.reshape import *
from pandas.tools.tile import *

happen in the docs (and often not visible to the users), what I think is a bad idea. First, a lot of these imports should never been done as the functions used from there are also in the top-level pandas namespace.

If it is for functions that are used from the submodules, that we have to decide how to import them. At least, the imports should happen explicitely in the visible docs. But to do that, there are some different forms possible:

from pandas.tseries.offsets import *
... BMonthEnd()
... Day()

from pandas.tseries.offsets import BMonthEnd, Day
... BMonthEnd()
... Day()

import pandas.tseries.offsets as offsets (or from pandas.tseries import offsets)
... offsets.BMonthEnd()
... offsets.Day()

So: Question 4: How do we import from pandas submodules?

TO DO:

• Decide on the imports (see questions above)
• Clearly document this in the contributor guidelines
• Adapt this in the documentation

[jorisvandenbossche]

@jreback @shoyer @TomAugspurger @sinhrks What do you think about this?

[shoyer]

I think we agree here.

1. Yes, we should use import pandas as pd for everything.
2. I don't think this matters so much, as long we're explicit
3. Yes, though I would probably allow for omitting import numpy as np as well.
4. We should import explicitly, never with * (like we encourage users to do)

[jreback]

agree with @shoyer here.

I would prob show import numpy as np as well

should show esp in 10min to pandas. Not really concerned about in the docs itself, but I guess it could be a bit unclear.

Are you proposing prefixing all calls with pd.? e.g.

pd.Series, pd.date_range etc...?

[jorisvandenbossche]

@shoyer On question 3: yes indeed, apart from pd, I would propose that also np and plt are assumed and do not have to be imported explicitely (or only once at the top).

@jreback Yes, indeed: pd.Series, pd.DataFrame, pd.date_range -> that is the consequence of saying "Yes, we should use import pandas as pd for everyting" (see question 1 for more details)
But that is the reason I asked, as we don't do this at the moment, so it has quite an impact.

[jreback]

I think that might be a bit too far. I would be +1 on this for 10min to pandas. But IMHO just clutters the docs otherwise. and we don't do it ANYWHERE IIRC.

[TomAugspurger]

1. always import pandas as pd even for pd.Series, pd.DataFrame
2. I always use import datetime, but as long as we're consistent
3. Explicit imports for sure. We have

In [1]: import pandas as pd

In [2]: import numpy as np

In [3]: import matplotlib.pyplot as plt

at the start of the 10 minute intro. I think that's ok. All others should imported (and shown to be imported), say once per section? We shouldn't assume people are reading the docs straight through.
4. Make the submodule imports visible and don't use *

So I think I'm agreeing with @jorisvandenbossche and @shoyer here.

[sinhrks]

+1 for @shoyer and @TomAugspurger . And I prefer import datetime also, because I feel datetime.datetime and datetime.timedelta are more explicit.

[jorisvandenbossche]

@jreback That's the reason I brought it up, as now we don't do this, although recommend it. But I think we should be consistent in the first place. If we recommend it, we should do it ourselves. If we do it in 10min, we should do it in all the docs, although this is more verbose.
Otherwise we should change our recommendation to from pandas import Series, DataFrame; import pandas as pd (but I am not really a proponent of that)

[jorisvandenbossche]

For question 4, anybody a preference out of those two?

from pandas.tseries.offsets import BMonthEnd, Day
... BMonthEnd()
... Day()

import pandas.tseries.offsets as offsets (or from pandas.tseries import offsets)
... offsets.BMonthEnd()
... offsets.Day()

[jorisvandenbossche]

I started with some files, see #9987 (long train rit today :-)), so that is what it would look like if I follow the above.

[jorisvandenbossche]

Most is done, overview of the files that still need updates:

• merging.rst (only randn)
• timedeltas.rst (the non pd imports: offsets, datetime, pytz, ..)
• timeseries.rst (same)

[ghost]

I'ld like to work on this, for the above files: merging.rst timedeltsd.rst and timeseries.rst

[mroeschke]

Looks like the remaining files in #9886 (comment) have consistent import styles now. Going to close out this issue but happy to reopen if we re-catch inconsistent imports in the references.