"""

NumPy

=====

Provides

  1. An array object of arbitrary homogeneous items

  2. Fast mathematical operations over arrays

  3. Linear Algebra, Fourier Transforms, Random Number Generation

How to use the documentation

----------------------------

Documentation is available in two forms: docstrings provided

with the code, and a loose standing reference guide, available from

`the NumPy homepage <http://www.scipy.org>`_.

We recommend exploring the docstrings using

`IPython <http://ipython.scipy.org>`_, an advanced Python shell with

TAB-completion and introspection capabilities.  See below for further

instructions.

The docstring examples assume that `numpy` has been imported as `np`::

  >>> import numpy as np

Code snippets are indicated by three greater-than signs::

  >>> x = 42

  >>> x = x + 1

Use the built-in ``help`` function to view a function's docstring::

  >>> help(np.sort)

  ... # doctest: +SKIP

For some objects, ``np.info(obj)`` may provide additional help.  This is

particularly true if you see the line "Help on ufunc object:" at the top

of the help() page.  Ufuncs are implemented in C, not Python, for speed.

The native Python help() does not know how to view their help, but our

np.info() function does.

To search for documents containing a keyword, do::

  >>> np.lookfor('keyword')

  ... # doctest: +SKIP

General-purpose documents like a glossary and help on the basic concepts

of numpy are available under the ``doc`` sub-module::

  >>> from numpy import doc

  >>> help(doc)

  ... # doctest: +SKIP

Available subpackages

---------------------

doc

    Topical documentation on broadcasting, indexing, etc.

lib

    Basic functions used by several sub-packages.

random

    Core Random Tools

linalg

    Core Linear Algebra Tools

fft

    Core FFT routines

polynomial

    Polynomial tools

testing

    NumPy testing tools

f2py

    Fortran to Python Interface Generator.

distutils

    Enhancements to distutils with support for

    Fortran compilers support and more.

Utilities

---------

test

    Run numpy unittests

show_config

    Show numpy build configuration

dual

    Overwrite certain functions with high-performance Scipy tools

matlib

    Make everything matrices.

__version__

    NumPy version string

Viewing documentation using IPython

-----------------------------------

Start IPython with the NumPy profile (``ipython -p numpy``), which will

import `numpy` under the alias `np`.  Then, use the ``cpaste`` command to

paste examples into the shell.  To see which functions are available in

`numpy`, type ``np.<TAB>`` (where ``<TAB>`` refers to the TAB key), or use

``np.*cos*?<ENTER>`` (where ``<ENTER>`` refers to the ENTER key) to narrow

down the list.  To view the docstring for a function, use

``np.cos?<ENTER>`` (to view the docstring) and ``np.cos??<ENTER>`` (to view

the source code).

Copies vs. in-place operation

-----------------------------

Most of the functions in `numpy` return a copy of the array argument

(e.g., `np.sort`).  In-place versions of these functions are often

available as array methods, i.e. ``x = np.array([1,2,3]); x.sort()``.

Exceptions to this rule are documented.

"""

from __future__ import division, absolute_import, print_function

import sys

import warnings

from ._globals import ModuleDeprecationWarning, VisibleDeprecationWarning

from ._globals import _NoValue

# We first need to detect if we're being called as part of the numpy setup

# procedure itself in a reliable manner.

try:

    __NUMPY_SETUP__

except NameError:

    __NUMPY_SETUP__ = False

if __NUMPY_SETUP__:

    sys.stderr.write('Running from numpy source directory.\n')

else:

    try:

        from numpy.__config__ import show as show_config

    except ImportError:

        msg = """Error importing numpy: you should not try to import numpy from

        its source directory; please exit the numpy source tree, and relaunch

        your python interpreter from there."""

        raise ImportError(msg)

    from .version import git_revision as __git_revision__

    from .version import version as __version__

    from ._import_tools import PackageLoader

    def pkgload(*packages, **options):

        loader = PackageLoader(infunc=True)

        return loader(*packages, **options)

    from . import add_newdocs

    __all__ = ['add_newdocs',

               'ModuleDeprecationWarning',

               'VisibleDeprecationWarning']

    pkgload.__doc__ = PackageLoader.__call__.__doc__

    # We don't actually use this ourselves anymore, but I'm not 100% sure that

    # no-one else in the world is using it (though I hope not)

    from .testing import Tester, _numpy_tester

    test = _numpy_tester().test

    bench = _numpy_tester().bench

    # Allow distributors to run custom init code

    from . import _distributor_init

    from . import core

    from .core import *

    from . import compat

    from . import lib

    from .lib import *

    from . import linalg

    from . import fft

    from . import polynomial

    from . import random

    from . import ctypeslib

    from . import ma

    from . import matrixlib as _mat

    from .matrixlib import *

    from .compat import long

    # Make these accessible from numpy name-space

    # but not imported in from numpy import *

    if sys.version_info[0] >= 3:

        from builtins import bool, int, float, complex, object, str

        unicode = str

    else:

        from __builtin__ import bool, int, float, complex, object, unicode, str

    from .core import round, abs, max, min

    __all__.extend(['__version__', 'pkgload', 'PackageLoader',

               'show_config'])

    __all__.extend(core.__all__)

    __all__.extend(_mat.__all__)

    __all__.extend(lib.__all__)

    __all__.extend(['linalg', 'fft', 'random', 'ctypeslib', 'ma'])

    # Filter annoying Cython warnings that serve no good purpose.

    warnings.filterwarnings("ignore", message="numpy.dtype size changed")

    warnings.filterwarnings("ignore", message="numpy.ufunc size changed")

    warnings.filterwarnings("ignore", message="numpy.ndarray size changed")

    # oldnumeric and numarray were removed in 1.9. In case some packages import

    # but do not use them, we define them here for backward compatibility.

    oldnumeric = 'removed'

    numarray = 'removed'