astropy/astropy — pull request #298 by astrofrog (2012-12-11 15:13:33+00:00)
Title: importing standards needed

The numpy and scipy communities wrestled with the issue of importing into the top level and decided it was poor practice, for a variety of reasons I won't rehash here. Hence, there is the standard "import numpy as np" and its friends. In the astropy docs, however, there is a lot of importing into the top level. Usually this is just single functions, but it breaks when you try to get example code to work in your own function, where you imported all of astropy and need to say "astropy." before each call.

Most important is the standard that we NEVER import * into the top level, since future versions could include names that conflict with standard Python names. Then, provide a standard way to import each module (and the top level if there are useful things there). These might include:

import astropy as ap

for the top level. Some names will require thought. It was suggested on the mailing list that we NOT:

import astropy.io as api

since "API" is already a standard abbreviation and this might cause confusion. Also,

import astropy.io.fits as fits

would be a clean standard. However, given the history of pyfits,

import astropy.io.fits as pyfits

would be seamless for a lot of existing code. A decision is needed between the two and should include input from the pyfits maintainers and from anyone with code that must be long-term stable.

Given the large number of modules contemplated, a help() page giving the importation standard should be created:
help(astropy.import)

--jh--