Ticket Navigation

Ticket #86 (new enhancement)

Opened 2 years ago

Last modified 2 years ago

use api.py

Reported by:	jarrod.millman	Assigned to:	jarrod.millman
Priority:	normal	Milestone:	0.1.4
Component:	general	Version:
Severity:	normal	Keywords:	api
Cc:

Description

Each NIPY subpackage should include an api.py module that exports its API classes, functions, constants, and interfaces. This has several benefits:

Helps distinguish between the public and private portions of our code, since api.py is an obvious choice to look at when browsing a package to see what it has to offer.
Putting imports in __init__.py files means that anyone who tries to use something from the package will have perform all the imports.
Packaging and code organization is made easier when using setuptools if the __init__.py is essentially empty. In particular, if we want to distribute NIPY as a collection of smaller eggs (e.g., an FMRI egg, a SPECT egg, an EEG egg) we can use Namespace Packages, which requires that __init__.py has no meaningful data.
It is a convention gaining widespread adoption including, for example, enthought, peak, trac, zope.

In practive this should enable us to have shorter, more intuitive paths to frequently used things. For example, rather than

from neuroimaging.core.image.image import Image

we might write

from neuroimaging.core.api import Image

Change History

02/09/07 03:53:56 changed by jarrod.millman

In [1503], I created lib/neuroimaging/core/api.py with the following contents:

"""
Pseudo-package for all of the core symbols from the image object and its reference
system.  Use this module for importing core names into your namespace. For example:
from neuorimaging.core.api import Image
"""

from neuroimaging.core.image.image import Image, ImageSequenceIterator
from neuroimaging.core.reference.grid import SamplingGrid
from neuroimaging.core.reference.iterators import SliceIterator, \
     SliceParcelIterator, ParcelIterator, fMRIParcelterator
from neuroimaging.core.reference.mapping import Mapping, Affine

I decided to include just thess names for now, since they were the only names that were used outside neuroimaging.core in any real way. I think we should keep these files relatively small and the names we import few.

Download in other formats: