Importing from SciPy#

In Python, the distinction between what is the public API of a library and whatare private implementation details is not always clear. Unlike in otherlanguages like Java, it is possible in Python to access “private” functions orobjects. Occasionally this may be convenient, but be aware that if you do soyour code may break without warning in future releases. Some widely understoodrules for what is and isn’t public in Python are:

• Methods / functions / classes and module attributes whose names begin with aleading underscore are private.

• If a class name begins with a leading underscore, none of its members arepublic, whether or not they begin with a leading underscore.

• If a module name in a package begins with a leading underscore none ofits members are public, whether or not they begin with a leading underscore.

• If a module or package defines__all__, that authoritatively defines thepublic interface.

• If a module or package doesn’t define__all__, then all names that don’tstart with a leading underscore are public.

In SciPy there are modules whose names don’t start with an underscore, but thatshould be considered private. To clarify which modules these are, we definebelow what the public API is for SciPy, and give some recommendations for howto import modules/functions/objects from SciPy.

Guidelines for importing functions from SciPy#

Everything in the namespaces of SciPy submodules is public. In general inPython, it is recommended to make use of namespaces. For example, thefunctioncurve_fit (defined inscipy/optimize/_minpack_py.py) should beimported like this:

importscipyresult=scipy.optimize.curve_fit(...)

Or alternatively one could use the submodule as a namespace like so:

fromscipyimportoptimizeresult=optimize.curve_fit(...)

In some cases, the public API is one level deeper. For example, thescipy.sparse.linalg module is public, and the functions it contains are notavailable in thescipy.sparse namespace. Sometimes it may result in moreeasily understandable code if functions are imported from one level deeper.For example, in the following it is immediately clear thatlomax is adistribution if the second form is chosen:

# first formfromscipyimportstatsstats.lomax(...)# second formfromscipy.statsimportdistributionsdistributions.lomax(...)

In that case, the second form can be chosenif it is documented in the nextsection that the submodule in question is public. Of course you can still use:

importscipyscipy.stats.lomax(...)# orscipy.stats.distributions.lomax(...)

API definition#

Every submodule listed below is public. That means that these submodules areunlikely to be renamed or changed in an incompatible way, and if that isnecessary, a deprecation warning will be raised for one SciPy release before thechange is made.

• scipy

• scipy.cluster

  • scipy.cluster.vq

  • scipy.cluster.hierarchy

• scipy.constants

• scipy.datasets

• scipy.differentiate

• scipy.fft

• scipy.fftpack

• scipy.integrate

• scipy.interpolate

• scipy.io

  • scipy.io.arff

  • scipy.io.matlab

  • scipy.io.wavfile

• scipy.linalg

  • scipy.linalg.blas

  • scipy.linalg.cython_blas

  • scipy.linalg.lapack

  • scipy.linalg.cython_lapack

  • scipy.linalg.interpolative

• scipy.ndimage

• scipy.odr

• scipy.optimize

  • scipy.optimize.cython_optimize

• scipy.signal

  • scipy.signal.windows

• scipy.sparse

  • scipy.sparse.linalg

  • scipy.sparse.csgraph

• scipy.spatial

  • scipy.spatial.distance

  • scipy.spatial.transform

• scipy.special

• scipy.stats

  • scipy.stats.contingency

  • scipy.stats.distributions

  • scipy.stats.mstats

  • scipy.stats.qmc

  • scipy.stats.sampling

SciPy structure#

All SciPy modules should follow the following conventions. In thefollowing, aSciPy module is defined as a Python package, sayyyy, that is located in the scipy/ directory.

• Ideally, each SciPy module should be as self-contained as possible.That is, it should have minimal dependencies on other packages ormodules. Even dependencies on other SciPy modules should be kept toa minimum. A dependency on NumPy is of course assumed.

• Directoryyyy/ contains:

  • A filemeson.build with build configuration for the submodule.

  • A directorytests/ that contains filestest_<name>.pycorresponding to modulesyyy/<name>{.py,.so,/}.

• Private modules should be prefixed with an underscore_,for instanceyyy/_somemodule.py.

• User-visible functions should have good documentation followingtheNumPy documentation style.

• The__init__.py of the module should contain the main referencedocumentation in its docstring. This is connected to the Sphinxdocumentation underdoc/ via Sphinx’s automodule directive.

  The reference documentation should first give a categorized list ofthe contents of the module usingautosummary:: directives, andafter that explain points essential for understanding the use of themodule.

  Tutorial-style documentation with extensive examples should beseparate and put underdoc/source/tutorial/.

See the existing SciPy submodules for guidance.