[AstroPy] astropy docs: importing standards

Joe Harrington jh at physics.ucf.edu
Tue Jun 19 13:57:16 EDT 2012

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 we don't need to 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.  I propose that we skip the arduous debates
those communities went through and just adopt their solution by defining
some importation standards:

import astropy as ap
import astropy.io as api
import astropy.io.fits as apif

... and fix the docs to use these consistently.  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.

There are other abbreviations we could use, including:

import astropy.io.fits as pf
import astropy.io.fits as pyfits

since many already do:

import pyfits as pf
import pyfits

...and the same for pywcs.  What exact abbreviations we choose are less
important than that we choose them and always use them.  The result
otherwise is bugs and other suffering as code gets shared from place to
place and breaks.


Prof. Joe Harrington
Planetary Sciences Group
Department of Physics
University of Central Florida
Orlando, FL 32816-2385
jh at physics.ucf.edu

More information about the AstroPy mailing list