diff options
Diffstat (limited to 'doc')
43 files changed, 1899 insertions, 554 deletions
diff --git a/doc/HOWTO_BUILD_DOCS.txt b/doc/HOWTO_BUILD_DOCS.txt index fd058d9bd..8c1722712 100644 --- a/doc/HOWTO_BUILD_DOCS.txt +++ b/doc/HOWTO_BUILD_DOCS.txt @@ -2,70 +2,97 @@ Building the NumPy API and reference docs ========================================= -Using Sphinx_ -------------- -`Download <https://code.launchpad.net/~stefanv/scipy/numpy-refguide>`_ -the builder. Follow the instructions in ``README.txt``. +We currently use Sphinx_ for generating the API and reference +documentation for Numpy. You will need Sphinx 0.5 or newer. Sphinx's +current development version also works as of now (2009-06-24), and +using it is recommended though not required. +If you only want to get the documentation, note that pre-built +versions can be found at -Using Epydoc_ -------------- + http://docs.scipy.org/ -Currently, we recommend that you build epydoc from the trunk:: +in several different formats. - svn co https://epydoc.svn.sf.net/svnroot/epydoc/trunk/epydoc epydoc - cd epydoc/src - sudo python setup.py install +.. _Sphinx: http://sphinx.pocoo.org -The appearance of some elements can be changed in the epydoc.css -style sheet. -Emphasized text appearance can be controlled by the definition of the <em> -tag. For instance, to make them bold, insert:: +Instructions +------------ - em {font-weight: bold;} +Since large parts of the main documentation are stored in +docstrings, you will need to first build Numpy, and install it so +that the correct version is imported by -The variables' types are in a span of class rst-classifier, hence can be -changed by inserting something like:: + >>> import numpy - span.rst-classifier {font-weight: normal;} +Note that you can eg. install Numpy to a temporary location and set +the PYTHONPATH environment variable appropriately. Also note that if +you have a system Numpy installed via Python eggs, you will also need +to use ``setupegg.py`` to install the temporary Numpy. -The first line of the signature should **not** copy the signature unless -the function is written in C, in which case it is mandatory. If the function -signature is generic (uses ``*args`` or ``**kwds``), then a function signature -may be included. +After Numpy is installed, write:: -Use optional in the "type" field for parameters that are non-keyword -optional for C-functions. + make html -Epydoc depends on Docutils for reStructuredText parsing. You can -download Docutils from the `Docutils sourceforge -page. <http://docutils.sourceforge.net/>`_. The version in SVN is -broken, so use 0.4 or the patched version from Debian. You may also -be able to use a package manager like yum to install it:: +in this ``doc/`` directory. If all goes well, this will generate a +``build/html`` subdirectory containing the built documentation. Note +that building the documentation on Windows is currently not actively +supported, though it should be possible. (See Sphinx_ documentation +for more information.) - $ sudo yum install python-docutils +To build the PDF documentation, do instead:: + make latex + make -C build/latex all-pdf -Example -------- -Here is a short example module, -`plain text <http://svn.scipy.org/svn/numpy/trunk/doc/example.py>`_ -or -`rendered <http://www.scipy.org/doc/example>`_ in HTML. +You will need to have Latex installed for this. -To try this yourself, simply download the example.py:: +In addition to the above, you can also do:: - svn co http://svn.scipy.org/svn/numpy/trunk/doc/example.py . + make dist -Then, run epydoc:: +which will rebuild Numpy, install it to a temporary location, and +build the documentation in all formats. This will most likely again +only work on Unix platforms. - $ epydoc --docformat=restructuredtext example.py -The output is placed in ``./html``, and may be viewed by loading the -``index.html`` file into your browser. +Sphinx extensions +----------------- +Numpy's documentation uses several custom extensions to Sphinx. These +are shipped in the ``sphinxext/`` directory, and are automatically +enabled when building Numpy's documentation. +However, if you want to make use of these extensions in third-party +projects, they are available on PyPi_ as the numpydoc_ package, and +can be installed with:: -.. _epydoc: http://epydoc.sourceforge.net/ -.. _sphinx: http://sphinx.pocoo.org + easy_install numpydoc + +In addition, you will need to add:: + + extensions = ['numpydoc'] + +to ``conf.py`` in your Sphinx documentation. + +The following extensions are available: + + - ``numpydoc``: support for Numpy docstring format in Sphinx. + + - ``numpydoc.only_directives``: (DEPRECATED) + + - ``numpydoc.plot_directives``: Adaptation of Matplotlib's ``plot::`` + directive. Note that this implementation may still undergo severe + changes or be eventually deprecated. + + - ``numpydoc.autosummary``: (DEPRECATED) An ``autosummary::`` directive. + Available in Sphinx 0.6.2 and (to-be) 1.0 as ``sphinx.ext.autosummary``, + and it the Sphinx 1.0 version is recommended over that included in + Numpydoc. + + - ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes. + + +.. _PyPi: http://python.org/pypi +.. _numpydoc: http://python.org/pypi/numpydoc diff --git a/doc/HOWTO_DOCUMENT.txt b/doc/HOWTO_DOCUMENT.txt index 1cea22f1f..efe731ff7 100644 --- a/doc/HOWTO_DOCUMENT.txt +++ b/doc/HOWTO_DOCUMENT.txt @@ -61,12 +61,12 @@ docstrings that provides for consistency, while also allowing our toolchain to produce well-formatted reference guides. This document describes the current community consensus for such a standard. If you have suggestions for improvements, post them on the `numpy-discussion -list`_, together with the epydoc output. +list`_. Our docstring standard uses `re-structured text (reST) <http://docutils.sourceforge.net/rst.html>`_ syntax and is rendered -using tools like epydoc_ or sphinx_ (pre-processors that understand -the particular documentation style we are using). While a rich set of +using Sphinx_ (a pre-processor that understands the particular +documentation style we are using). While a rich set of markup is available, we limit ourselves to a very basic subset, in order to provide docstrings that are easy to read on text-only terminals. @@ -74,15 +74,18 @@ terminals. A guiding principle is that human readers of the text are given precedence over contorting docstrings so our tools produce nice output. Rather than sacrificing the readability of the docstrings, we -have written pre-processors to assist tools like epydoc_ and sphinx_ in -their task. +have written pre-processors to assist Sphinx_ in its task. + +The length of docstring lines should be kept to 75 characters to +facilitate reading the docstrings in text terminals. Status ------ We are busy converting existing docstrings to the new format, expanding them where they are lacking, as well as writing new ones for undocumented functions. Volunteers are welcome to join the effort on -our new documentation system (see the `Developer Zone +our new documentation system (see the `Documentation Editor +<http://docs.scipy.org/doc/>`_ and the `Developer Zone <http://www.scipy.org/Developer_Zone/DocMarathon2008>`_). Sections @@ -96,7 +99,7 @@ The sections of the docstring are: :: - def add(a,b): + def add(a, b): """The sum of two numbers. """ @@ -107,7 +110,7 @@ The sections of the docstring are: it as the first line of the docstring:: """ - add(a,b) + add(a, b) The sum of two numbers. @@ -147,11 +150,17 @@ The sections of the docstring are: over all axes). When a parameter can only assume one of a fixed set of values, - those values can be listed in braces :: + those values can be listed in braces:: x : {True, False} Description of `x`. + When two or more input parameters have exactly the same type, shape and + description, they can be combined:: + + x1, x2 : array_like + Input arrays, description of `x1`, `x2`. + 4. **Returns** Explanation of the returned values and their types, of the same @@ -173,6 +182,9 @@ The sections of the docstring are: LinAlgException If the matrix is not numerically invertible. + This section should be used judiciously, i.e only for errors + that are non-obvious or have a large chance of getting raised. + 7. **See Also** An optional section used to refer to related code. This section @@ -203,7 +215,8 @@ The sections of the docstring are: scipy.random.norm : Random variates, PDFs, etc. - Functions may be listed without descriptions:: + Functions may be listed without descriptions, and this is + preferable if the functionality is clear from the function name:: See Also -------- @@ -286,59 +299,39 @@ The sections of the docstring are: 10. **Examples** - An optional section for examples, using the `doctest - <http://www.python.org/doc/lib/module-doctest.html>`_ format. - This section is meant to illustrate usage, not to provide a - testing framework -- for that, use the ``tests/`` directory. - While optional, this section is very strongly encouraged. You can - run these examples by doing:: - - >>> import doctest - >>> doctest.testfile('example.py') - - or, using nose, - - :: - - $ nosetests --with-doctest example.py + An optional section for examples, using the `doctest + <http://www.python.org/doc/lib/module-doctest.html>`_ format. + This section is meant to illustrate usage, not to provide a + testing framework -- for that, use the ``tests/`` directory. + While optional, this section is very strongly encouraged. - Blank lines are used to seperate doctests. When they occur in the - expected output, they should be replaced by ``<BLANKLINE>`` (see - `doctest options - <http://docs.python.org/lib/doctest-options.html>`_ for other such - special strings), e.g. + When multiple examples are provided, they should be separated by + blank lines. Comments explaining the examples should have blank + lines both above and below them:: - :: + >>> np.add(1, 2) + 3 - >>> print "a\n\nb" - a - <BLANKLINE> - b + Comment explaining the second example - The examples may assume that ``import numpy as np`` is executed before - the example code in *numpy*, and ``import scipy as sp`` in *scipy*. - Additional examples may make use of *matplotlib* for plotting, but should - import it explicitly, e.g., ``import matplotlib.pyplot as plt``. + >>> np.add([1, 2], [3, 4]) + array([4, 6]) -11. **Indexing tags*** + You can run examples using:: - Each function needs to be categorised for indexing purposes. Use - the ``index`` directive:: + >>> np.test(doctests=True) - .. index:: - :refguide: ufunc, trigonometry + It is not necessary to use the doctest markup ``<BLANKLINE>`` to + indicate empty lines in the output. Note that the option to run + the examples through ``numpy.test`` is provided for checking if the + examples work, not for making the examples part of the testing framework. - To index a function as a sub-category of a class, separate index - entries by a colon, e.g. - - :: - - :refguide: ufunc, numpy:reshape, other - - A `list of available categories - <http://www.scipy.org/Developer_Zone/ReferenceGuide>`_ is - available. + The examples may assume that ``import numpy as np`` is executed before + the example code in *numpy*, and ``import scipy as sp`` in *scipy*. + Additional examples may make use of *matplotlib* for plotting, but should + import it explicitly, e.g., ``import matplotlib.pyplot as plt``. + Documenting classes ------------------- @@ -346,9 +339,11 @@ Class docstring ``````````````` Use the same sections as outlined above (all except ``Returns`` are applicable). The constructor (``__init__``) should also be documented -here. +here, the **parameters** section of the docstring details the constructors +parameters. -An ``Attributes`` section may be used to describe class variables:: +An ``Attributes`` section, located below the **parameters** section, +may be used to describe class variables:: Attributes ---------- @@ -357,6 +352,18 @@ An ``Attributes`` section may be used to describe class variables:: y : float The Y coordinate. +Attributes that are properties and have their own docstrings can be +simply listed by name:: + + Attributes + ---------- + real + imag + x : float + The X coordinate + y : float + The Y coordinate + In general, it is not necessary to list class methods. Those that are not part of the public API have names that start with an underscore. In some cases, however, a class may have a great many methods, of @@ -383,6 +390,10 @@ becomes useful to have an additional ``Methods`` section:: """ +If it is necessary to explain a private method (use with care!), it can +be referred to in the **extended summary** or the **notes**. Do not +list private methods in the Methods section. + Note that `self` is *not* listed as the first parameter of methods. Method docstrings @@ -390,6 +401,60 @@ Method docstrings Document these as you would any other function. Do not include ``self`` in the list of parameters. +Documenting class instances +--------------------------- +Instances of classes that are part of the Numpy API (for example `np.r_` +`np,c_`, `np.index_exp`, etc.) may require some care. To give these +instances a useful docstring, we do the following: + +* Single instance: If only a single instance of a class is exposed, + document the class. Examples can use the instance name. + +* Multiple instances: If multiple instances are exposed, docstrings + for each instance are written and assigned to the instances' + ``__doc__`` attributes at run time. The class is documented as usual, and + the exposed instances can be mentioned in the Notes and See Also sections. + +Documenting constants +--------------------- +Use the same sections as outlined for functions where applicable:: + + 1. summary + 2. extended summary (optional) + 3. see also (optional) + 4. references (optional) + 5. examples (optional) + +Docstrings for constants will not be visible in text terminals +(constants are of immutable type, so docstrings can not be assigned +to them like for for class instances), but will appear in the +documentation built with Sphinx. + +Other points to keep in mind +---------------------------- +* Notes and Warnings : If there are points in the docstring that deserve + special emphasis, the reST directives for a note or warning can be used + in the vicinity of the context of the warning (inside a section). Syntax: + + :: + + .. warning:: Warning text. + + .. note:: Note text. + + Use these sparingly, as they do not look very good in text terminals + and are not often necessary. One situation in which a warning can + be useful is for marking a known bug that is not yet fixed. + +* Questions and Answers : For general questions on how to write docstrings + that are not answered in this document, refer to + `<http://docs.scipy.org/numpy/Questions+Answers/>`_. + +* array_like : For functions that take arguments which can have not only + a type `ndarray`, but also types that can be converted to an ndarray + (i.e. scalar types, sequence types), those arguments can be documented + with type `array_like`. + Common reST concepts -------------------- For paragraphs, indentation is significant and indicates indentation in the @@ -412,12 +477,11 @@ followed. Conclusion ---------- -`An example -<http://svn.scipy.org/svn/numpy/trunk/doc/example.py>`_ of the +`An example <http://svn.scipy.org/svn/numpy/trunk/doc/example.py>`_ of the format shown here is available. Refer to `How to Build API/Reference Documentation <http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt>`_ -on how to use epydoc_ or sphinx_ to construct a manual and web page. +on how to use Sphinx_ to build the manual. This document itself was written in ReStructuredText, and may be converted to HTML using:: @@ -426,5 +490,4 @@ HTML using:: .. _SciPy: http://www.scipy.org .. _numpy-discussion list: http://www.scipy.org/Mailing_Lists -.. _epydoc: http://epydoc.sourceforge.net/ -.. _sphinx: http://sphinx.pocoo.org +.. _Sphinx: http://sphinx.pocoo.org diff --git a/doc/Makefile b/doc/Makefile index 82dcc741c..24959750a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -132,6 +132,10 @@ htmlhelp-build: htmlhelp build/htmlhelp/numpy.chm %.chm: %.hhp -hhc.exe $^ +qthelp: generate + mkdir -p build/qthelp build/doctrees + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp + latex: generate mkdir -p build/latex build/doctrees $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex diff --git a/doc/README.txt b/doc/README.txt deleted file mode 100644 index 2a7ad82ee..000000000 --- a/doc/README.txt +++ /dev/null @@ -1,40 +0,0 @@ -NumPy Reference Guide -===================== - -Instructions ------------- -1. Optionally download an XML dump of the newest docstrings from the doc wiki - at ``/pydocweb/dump`` and save it as ``dump.xml``. -2. Run ``make html`` or ``make dist`` - -You can also run ``summarize.py`` to see which parts of the Numpy -namespace are documented. - - -TODO ----- - -* Numberless [*] footnotes cause LaTeX errors. - -* ``See also`` sections are still somehow broken even if some work. - The problem is that Sphinx searches like this:: - - 'name' - 'active_module.name' - 'active_module.active_class.name'. - - Whereas, we would like to have this: - - 'name' - 'active_module.name' - 'parent_of_active_module.name' - 'parent_of_parent_of_active_module.name' - ... - 'numpy.name' - - We can get one step upwards by always using 'numpy' as the active module. - It seems difficult to beat Sphinx to do what we want. - Do we need to change our docstring standard slightly, ie. allow only - leaving the 'numpy.' prefix away? - -* Link resolution doesn't work as intended... eg. `doc.ufunc`_ diff --git a/doc/TESTS.txt b/doc/TESTS.txt index 00d89d21e..40524b82a 100644 --- a/doc/TESTS.txt +++ b/doc/TESTS.txt @@ -8,100 +8,140 @@ NumPy/SciPy Testing Guidelines Introduction '''''''''''' -SciPy uses the `Nose testing system <http://www.somethingaboutorange.com/mrl/projects/nose>`__, with some minor convenience features added. Nose is an extension of the unit testing framework offered by `unittest.py <http://docs.python.org/lib/module-unittest.html>`__. Our goal is that every module and package in SciPy should have a thorough set of unit tests. These tests should exercise the full functionality of a given routine as well as its robustness to erroneous or unexpected input arguments. Long experience has shown that by far the best time to write the tests is before you write or change the code - this is `test-driven development <http://en.wikipedia.org/wiki/Test-driven_development>`__. The arguments for this can sound rather abstract, but we can assure you that you will find that writing the tests first leads to more robust and better designed code. Well-designed tests with good coverage make an enormous difference to the ease of refactoring. Whenever a new bug is found in a routine, you should write a new test for that specific case and add it to the test suite to prevent that bug from creeping back in unnoticed. +SciPy uses the `Nose testing system +<http://www.somethingaboutorange.com/mrl/projects/nose>`__, with some +minor convenience features added. Nose is an extension of the unit +testing framework offered by `unittest.py +<http://docs.python.org/lib/module-unittest.html>`__. Our goal is that +every module and package in SciPy should have a thorough set of unit +tests. These tests should exercise the full functionality of a given +routine as well as its robustness to erroneous or unexpected input +arguments. Long experience has shown that by far the best time to +write the tests is before you write or change the code - this is +`test-driven development +<http://en.wikipedia.org/wiki/Test-driven_development>`__. The +arguments for this can sound rather abstract, but we can assure you +that you will find that writing the tests first leads to more robust +and better designed code. Well-designed tests with good coverage make +an enormous difference to the ease of refactoring. Whenever a new bug +is found in a routine, you should write a new test for that specific +case and add it to the test suite to prevent that bug from creeping +back in unnoticed. To run SciPy's full test suite, use the following:: >>> import scipy >>> scipy.test() -SciPy uses the testing framework from NumPy (specifically ``numpy.testing``), so all the SciPy examples shown here are also applicable to NumPy. So NumPy's full test suite can be run as follows:: +SciPy uses the testing framework from NumPy (specifically +``numpy.testing``), so all the SciPy examples shown here are also +applicable to NumPy. So NumPy's full test suite can be run as +follows:: >>> import numpy >>> numpy.test() -The test method may take two or more arguments; the first is a string label specifying what should be tested and the second is an integer giving the level of output verbosity. See the docstring for numpy.test for details. The default value for the label is 'fast' - which will run the standard tests. The string 'full' will run the full battery of tests, including those identified as being slow to run. If the verbosity is 1 or less, the tests will just show information messages about the tests that are run; but if it is greater than 1, then the tests will also provide warnings on missing tests. So if you want to run every test and get messages about which modules don't have tests:: +The test method may take two or more arguments; the first is a string +label specifying what should be tested and the second is an integer +giving the level of output verbosity. See the docstring for numpy.test +for details. The default value for the label is 'fast' - which will +run the standard tests. The string 'full' will run the full battery +of tests, including those identified as being slow to run. If the +verbosity is 1 or less, the tests will just show information messages +about the tests that are run; but if it is greater than 1, then the +tests will also provide warnings on missing tests. So if you want to +run every test and get messages about which modules don't have tests:: - >>> scipy.test(label='full', verbosity=2) # or - >>> scipy.test('full', 2) + >>> scipy.test(label='full', verbosity=2) # or scipy.test('full', 2) -Finally, if you are only interested in testing a subset of SciPy, for example, the ``integrate`` module, use the following:: +Finally, if you are only interested in testing a subset of SciPy, for +example, the ``integrate`` module, use the following:: >>> scipy.integrate.test() -The rest of this page will give you a basic idea of how to add unit tests to modules in SciPy. It is extremely important for us to have extensive unit testing since this code is going to be used by scientists and researchers and is being developed by a large number of people spread across the world. So, if you are writing a package that you'd like to become part of SciPy, please write the tests as you develop the package. Also since much of SciPy is legacy code that was originally written without unit tests, there are still several modules that don't have tests yet. Please feel free to choose one of these modules to develop test for either after or even as you read through this introduction. +The rest of this page will give you a basic idea of how to add unit +tests to modules in SciPy. It is extremely important for us to have +extensive unit testing since this code is going to be used by +scientists and researchers and is being developed by a large number of +people spread across the world. So, if you are writing a package that +you'd like to become part of SciPy, please write the tests as you +develop the package. Also since much of SciPy is legacy code that was +originally written without unit tests, there are still several modules +that don't have tests yet. Please feel free to choose one of these +modules to develop test for either after or even as you read through +this introduction. Writing your own tests '''''''''''''''''''''' -Every Python module, extension module, or subpackage in the SciPy package directory should have a corresponding ``test_<name>.py`` file. The nose framework picks up tests by first looking for any functions in the file that have test-related names (see below), or classes that inherit from ``unittest.TestCase`` (which is also made available as ``numpy.testing.TestCase``. Any methods of these classes, that also have test-related names, are considered tests. A test-related name is simply a function or method name containing 'test'. +Every Python module, extension module, or subpackage in the SciPy +package directory should have a corresponding ``test_<name>.py`` file. +Nose examines these files for test methods (named test*) and test +classes (named Test*). -Suppose you have a SciPy module ``scipy/xxx/yyy.py`` containing a function ``zzz()``. To test this you would start by creating a test module called ``test_yyy.py``. There are several different ways to implement tests using the nose / SciPy system. There is the standard unittest way and the nose test function way. +Suppose you have a SciPy module ``scipy/xxx/yyy.py`` containing a +function ``zzz()``. To test this function you would create a test +module called ``test_yyy.py``. If you only need to test one aspect of +``zzz``, you can simply add a test function:: -Standard unit test classes --------------------------- + def test_zzz(): + assert zzz() == 'Hello from zzz' -You can use the traditional unittest system by making your test file include a class that tests ``zzz()``. The test class inherits from the TestCase class, and has test methods that test various aspects of ``zzz()``. Within these test methods, ``assert()`` is used to test whether some case is true. If the assert fails, the test fails. The line ``nose.run(...)`` function actually runs the test suite. A minimal example of a ``test_yyy.py`` file that implements tests for a Scipy package module ``scipy.xxx.yyy``, is shown below:: +More often, we need to group a number of tests together, so we create +a test class:: from numpy.testing import * # import xxx symbols from scipy.xxx.yyy import zzz - class test_zzz(TestCase): + class TestZzz: def test_simple(self): - assert zzz()=='Hello from zzz' - #... + assert zzz() == 'Hello from zzz' - if __name__ == "__main__": - run_module_suite() - - -Note that all classes that are inherited from ``TestCase`` class, are picked up by the test runner. For more detailed information on defining test classes see the official documentation for the `Python Unit testing framework <http://docs.python.org/lib/module-unittest.html>`__. - -Using test functions with nose ------------------------------- + def test_invalid_parameter(self): + assert_raises(...) -This is as simple as making a function or functions with names including 'test':: +Within these test methods, ``assert()`` is used to test whether a +certain assumption is valid. If the assert fails, the test fails. - from numpy.testing import * - - # import xxx symbols - from scipy.xxx.yyy import zzz - - def test_simple(self): - assert zzz()=='Hello from zzz' +Sometimes it is convenient to run ``test_yyy.py`` by itself, so we add +:: if __name__ == "__main__": run_module_suite() - -You can mix nose test functions and TestCase classes in a single test file. +at the bottom. Labeling tests with nose ------------------------ -Unlabeled tests like the ones above are run in the default ``scipy.test()`` run. If you want to label your test as slow - and therefore reserved for a full ``scipy.test(label='full')`` run, you can label it with a nose decorator:: +Unlabeled tests like the ones above are run in the default +``scipy.test()`` run. If you want to label your test as slow - and +therefore reserved for a full ``scipy.test(label='full')`` run, you +can label it with a nose decorator:: # numpy.testing module includes 'import decorators as dec' from numpy.testing import * + @dec.slow def test_big(self): print 'Big, slow test' Similarly for methods:: - class test_zzz(TestCase): + class test_zzz: @dec.slow def test_simple(self): - assert zzz()=='Hello from zzz' + assert zzz() == 'Hello from zzz' Easier setup and teardown functions / methods --------------------------------------------- -Nose looks for module level setup and teardown functions by name; thus:: +Nose looks for module level setup and teardown functions by name; +thus:: def setup(): """Module-level setup""" @@ -112,7 +152,8 @@ Nose looks for module level setup and teardown functions by name; thus:: print 'doing teardown' -You can add setup and teardown functions to functions and methods with nose decorators:: +You can add setup and teardown functions to functions and methods with +nose decorators:: import nose from numpy.testing import * @@ -138,7 +179,9 @@ You can add setup and teardown functions to functions and methods with nose deco Parametric tests ---------------- -One very nice feature of nose is allowing easy testing across a range of parameters - a nasty problem for standard unit tests. It does this with test generators:: +One very nice feature of nose is allowing easy testing across a range +of parameters - a nasty problem for standard unit tests. It does this +with test generators:: def check_even(n, nn): """A check function to be used in a test generator.""" @@ -148,31 +191,52 @@ One very nice feature of nose is allowing easy testing across a range of paramet for i in range(0,4,2): yield check_even, i, i*3 -Note that 'check_even' is not itself a test (no 'test' in the name), but 'test_evens' is a generator that returns a series of tests, using 'check_even', across a range of inputs. Nice. +Note that 'check_even' is not itself a test (no 'test' in the name), +but 'test_evens' is a generator that returns a series of tests, using +'check_even', across a range of inputs. + +.. warning:: + + Parametric tests cannot be implemented on classes derived from + TestCase. Doctests -------- -Doctests are a convenient way of documenting the behavior a function and allowing that behavior to be tested at the same time. The output of an interactive Python session can be included in the docstring of a function, and the test framework can run the example and compare the actual output to the expected output. +Doctests are a convenient way of documenting the behavior a function +and allowing that behavior to be tested at the same time. The output +of an interactive Python session can be included in the docstring of a +function, and the test framework can run the example and compare the +actual output to the expected output. -The doctests can be run by adding the ``doctests`` argument to the ``test()`` call; for example, to run all tests (including doctests) for numpy.lib:: +The doctests can be run by adding the ``doctests`` argument to the +``test()`` call; for example, to run all tests (including doctests) +for numpy.lib:: >>> import numpy as np >>> np.lib.test(doctests=True) -The doctests are run as if they are in a fresh Python instance which has executed ``import numpy as np`` (tests that are part of the SciPy package also have an implicit ``import scipy as sp``). +The doctests are run as if they are in a fresh Python instance which +has executed ``import numpy as np`` (tests that are part of the SciPy +package also have an implicit ``import scipy as sp``). ``tests/`` ---------- -Rather than keeping the code and the tests in the same directory, we put all the tests for a given subpackage in a ``tests/`` subdirectory. For our example, if it doesn't all ready exist you will need to create a ``tests/`` directory in ``scipy/xxx/``. So the path for ``test_yyy.py`` is ``scipy/xxx/tests/test_yyy.py``. +Rather than keeping the code and the tests in the same directory, we +put all the tests for a given subpackage in a ``tests/`` +subdirectory. For our example, if it doesn't all ready exist you will +need to create a ``tests/`` directory in ``scipy/xxx/``. So the path +for ``test_yyy.py`` is ``scipy/xxx/tests/test_yyy.py``. -Once the ``scipy/xxx/tests/test_yyy.py`` is written, its possible to run the tests by going to the ``tests/`` directory and typing:: +Once the ``scipy/xxx/tests/test_yyy.py`` is written, its possible to +run the tests by going to the ``tests/`` directory and typing:: python test_yyy.py -Or if you add ``scipy/xxx/tests/`` to the Python path, you could run the tests interactively in the interpreter like this:: +Or if you add ``scipy/xxx/tests/`` to the Python path, you could run +the tests interactively in the interpreter like this:: >>> import test_yyy >>> test_yyy.test() @@ -180,14 +244,18 @@ Or if you add ``scipy/xxx/tests/`` to the Python path, you could run the tests i ``__init__.py`` and ``setup.py`` -------------------------------- -Usually however, adding the ``tests/`` directory to the python path isn't desirable. Instead it would better to invoke the test straight from the module ``xxx``. To this end, simply place the following lines at the end of your package's ``__init__.py`` file:: +Usually, however, adding the ``tests/`` directory to the python path +isn't desirable. Instead it would better to invoke the test straight +from the module ``xxx``. To this end, simply place the following lines +at the end of your package's ``__init__.py`` file:: ... def test(level=1, verbosity=1): from numpy.testing import Tester return Tester().test(level, verbosity) -You will also need to add the tests directory in the configuration section of your setup.py:: +You will also need to add the tests directory in the configuration +section of your setup.py:: ... def configuration(parent_package='', top_path=None): @@ -201,10 +269,11 @@ Now you can do the following to test your module:: >>> import scipy >>> scipy.xxx.test() -Also, when invoking the entire SciPy test suite, your tests will be found and run:: +Also, when invoking the entire SciPy test suite, your tests will be +found and run:: >>> import scipy - >>> scipy.test() + >>> scipy.test() # your tests are included and run automatically! Tips & Tricks @@ -213,7 +282,12 @@ Tips & Tricks Creating many similar tests --------------------------- -If you have a collection of tests that must be run multiple times with minor variations, it can be helpful to create a base class containing all the common tests, and then create a subclass for each variation. Several examples of this technique exist in NumPy; below are excerpts from one in `numpy/linalg/tests/test_linalg.py <http://svn.scipy.org/svn/numpy/trunk/numpy/linalg/tests/test_linalg.py>`__:: +If you have a collection of tests that must be run multiple times with +minor variations, it can be helpful to create a base class containing +all the common tests, and then create a subclass for each variation. +Several examples of this technique exist in NumPy; below are excerpts +from one in `numpy/linalg/tests/test_linalg.py +<http://svn.scipy.org/svn/numpy/trunk/numpy/linalg/tests/test_linalg.py>`__:: class LinalgTestCase: def test_single(self): @@ -228,24 +302,30 @@ If you have a collection of tests that must be run multiple times with minor var ... - class TestSolve(LinalgTestCase, TestCase): + class TestSolve(LinalgTestCase): def do(self, a, b): x = linalg.solve(a, b) assert_almost_equal(b, dot(a, x)) assert imply(isinstance(b, matrix), isinstance(x, matrix)) - class TestInv(LinalgTestCase, TestCase): + class TestInv(LinalgTestCase): def do(self, a, b): a_inv = linalg.inv(a) assert_almost_equal(dot(a, a_inv), identity(asarray(a).shape[0])) assert imply(isinstance(a, matrix), isinstance(a_inv, matrix)) -In this case, we wanted to test solving a linear algebra problem using matrices of several data types, using ``linalg.solve`` and ``linalg.inv``. The common test cases (for single-precision, double-precision, etc. matrices) are collected in ``LinalgTestCase``. Note that ``LinalgTestCase`` is not descended from ``TestCase``--if it were, then nose would attempt to run ``LinalgTestCase.test_single`` and ``LinalgTestCase.test_double``, which would fail because ``LinalgTestCase`` has no ``do`` method. Since ``TestSolve`` and ``TestInv`` inherit from ``LinalgTestCase`` and ``TestCase``, nose will run ``test_single`` and ``test_double`` for each class. +In this case, we wanted to test solving a linear algebra problem using +matrices of several data types, using ``linalg.solve`` and +``linalg.inv``. The common test cases (for single-precision, +double-precision, etc. matrices) are collected in ``LinalgTestCase``. Known failures & skipping tests ------------------------------- -Sometimes you might want to skip a test or mark it as a known failure, such as when the test suite is being written before the code it's meant to test, or if a test only fails on a particular architecture. The decorators from numpy.testing.dec can be used to do this. +Sometimes you might want to skip a test or mark it as a known failure, +such as when the test suite is being written before the code it's +meant to test, or if a test only fails on a particular architecture. +The decorators from numpy.testing.dec can be used to do this. To skip a test, simply use ``skipif``:: @@ -255,7 +335,10 @@ To skip a test, simply use ``skipif``:: def test_something(foo): ... -The test is marked as skipped if ``SkipMyTest`` evaluates to nonzero, and the message in verbose test output is the second argument given to ``skipif``. Similarly, a test can be marked as a known failure by using ``knownfailureif``:: +The test is marked as skipped if ``SkipMyTest`` evaluates to nonzero, +and the message in verbose test output is the second argument given to +``skipif``. Similarly, a test can be marked as a known failure by +using ``knownfailureif``:: from numpy.testing import * @@ -263,8 +346,12 @@ The test is marked as skipped if ``SkipMyTest`` evaluates to nonzero, and the me def test_something_else(foo): ... -Of course, a test can be unconditionally skipped or marked as a known failure by passing ``True`` as the first argument to ``skipif`` or ``knownfailureif``, respectively. - -A total of the number of skipped and known failing tests is displayed at the end of the test run. Skipped tests are marked as ``'S'`` in the test results (or ``'SKIPPED'`` for ``verbosity > 1``), and known failing tests are marked as ``'K'`` (or ``'KNOWN'`` if ``verbosity > 1``). - +Of course, a test can be unconditionally skipped or marked as a known +failure by passing ``True`` as the first argument to ``skipif`` or +``knownfailureif``, respectively. +A total of the number of skipped and known failing tests is displayed +at the end of the test run. Skipped tests are marked as ``'S'`` in +the test results (or ``'SKIPPED'`` for ``verbosity > 1``), and known +failing tests are marked as ``'K'`` (or ``'KNOWN'`` if ``verbosity > +1``). diff --git a/doc/example.py b/doc/example.py index 152e2a622..0d5b53a33 100644 --- a/doc/example.py +++ b/doc/example.py @@ -35,7 +35,7 @@ import matplotlib.pyplot as plt from my_module import my_func, other_func def foo(var1, var2, long_var_name='hi') : - """A one-line summary that does not use variable names or the + r"""A one-line summary that does not use variable names or the function name. Several sentences providing an extended description. Refer to @@ -58,11 +58,11 @@ def foo(var1, var2, long_var_name='hi') : ------- describe : type Explanation - output + output : type Explanation - tuple + tuple : type Explanation - items + items : type even more explaining Other Parameters @@ -117,7 +117,6 @@ def foo(var1, var2, long_var_name='hi') : [4, 5, 6] >>> print "a\n\nb" a - <BLANKLINE> b """ diff --git a/doc/neps/datetime-proposal3.rst b/doc/neps/datetime-proposal3.rst index aad549a88..6874aac13 100644 --- a/doc/neps/datetime-proposal3.rst +++ b/doc/neps/datetime-proposal3.rst @@ -77,6 +77,7 @@ corresponding time spans. s second [ 2.9e9 BC, 2.9e9 AC] ms millisecond [ 2.9e6 BC, 2.9e6 AC] us microsecond [290301 BC, 294241 AC] + c# ticks (100ns) [ 2757 BC, 31197 AC] ns nanosecond [ 1678 AC, 2262 AC] ======== ================ ========================== @@ -97,10 +98,9 @@ Using the long string notation:: Using the short string notation:: - dtype('T8[us]') + dtype('M8[us]') -Note that a time unit should always be specified, as there is not a -default. +The default is microseconds if no time unit is specified. Thus, 'M8' is equivalent to 'M8[us]' Setting and getting values @@ -108,7 +108,7 @@ Setting and getting values The objects with this dtype can be set in a series of ways:: - t = numpy.ones(3, dtype='T8[s]') + t = numpy.ones(3, dtype='M8[s]') t[0] = 1199164176 # assign to July 30th, 2008 at 17:31:00 t[1] = datetime.datetime(2008, 7, 30, 17, 31, 01) # with datetime module t[2] = '2008-07-30T17:31:02' # with ISO 8601 @@ -128,28 +128,28 @@ Comparisons The comparisons will be supported too:: - numpy.array(['1980'], 'T8[Y]') == numpy.array(['1979'], 'T8[Y]') + numpy.array(['1980'], 'M8[Y]') == numpy.array(['1979'], 'M8[Y]') --> [False] or by applying broadcasting:: - numpy.array(['1979', '1980'], 'T8[Y]') == numpy.datetime64('1980', 'Y') + numpy.array(['1979', '1980'], 'M8[Y]') == numpy.datetime64('1980', 'Y') --> [False, True] The next should work too:: - numpy.array(['1979', '1980'], 'T8[Y]') == '1980-01-01' + numpy.array(['1979', '1980'], 'M8[Y]') == '1980-01-01' --> [False, True] because the right hand expression can be broadcasted into an array of 2 -elements of dtype 'T8[Y]'. +elements of dtype 'M8[Y]'. Compatibility issues ~~~~~~~~~~~~~~~~~~~~ This will be fully compatible with the ``datetime`` class of the ``datetime`` module of Python only when using a time unit of -microseconds. For other time units, the conversion process will loose +microseconds. For other time units, the conversion process will lose precision or will overflow as needed. The conversion from/to a ``datetime`` object doesn't take leap seconds into account. @@ -187,6 +187,7 @@ corresponding time spans. s second +- 2.9e12 years ms millisecond +- 2.9e9 years us microsecond +- 2.9e6 years + c# ticks (100ns) +- 2.9e4 years ns nanosecond +- 292 years ps picosecond +- 106 days fs femtosecond +- 2.6 hours @@ -207,17 +208,17 @@ Using the long string notation:: Using the short string notation:: - dtype('t8[us]') + dtype('m8[us]') + +The default is micro-seconds if no default is specified: 'm8' is equivalent to 'm8[us]' -Note that a time unit should always be specified, as there is not a -default. Setting and getting values ~~~~~~~~~~~~~~~~~~~~~~~~~~ The objects with this dtype can be set in a series of ways:: - t = numpy.ones(3, dtype='t8[ms]') + t = numpy.ones(3, dtype='m8[ms]') t[0] = 12 # assign to 12 ms t[1] = datetime.timedelta(0, 0, 13000) # 13 ms t[2] = '0:00:00.014' # 14 ms @@ -236,21 +237,21 @@ Comparisons The comparisons will be supported too:: - numpy.array([12, 13, 14], 't8[ms]') == numpy.array([12, 13, 13], 't8[ms]') + numpy.array([12, 13, 14], 'm8[ms]') == numpy.array([12, 13, 13], 'm8[ms]') --> [True, True, False] or by applying broadcasting:: - numpy.array([12, 13, 14], 't8[ms]') == numpy.timedelta64(13, 'ms') + numpy.array([12, 13, 14], 'm8[ms]') == numpy.timedelta64(13, 'ms') --> [False, True, False] The next should work too:: - numpy.array([12, 13, 14], 't8[ms]') == '0:00:00.012' + numpy.array([12, 13, 14], 'm8[ms]') == '0:00:00.012' --> [True, False, False] because the right hand expression can be broadcasted into an array of 3 -elements of dtype 't8[ms]'. +elements of dtype 'm8[ms]'. Compatibility issues ~~~~~~~~~~~~~~~~~~~~ @@ -340,12 +341,12 @@ Operating with date/time arrays The only arithmetic operation allowed between absolute dates is the subtraction:: - In [10]: numpy.ones(3, "T8[s]") - numpy.zeros(3, "T8[s]") + In [10]: numpy.ones(3, "M8[s]") - numpy.zeros(3, "M8[s]") Out[10]: array([1, 1, 1], dtype=timedelta64[s]) But not other operations:: - In [11]: numpy.ones(3, "T8[s]") + numpy.zeros(3, "T8[s]") + In [11]: numpy.ones(3, "M8[s]") + numpy.zeros(3, "M8[s]") TypeError: unsupported operand type(s) for +: 'numpy.ndarray' and 'numpy.ndarray' Comparisons between absolute dates are allowed. @@ -360,12 +361,12 @@ time units can be very different, and it is not clear at all what time unit will be preferred for the user. For example, this should be allowed:: - >>> numpy.ones(3, dtype="T8[Y]") - numpy.zeros(3, dtype="T8[Y]") + >>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[Y]") array([1, 1, 1], dtype="timedelta64[Y]") But the next should not:: - >>> numpy.ones(3, dtype="T8[Y]") - numpy.zeros(3, dtype="T8[ns]") + >>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[ns]") raise numpy.IncompatibleUnitError # what unit to choose? @@ -375,15 +376,15 @@ But the next should not:: It will be possible to add and subtract relative times from absolute dates:: - In [10]: numpy.zeros(5, "T8[Y]") + numpy.ones(5, "t8[Y]") + In [10]: numpy.zeros(5, "M8[Y]") + numpy.ones(5, "m8[Y]") Out[10]: array([1971, 1971, 1971, 1971, 1971], dtype=datetime64[Y]) - In [11]: numpy.ones(5, "T8[Y]") - 2 * numpy.ones(5, "t8[Y]") + In [11]: numpy.ones(5, "M8[Y]") - 2 * numpy.ones(5, "m8[Y]") Out[11]: array([1969, 1969, 1969, 1969, 1969], dtype=datetime64[Y]) But not other operations:: - In [12]: numpy.ones(5, "T8[Y]") * numpy.ones(5, "t8[Y]") + In [12]: numpy.ones(5, "M8[Y]") * numpy.ones(5, "m8[Y]") TypeError: unsupported operand type(s) for *: 'numpy.ndarray' and 'numpy.ndarray' Casting rules @@ -408,15 +409,15 @@ Finally, it will be possible to operate with relative times as if they were regular int64 dtypes *as long as* the result can be converted back into a ``timedelta64``:: - In [10]: numpy.ones(3, 't8[us]') + In [10]: numpy.ones(3, 'm8[us]') Out[10]: array([1, 1, 1], dtype="timedelta64[us]") - In [11]: (numpy.ones(3, 't8[M]') + 2) ** 3 + In [11]: (numpy.ones(3, 'm8[M]') + 2) ** 3 Out[11]: array([27, 27, 27], dtype="timedelta64[M]") But:: - In [12]: numpy.ones(5, 't8') + 1j + In [12]: numpy.ones(5, 'm8') + 1j TypeError: the result cannot be converted into a ``timedelta64`` Casting rules @@ -426,14 +427,14 @@ When combining two ``timedelta64`` dtypes with different time units the outcome will be the shorter of both ("keep the precision" rule). For example:: - In [10]: numpy.ones(3, 't8[s]') + numpy.ones(3, 't8[m]') + In [10]: numpy.ones(3, 'm8[s]') + numpy.ones(3, 'm8[m]') Out[10]: array([61, 61, 61], dtype="timedelta64[s]") However, due to the impossibility to know the exact duration of a relative year or a relative month, when these time units appear in one of the operands, the operation will not be allowed:: - In [11]: numpy.ones(3, 't8[Y]') + numpy.ones(3, 't8[D]') + In [11]: numpy.ones(3, 'm8[Y]') + numpy.ones(3, 'm8[D]') raise numpy.IncompatibleUnitError # how to convert relative years to days? In order to being able to perform the above operation a new NumPy @@ -451,11 +452,11 @@ days). With this, the above operation can be done as follows:: - In [10]: t_years = numpy.ones(3, 't8[Y]') + In [10]: t_years = numpy.ones(3, 'm8[Y]') In [11]: t_days = numpy.change_timeunit(t_years, 'D', '2001-01-01') - In [12]: t_days + numpy.ones(3, 't8[D]') + In [12]: t_days + numpy.ones(3, 'm8[D]') Out[12]: array([366, 366, 366], dtype="timedelta64[D]") diff --git a/doc/numpy.scipy.org/Makefile b/doc/numpy.scipy.org/Makefile new file mode 100644 index 000000000..93933ba25 --- /dev/null +++ b/doc/numpy.scipy.org/Makefile @@ -0,0 +1,105 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf build/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html + @echo + @echo "Build finished. The HTML pages are in build/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml + @echo + @echo "Build finished. The HTML pages are in build/dirhtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in build/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in build/qthelp, like this:" + @echo "# qcollectiongenerator build/qthelp/Numpy.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile build/qthelp/Numpy.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) build/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Numpy" + @echo "# ln -s build/devhelp $$HOME/.local/share/devhelp/Numpy" + @echo "# devhelp" + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex + @echo + @echo "Build finished; the LaTeX files are in build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +latexpdf: latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex + @echo "Running LaTeX files through pdflatex..." + make -C build/latex all-pdf + @echo "pdflatex finished; the PDF files are in build/latex." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes + @echo + @echo "The overview file is in build/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in build/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in build/doctest/output.txt." diff --git a/doc/numpy.scipy.org/source/conf.py b/doc/numpy.scipy.org/source/conf.py new file mode 100644 index 000000000..16bd69f83 --- /dev/null +++ b/doc/numpy.scipy.org/source/conf.py @@ -0,0 +1,206 @@ +# -*- coding: utf-8 -*- +# +# Scipy.org documentation build configuration file +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.pngmath', + 'sphinx.ext.ifconfig'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Numpy' +copyright = u'2009 Numpy developers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '' +# The full version, including alpha/beta/rc tags. +release = '' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'scipy' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["../theme"] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +html_title = "Numpy" + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = "" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Scipy.org' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'numpy-scipy-org.tex', u'numpy.scipy.org', + u'NumPy collaborators', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'http://docs.python.org/': None, + 'http://docs.scipy.org/doc/numpy/': None, +} diff --git a/doc/numpy.scipy.org/source/index.rst b/doc/numpy.scipy.org/source/index.rst new file mode 100644 index 000000000..ee2ac48fd --- /dev/null +++ b/doc/numpy.scipy.org/source/index.rst @@ -0,0 +1,32 @@ +NumPy is the fundamental package needed for scientific computing with Python. It contains among other things: + +- a powerful N-dimensional array object +- sophisticated (broadcasting) functions +- tools for integrating C/C++ and Fortran code +- useful linear algebra, Fourier transform, and random number capabilities. + +Besides its obvious scientific uses, NumPy can also be used as an efficient multi-dimensional container of generic data. Arbitrary data-types can be defined. This allows NumPy to seamlessly and speedily integrate with a wide variety of databases. + +Getting Started +--------------- + +- `Getting Numpy <http://www.scipy.org/Download>`_ +- `Installing NumPy and SciPy <http://www.scipy.org/Installing_SciPy>`_ +- `NumPy and SciPy documentation page <http://docs.scipy.org/doc/>`_ +- `NumPy Tutorial <http://www.scipy.org/Tentative_NumPy_Tutorial>`_ +- `NumPy for MATLAB© Users <http://www.scipy.org/NumPy_for_Matlab_Users>`_ +- `NumPy functions by category <http://www.scipy.org/Numpy_Functions_by_Category>`_ +- `NumPy Mailing List <http://www.scipy.org/Mailing_Lists>`_ + +More Information +---------------- + +- `NumPy Sourceforge Home Page <http://sourceforge.net/projects/numpy/>`_ +- `SciPy Home Page <http://www.scipy.org/>`_ +- `Interfacing with compiled code <http://www.scipy.org/Topical_Software#head-7153b42ac4ea517c7d99ec4f4453555b2302a1f8>`_ +- :doc:`Older python array packages </old_array_packages>` + +.. toctree:: + :hidden: + + old_array_packages diff --git a/doc/numpy.scipy.org/source/old_array_packages.rst b/doc/numpy.scipy.org/source/old_array_packages.rst new file mode 100644 index 000000000..814083ed6 --- /dev/null +++ b/doc/numpy.scipy.org/source/old_array_packages.rst @@ -0,0 +1,40 @@ +==================== +Older Array Packages +==================== + +It may take months for the large code base that uses Numeric and/or Numarray +to transition to the new NumPy system. Links to the older packages are +provided here. New users should start out with NumPy. + +Much of the documentation for Numeric and Numarray is applicable to the NumPy package. However, there are `significant feature improvements <http://numpy.scipy.org/new_features.html>`_. A complete guide to the new system has been written by the primary developer, Travis Oliphant. It is now in the public domain. Other Documentation is available at `the scipy website <http://www.scipy.org/>`_ and in the docstrings (which can be extracted using pydoc). Free Documentation for Numeric (most of which is still valid) is `here <http://numpy.scipy.org/numpydoc/numdoc.htm>`_ or as a `pdf <http://numpy.scipy.org/numpy.pdf>`_ file. Obviously you should replace references to Numeric in that document with numpy (i.e. instead of "import Numeric", use "import numpy"). + +Upgrading from historical implementations +========================================= + +NumPy derives from the old Numeric code base and can be used as a replacement for Numeric. It also adds the features introduced by Numarray and can also be used to replace Numarray. + +Numeric users should find the transition relatively easy (although not without some effort). There is a module (numpy.oldnumeric.alter_code1) that can makemost of the necessary changes to your Python code that used Numeric to work with NumPy's Numeric compatibility module. + +Users of numarray can also transition their code using a similar module (numpy.numarray.alter_code1) and the numpy.numarray compatibility layer. + +C-code written to either package can be easily ported to NumPy using "numpy/oldnumeric.h" and "numpy/libnumarray.h" for the Numeric C-API and the Numarray C-API respectively. `Sourceforge download site <http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_ + +For about 6 months at the end of 2005, the new package was called SciPy Core (not to be confused with the full SciPy package which remains a `separate <http://www.scipy.org/>`_ package), and so you will occasionally see references to SciPy Core floating around. It was decided in January 2006 to go with the historical name of NumPy for the new package. Realize that NumPy (module name numpy) is the new name. Because of the name-change, there were a lot of dicussions that took place on scipy-dev@scipy.org and scipy-user@scipy.org. If you have a question about the new system, you may wish to run a search on those mailing lists as well as the main NumPy list (numpy-discussion@lists.sourceforge.net) + +Numeric (version 24.2) +====================== + +Numeric was the first array object built for Python. It has been quite successful and is used in a wide variety of settings and applications. Maintenance has ceased for Numeric, and users should transisition to NumPy as quickly as possible. There is a module called numpy.oldnumeric.alter_code1 in NumPy that can make the transition to NumPy easier (it will automatically perform the search-and-replace style changes that need to be made to python code that uses Numeric to make it work with NumPy). + +Documentation for Numeric is at http://numpy.scipy.org/numpydoc/numdoc.htm> or as a `pdf <http://numpy.scipy.org/numpy.pdf>`_ file `Sourceforge Numeric Download Page <http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=1351>`_ + +Numarray +======== + +Numarray is another implementation of an array object for Python written after +Numeric and before NumPy. Sponsors of numarray have indicated they will be +moving to NumPy as soon as is feasible for them so that eventually numarray +will be phased out (probably sometime in 2007). This project shares some of +the resources with the Numeric sourceforge site but maintains its own web page +at http://www.stsci.edu/resources/software_hardware/numarray +`Sourceforge Numarray Download Page <http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=32367>`_
\ No newline at end of file diff --git a/doc/numpy.scipy.org/theme/scipy/layout.html b/doc/numpy.scipy.org/theme/scipy/layout.html new file mode 100644 index 000000000..927088ce5 --- /dev/null +++ b/doc/numpy.scipy.org/theme/scipy/layout.html @@ -0,0 +1,16 @@ +{% extends "sphinxdoc/layout.html" %} + +{% block rootrellink %} +{% endblock %} + +{% block relbar1 %} +<div class="top-logo-header"> +<a href="{{ pathto('index') }}"><img src="{{ pathto("_static/numpy_logo.png", 1) }}" border="0" alt="NumPy Homepage"/></a> +</div> +{% endblock %} + +{% block relbar2 %}{% endblock %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{% endblock %} +{% block sidebar2 %}{% endblock %} diff --git a/doc/numpy.scipy.org/theme/scipy/static/logo.gif b/doc/numpy.scipy.org/theme/scipy/static/logo.gif Binary files differnew file mode 100644 index 000000000..ab2e3ac33 --- /dev/null +++ b/doc/numpy.scipy.org/theme/scipy/static/logo.gif diff --git a/doc/numpy.scipy.org/theme/scipy/static/numpy_logo.png b/doc/numpy.scipy.org/theme/scipy/static/numpy_logo.png Binary files differnew file mode 100644 index 000000000..5ed48c094 --- /dev/null +++ b/doc/numpy.scipy.org/theme/scipy/static/numpy_logo.png diff --git a/doc/numpy.scipy.org/theme/scipy/static/scipy.css b/doc/numpy.scipy.org/theme/scipy/static/scipy.css new file mode 100644 index 000000000..377c45955 --- /dev/null +++ b/doc/numpy.scipy.org/theme/scipy/static/scipy.css @@ -0,0 +1,200 @@ +@import "sphinxdoc.css"; + +/** + * Spacing fixes + */ + + +div.body { + width: 90%; +} + +div.bodywrapper { + width: 100%; +} + +div.body p, div.body dd, div.body li { + line-height: 125%; +} + +ul.simple { + margin-top: 0; + margin-bottom: 0; + padding-top: 0; + padding-bottom: 0; +} + +/* spacing around blockquoted fields in parameters/attributes/returns */ +td.field-body > blockquote { + margin-top: 0.1em; + margin-bottom: 0.5em; +} + +/* spacing around example code */ +div.highlight > pre { + padding: 2px 5px 2px 5px; +} + +/* spacing in see also definition lists */ +dl.last > dd { + margin-top: 1px; + margin-bottom: 5px; + margin-left: 30px; +} + +/** + * Hide dummy toctrees + */ + +ul { + padding-top: 0; + padding-bottom: 0; + margin-top: 0; + margin-bottom: 0; +} +ul li { + padding-top: 0; + padding-bottom: 0; + margin-top: 0; + margin-bottom: 0; +} +ul li a.reference { + padding-top: 0; + padding-bottom: 0; + margin-top: 0; + margin-bottom: 0; +} + +/** + * Make high-level subsections easier to distinguish from top-level ones + */ +div.body h3 { + background-color: transparent; +} + +div.body h4 { + border: none; + background-color: transparent; +} + +/** + * Scipy colors + */ + +body { + background-color: rgb(100,135,220); + border: none; +} + +div.sphinxsidebar { + display: none; +} + +div.sphinxsidebar h3 { + color: rgb(0,102,204); +} + +div.sphinxsidebar h4 { + color: rgb(0,82,194); +} + +div.sphinxsidebar p { + color: black; +} + +div.sphinxsidebar ul.want-points { + list-style: disc; +} + +.field-list th { + color: rgb(0,102,204); +} + +/** + * Extra admonitions + */ + +div.tip { + background-color: #ffffe4; + border: 1px solid #ee6; +} + +div.plot-output { + clear-after: both; +} + +div.plot-output .figure { + float: left; + text-align: center; + margin-bottom: 0; + padding-bottom: 0; +} + +div.plot-output .caption { + margin-top: 2; + padding-top: 0; +} + +div.plot-output p.admonition-title { + display: none; +} + +div.plot-output:after { + content: ""; + display: block; + height: 0; + clear: both; +} + + +/* +div.admonition-example { + background-color: #e4ffe4; + border: 1px solid #ccc; +}*/ + + +/** + * Styling for field lists + */ + +table.field-list th { + border-left: 1px solid #aaa !important; + padding-left: 5px; +} + +table.field-list { + border-collapse: separate; + border-spacing: 10px; +} + +/** + * Styling for footnotes + */ + +table.footnote td, table.footnote th { + border: none; +} + +/** + * Top header logo and colors + */ +body div.top-logo-header { + text-align: left; + background-color: #8CAAE6; + border-bottom: 8px solid #003399; + border-top: 10px solid #6487dc; +} + +/** + * Footer colors + */ +body div.footer { + background-color: #6487dc; + border: none; + color: white; + text-align: center; +} +body div.footer a { + color: white; +} diff --git a/doc/numpy.scipy.org/theme/scipy/theme.conf b/doc/numpy.scipy.org/theme/scipy/theme.conf new file mode 100644 index 000000000..e2f5ed848 --- /dev/null +++ b/doc/numpy.scipy.org/theme/scipy/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = sphinxdoc +stylesheet = scipy.css +pygments_css = friendly diff --git a/doc/release/1.4.0-notes.rst b/doc/release/1.4.0-notes.rst new file mode 100644 index 000000000..849b429cb --- /dev/null +++ b/doc/release/1.4.0-notes.rst @@ -0,0 +1,132 @@ +========================= +NumPy 1.4.0 Release Notes +========================= + +This minor includes numerous bug fixes as well as a few new features. + +Highlights +========== + +New features +============ + +Extended array wrapping mechanism for ufuncs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An __array_prepare__ method has been added to ndarray to provide subclasses +greater flexibility to interact with ufuncs and ufunc-like functions. ndarray +already provided __array_wrap__, which allowed subclasses to set the array type +for the result and populate metadata on the way out of the ufunc (as seen in +the implementation of MaskedArray). For some applications it is necessary to +provide checks and populate metadata *on the way in*. __array_prepare__ is +therefore called just after the ufunc has initialized the output array but +before computing the results and populating it. This way, checks can be made +and errors raised before operations which may modify data in place. + +Automatic detection of forward incompatibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, if an extension was built against a version N of NumPy, and used on +a system with NumPy M < N, the import_array was successfull, which could cause +crashes because the version M does not have a function in N. Starting from +NumPy 1.4.0, this will cause a failure in import_array, so the error will be +catched early on. + +New C API +~~~~~~~~~ + +The following C functions have been added to the C API: + + #. PyArray_GetNDArrayCFeatureVersion: return the *API* version of the + loaded numpy. + #. PyArray_Correlate2 - like PyArray_Correlate, but implements the usual + definition of correlation. Inputs are not swapped, and conjugate is + taken for complex arrays. + #. PyArray_NeighborhoodIterNew - a new iterator to iterate over a + neighborhood of a point, with automatic boundaries handling. + +New ufuncs +~~~~~~~~~~ + +The following ufuncs have been added to the C API: + + #. copysign - return the value of the first argument with the sign copied + from the second argument. + +New defines +~~~~~~~~~~~ + +The alpha processor is now defined and available in numpy/npy_cpu.h. The +failed detection of the PARISC processor has been fixed. The defines are: + + #. NPY_CPU_HPPA: PARISC + #. NPY_CPU_ALPHA: Alpha + +Enhancements +~~~~~~~~~~~~ + + #. The sort functions now sort nans to the end. + + * Real sort order is [R, nan] + * Complex sort order is [R + Rj, R + nanj, nan + Rj, nan + nanj] + + Complex numbers with the same nan placements are sorted according to + the non-nan part if it exists. + #. The type comparison functions have been made consistent with the new + sort order of nans. Searchsorted now works with sorted arrays + containing nan values. + #. Complex division has been made more resistent to overflow. + #. Complex floor division has been made more resistent to overflow. + +Testing +~~~~~~~ + + #. deprecated decorator: this decorator may be used to avoid cluttering + testing output while testing DeprecationWarning is effectively raised by + the decorated test. + + +Deprecations +============ + +The following functions are deprecated: + + #. correlate: it takes a new keyword argument old_behavior. When True (the + default), it returns the same result as before. When False, compute the + conventional correlation, and take the conjugate for complex arrays. The + old behavior will be removed in NumPy 1.5, and raises a + DeprecationWarning in 1.4. + +New iterators +~~~~~~~~~~~~~ + +A new neighborhood iterator has been added to the C API. It can be used to +iterate over the items in a neighborhood of an array, and can handle boundaries +conditions automatically. Zero and one padding are available, as well as +arbitrary constant value, mirror and circular padding. + +Internal changes +================ + +split multiarray and umath source code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The source code of multiarray and umath has been split into separate logic +compilation units. This should make the source code more amenable for +newcomers. + +Separate compilation +~~~~~~~~~~~~~~~~~~~~ + +By default, every file of multiarray (and umath) is merged into one for +compilation as was the case before, but if NPY_SEPARATE_COMPILATION env +variable is set to a non-negative value, experimental individual compilation of +each file is enabled. This makes the compile/debug cycle much faster when +working on core numpy. + +Separate core math library +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +New functions which have been added: + + * npy_copysign diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..0cabe7cd1 --- /dev/null +++ b/doc/source/_templates/autosummary/class.rst @@ -0,0 +1,23 @@ +{% extends "!autosummary/class.rst" %} + +{% block methods %} +{% if methods %} + .. HACK + .. autosummary:: + :toctree: + {% for item in methods %} + {{ name }}.{{ item }} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ name }}.{{ item }} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 318011e8a..b610470de 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,12 +18,13 @@ sys.path.insert(0, os.path.abspath('../sphinxext')) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', - 'only_directives', 'plot_directive'] + 'plot_directive'] if sphinx.__version__ >= "0.7": extensions.append('sphinx.ext.autosummary') else: extensions.append('autosummary') + extensions.append('only_directives') # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -44,6 +45,7 @@ copyright = '2008-2009, The Scipy community' import numpy # The short X.Y version (including .devXXXX, rcX, b1 suffixes if present) version = re.sub(r'(\d+\.\d+)\.\d+(.*)', r'\1\2', numpy.__version__) +version = re.sub(r'(\.dev\d+).*?$', r'\1', version) # The full version, including alpha/beta/rc tags. release = numpy.__version__ print version, release @@ -250,6 +252,9 @@ np.random.seed(0) plot_include_source = True plot_formats = [('png', 100), 'pdf'] +import math +phi = (math.sqrt(5) + 1)/2 + import matplotlib matplotlib.rcParams.update({ 'font.size': 8, @@ -258,7 +263,7 @@ matplotlib.rcParams.update({ 'xtick.labelsize': 8, 'ytick.labelsize': 8, 'legend.fontsize': 8, - 'figure.figsize': (3.236068, 2), + 'figure.figsize': (3*phi, 3), 'figure.subplot.bottom': 0.2, 'figure.subplot.left': 0.2, 'figure.subplot.right': 0.9, diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 671c95bbf..f9abfbafa 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -47,14 +47,29 @@ customize: update meta-information from the "parent." Subclasses inherit a default implementation of this method that does nothing. -.. function:: __array_wrap__(array) - - This method should return an instance of the subclass from the - :class:`ndarray` object passed in. For example, this is called - after every :ref:`ufunc <ufuncs.output-type>` for the object with - the highest array priority. The ufunc-computed array object is - passed in and whatever is returned is passed to the - user. Subclasses inherit a default implementation of this method. +.. function:: __array_prepare__(array, context=None) + + At the beginning of every :ref:`ufunc <ufuncs.output-type>`, this + method is called on the input object with the highest array + priority, or the output object if one was specified. The output + array is passed in and whatever is returned is passed to the ufunc. + Subclasses inherit a default implementation of this method which + simply returns the output array unmodified. Subclasses may opt to + use this method to transform the output array into an instance of + the subclass and update metadata before returning the array to the + ufunc for computation. + +.. function:: __array_wrap__(array, context=None) + + At the end of every :ref:`ufunc <ufuncs.output-type>`, this method + is called on the input object with the highest array priority, or + the output object if one was specified. The ufunc-computed array + is passed in and whatever is returned is passed to the user. + Subclasses inherit a default implementation of this method, which + transforms the array into a new instance of the object's class. Subclasses + may opt to use this method to transform the output array into an + instance of the subclass and update metadata before returning the + array to the user. .. data:: __array_priority__ diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 0def05ced..1bf7d1ac8 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -9,14 +9,14 @@ The N-dimensional array (:class:`ndarray`) An :class:`ndarray` is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its :attr:`shape <ndarray.shape>`, -which is a :class:`tuple` of *N* integers that specify the sizes of +which is a :class:`tuple` of *N* positive integers that specify the sizes of each dimension. The type of items in the array is specified by a separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which is associated with each ndarray. -As with other container objects in Python, the contents of a +As with other container objects in Python, the contents of an :class:`ndarray` can be accessed and modified by :ref:`indexing or -slicing <arrays.indexing>` the array (using for example *N* integers), +slicing <arrays.indexing>` the array (using, for example, *N* integers), and via the methods and attributes of the :class:`ndarray`. .. index:: view, base @@ -42,15 +42,19 @@ objects implementing the :class:`buffer` or :ref:`array >>> x.dtype dtype('int32') - The array can be indexed using a Python container-like syntax: + The array can be indexed using Python container-like syntax: - >>> x[1,2] + >>> x[1,2] # i.e., the element of x in the *second* row, *third* column 6 For example :ref:`slicing <arrays.indexing>` can produce views of the array: >>> y = x[:,1] - >>> y[0] = 9 + >>> y + array([2, 5]) + >>> y[0] = 9 # this also changes the corresponding element in x + >>> y + array([9, 5]) >>> x array([[1, 9, 3], [4, 5, 6]]) @@ -95,7 +99,7 @@ the bytes are interpreted is defined by the :ref:`data-type object .. index:: C-order, Fortran-order, row-major, column-major, stride, offset A segment of memory is inherently 1-dimensional, and there are many -different schemes of arranging the items of an *N*-dimensional array to +different schemes for arranging the items of an *N*-dimensional array in a 1-dimensional block. Numpy is flexible, and :class:`ndarray` objects can accommodate any *strided indexing scheme*. In a strided scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})` corresponds @@ -105,10 +109,10 @@ to the offset (in bytes) from the beginning of the memory block associated with the array. Here, :math:`s_k` are integers which specify the :obj:`strides -<ndarray.strides>` of the array. The :term:`column-major` order (used -for example in the Fortran language and in *Matlab*) and -:term:`row-major` order (used in C) are special cases of the strided -scheme, and correspond to the strides: +<ndarray.strides>` of the array. The :term:`column-major` order (used, +for example, in the Fortran language and in *Matlab*) and +:term:`row-major` order (used in C) schemes are just specific kinds of +strided scheme, and correspond to the strides: .. math:: @@ -116,12 +120,12 @@ scheme, and correspond to the strides: .. index:: single-segment, contiguous, non-contiguous -Both the C and Fortran orders are :term:`contiguous`, *i.e.* +Both the C and Fortran orders are :term:`contiguous`, *i.e.,* :term:`single-segment`, memory layouts, in which every part of the memory block can be accessed by some combination of the indices. Data in new :class:`ndarrays <ndarray>` is in the :term:`row-major` -(C) order, unless otherwise specified, but for example :ref:`basic +(C) order, unless otherwise specified, but, for example, :ref:`basic array slicing <arrays.indexing>` often produces :term:`views <view>` in a different scheme. @@ -227,7 +231,8 @@ Array methods An :class:`ndarray` object has many methods which operate on or with the array in some fashion, typically returning an array result. These -methods are explained below. +methods are briefly explained below. (Each method's doc string has a +more complete description.) For the following methods there are also corresponding functions in :mod:`numpy`: :func:`all`, :func:`any`, :func:`argmax`, @@ -433,7 +438,7 @@ Arithmetic: .. note:: - Any third argument to :func:`pow()` is silently ignored, - as the underlying :func:`ufunc <power>` only takes two arguments. + as the underlying :func:`ufunc <power>` takes only two arguments. - The three division operators are all defined; :obj:`div` is active by default, :obj:`truediv` is active when @@ -472,7 +477,7 @@ Arithmetic, in-place: the array. Therefore, for mixed precision calculations, ``A {op}= B`` can be different than ``A = A {op} B``. For example, suppose ``a = ones((3,3))``. Then, ``a += 3j`` is different than ``a = a + - 3j``: While they both perform the same computation, ``a += 3`` + 3j``: while they both perform the same computation, ``a += 3`` casts the result to fit back in ``a``, whereas ``a = a + 3j`` re-binds the name ``a`` to the result. diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst index 33d5ceff6..75daf2a08 100644 --- a/doc/source/reference/arrays.scalars.rst +++ b/doc/source/reference/arrays.scalars.rst @@ -204,8 +204,6 @@ elements the data type consists of.) :mod:`struct` module. -.. note:: XXX: what to put in the type docstrings, and where to put them? - Attributes ========== @@ -235,7 +233,6 @@ attribute. Otherwise, they share the same attributes as arrays: generic.__array_priority__ generic.__array_wrap__ -.. note:: XXX: import the documentation into the docstrings? Indexing ======== @@ -273,7 +270,6 @@ The exceptions to the above rules are given below: generic.__setstate__ generic.setflags -.. note:: XXX: import the documentation into the docstrings? Defining new types ================== diff --git a/doc/source/reference/c-api.array.rst b/doc/source/reference/c-api.array.rst index 654201d73..8ce362079 100644 --- a/doc/source/reference/c-api.array.rst +++ b/doc/source/reference/c-api.array.rst @@ -251,14 +251,16 @@ From other objects .. cfunction:: PyObject* PyArray_FromAny(PyObject* op, PyArray_Descr* dtype, int min_depth, int max_depth, int requirements, PyObject* context) This is the main function used to obtain an array from any nested - sequence, or object that exposes the array interface, ``op``. The - parameters allow specification of the required *type*, the + sequence, or object that exposes the array interface, *op*. The + parameters allow specification of the required *dtype*, the minimum (*min_depth*) and maximum (*max_depth*) number of dimensions acceptable, and other *requirements* for the array. The *dtype* argument needs to be a :ctype:`PyArray_Descr` structure indicating the desired data-type (including required byteorder). The *dtype* argument may be NULL, indicating that any - data-type (and byteorder) is acceptable. If you want to use + data-type (and byteorder) is acceptable. Unless ``FORCECAST`` is + present in ``flags``, this call will generate an error if the data + type cannot be safely obtained from the object. If you want to use ``NULL`` for the *dtype* and ensure the array is notswapped then use :cfunc:`PyArray_CheckFromAny`. A value of 0 for either of the depth parameters causes the parameter to be ignored. Any of the @@ -270,7 +272,8 @@ From other objects filled from *op* using the sequence protocol). The new array will have :cdata:`NPY_DEFAULT` as its flags member. The *context* argument is passed to the :obj:`__array__` method of *op* and is only used if - the array is constructed that way. + the array is constructed that way. Almost always this + parameter is ``NULL``. .. cvar:: NPY_C_CONTIGUOUS @@ -1001,6 +1004,24 @@ Special functions for PyArray_OBJECT Array flags ----------- +The ``flags`` attribute of the ``PyArrayObject`` structure contains +important information about the memory used by the array (pointed to +by the data member) This flag information must be kept accurate or +strange results and even segfaults may result. + +There are 6 (binary) flags that describe the memory area used by the +data buffer. These constants are defined in ``arrayobject.h`` and +determine the bit-position of the flag. Python exposes a nice +attribute- based interface as well as a dictionary-like interface for +getting (and, if appropriate, setting) these flags. + +Memory areas of all kinds can be pointed to by an ndarray, +necessitating these flags. If you get an arbitrary ``PyArrayObject`` +in C-code, you need to be aware of the flags that are set. If you +need to guarantee a certain kind of array (like ``NPY_CONTIGUOUS`` and +``NPY_BEHAVED``), then pass these requirements into the +PyArray_FromAny function. + Basic Array Flags ^^^^^^^^^^^^^^^^^ @@ -1023,6 +1044,12 @@ associated with an array. The data area is in Fortran-style contiguous order (first index varies the fastest). +Notice that contiguous 1-d arrays are always both ``NPY_FORTRAN`` +contiguous and C contiguous. Both of these flags can be checked and +are convenience flags only as whether or not an array is +``NPY_CONTIGUOUS`` or ``NPY_FORTRAN`` can be determined by the +``strides``, ``dimensions``, and ``itemsize`` attributes. + .. cvar:: NPY_OWNDATA The data area is owned by this array. @@ -1043,6 +1070,24 @@ associated with an array. The data area represents a (well-behaved) copy whose information should be transferred back to the original when this array is deleted. + This is a special flag that is set if this array represents a copy + made because a user required certain flags in + :cfunc:`PyArray_FromAny` and a copy had to be made of some other + array (and the user asked for this flag to be set in such a + situation). The base attribute then points to the "misbehaved" + array (which is set read_only). When the array with this flag set + is deallocated, it will copy its contents back to the "misbehaved" + array (casting if necessary) and will reset the "misbehaved" array + to :cdata:`NPY_WRITEABLE`. If the "misbehaved" array was not + :cdata:`NPY_WRITEABLE` to begin with then :cfunc:`PyArray_FromAny` + would have returned an error because :cdata:`NPY_UPDATEIFCOPY` + would not have been possible. + +:cfunc:`PyArray_UpdateFlags` (obj, flags) will update the +``obj->flags`` for ``flags`` which can be any of +:cdata:`NPY_CONTIGUOUS`, :cdata:`NPY_FORTRAN`, :cdata:`NPY_ALIGNED`, +or :cdata:`NPY_WRITEABLE`. + Combinations of array flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,6 +1766,29 @@ Array Functions *op1*, 2 - return all possible shifts (any overlap at all is accepted). + .. rubric:: Notes + + This does not compute the usual correlation: if op2 is larger than op1, the + arguments are swapped, and the conjugate is never taken for complex arrays. + See PyArray_Correlate2 for the usual signal processing correlation. + +.. cfunction:: PyObject* PyArray_Correlate2(PyObject* op1, PyObject* op2, int mode) + + Updated version of PyArray_Correlate, which uses the usual definition of + correlation for 1d arrays. The correlation is computed at each output point + by multiplying *op1* by a shifted version of *op2* and summing the result. + As a result of the shift, needed values outside of the defined range of + *op1* and *op2* are interpreted as zero. The mode determines how many + shifts to return: 0 - return only shifts that did not need to assume zero- + values; 1 - return an object that is the same size as *op1*, 2 - return all + possible shifts (any overlap at all is accepted). + + .. rubric:: Notes + + Compute z as follows:: + + z[k] = sum_n op1[n] * conj(op2[n+k]) + .. cfunction:: PyObject* PyArray_Where(PyObject* condition, PyObject* x, PyObject* y) If both ``x`` and ``y`` are ``NULL``, then return @@ -1901,6 +1969,96 @@ Broadcasting (multi-iterators) loop should be performed over the axis that won't require large stride jumps. +Neighborhood iterator +--------------------- + +.. versionadded:: 1.4.0 + +Neighborhood iterators are subclasses of the iterator object, and can be used +to iter over a neighborhood of a point. For example, you may want to iterate +over every voxel of a 3d image, and for every such voxel, iterate over an +hypercube. Neighborhood iterator automatically handle boundaries, thus making +this kind of code much easier to write than manual boundaries handling, at the +cost of a slight overhead. + +.. cfunction:: PyObject* PyArray_NeighborhoodIterNew(PyArrayIterObject* iter, npy_intp bounds, int mode, PyArrayObject* fill_value) + + This function creates a new neighborhood iterator from an existing + iterator. The neighborhood will be computed relatively to the position + currently pointed by *iter*, the bounds define the shape of the + neighborhood iterator, and the mode argument the boundaries handling mode. + + The *bounds* argument is expected to be a (2 * iter->ao->nd) arrays, such + as the range bound[2*i]->bounds[2*i+1] defines the range where to walk for + dimension i (both bounds are included in the walked coordinates). The + bounds should be ordered for each dimension (bounds[2*i] <= bounds[2*i+1]). + + The mode should be one of: + + * NPY_NEIGHBORHOOD_ITER_ZERO_PADDING: zero padding. Outside bounds values + will be 0. + * NPY_NEIGHBORHOOD_ITER_ONE_PADDING: one padding, Outside bounds values + will be 1. + * NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING: constant padding. Outside bounds + values will be the same as the first item in fill_value. + * NPY_NEIGHBORHOOD_ITER_MIRROR_PADDING: mirror padding. Outside bounds + values will be as if the array items were mirrored. For example, for the + array [1, 2, 3, 4], x[-2] will be 2, x[-2] will be 1, x[4] will be 4, + x[5] will be 1, etc... + * NPY_NEIGHBORHOOD_ITER_CIRCULAR_PADDING: circular padding. Outside bounds + values will be as if the array was repeated. For example, for the + array [1, 2, 3, 4], x[-2] will be 3, x[-2] will be 4, x[4] will be 1, + x[5] will be 2, etc... + + If the mode is constant filling (NPY_NEIGHBORHOOD_ITER_CONSTANT_PADDING), + fill_value should point to an array object which holds the filling value + (the first item will be the filling value if the array contains more than + one item). For other cases, fill_value may be NULL. + + - The iterator holds a reference to iter + - Return NULL on failure (in which case the reference count of iter is not + changed) + - iter itself can be a Neighborhood iterator: this can be useful for .e.g + automatic boundaries handling + - the object returned by this function should be safe to use as a normal + iterator + - If the position of iter is changed, any subsequent call to + PyArrayNeighborhoodIter_Next is undefined behavior, and + PyArrayNeighborhoodIter_Reset must be called. + + .. code-block:: c + + PyArrayIterObject \*iter; + PyArrayNeighborhoodIterObject \*neigh_iter; + iter = PyArray_IterNew(x); + + //For a 3x3 kernel + bounds = {-1, 1, -1, 1}; + neigh_iter = (PyArrayNeighborhoodIterObject*)PyArrayNeighborhoodIter_New( + iter, bounds, NPY_NEIGHBORHOOD_ITER_ZERO_PADDING, NULL); + + for(i = 0; i < iter->size; ++i) { + for (j = 0; j < neigh_iter->size; ++j) { + // Walk around the item currently pointed by iter->dataptr + PyArrayNeighborhoodIter_Next(neigh_iter); + } + + // Move to the next point of iter + PyArrayIter_Next(iter); + PyArrayNeighborhoodIter_Reset(neigh_iter); + } + +.. cfunction:: int PyArrayNeighborhoodIter_Reset(PyArrayNeighborhoodIterObject* iter) + + Reset the iterator position to the first point of the neighborhood. This + should be called whenever the iter argument given at + PyArray_NeighborhoodIterObject is changed (see example) + +.. cfunction:: int PyArrayNeighborhoodIter_Next(PyArrayNeighborhoodIterObject* iter) + + After this call, iter->dataptr points to the next point of the + neighborhood. Calling this function after every point of the + neighborhood has been visited is undefined. Array Scalars ------------- diff --git a/doc/source/reference/c-api.config.rst b/doc/source/reference/c-api.config.rst index 0c7f6b147..0989c53d7 100644 --- a/doc/source/reference/c-api.config.rst +++ b/doc/source/reference/c-api.config.rst @@ -89,8 +89,8 @@ Platform information .. versionadded:: 1.3.0 Portable alternatives to the ``endian.h`` macros of GNU Libc. - One of :cdata:`NPY_BIG_ENDIAN` :cdata:`NPY_LITTLE_ENDIAN` or - is defined, and :cdata:`NPY_BYTE_ORDER` is either 4321 or 1234. + If big endian, :cdata:`NPY_BYTE_ORDER` == :cdata:`NPY_BIG_ENDIAN`, and + similarly for little endian architectures. Defined in ``numpy/npy_endian.h``. diff --git a/doc/source/reference/c-api.coremath.rst b/doc/source/reference/c-api.coremath.rst index 8e6011603..b1a356551 100644 --- a/doc/source/reference/c-api.coremath.rst +++ b/doc/source/reference/c-api.coremath.rst @@ -69,6 +69,14 @@ Floating point classification and extended precision, and return a non 0 value is x has the signbit set (that is the number is negative). +.. cfunction:: double npy_copysign(double x, double y) + + This is a function equivalent to C99 copysign: return x with the same sign + as y. Works for any value, including inf and nan. Single and extended + precisions are available with suffix f and l. + + .. versionadded:: 1.4.0 + Useful math constants ~~~~~~~~~~~~~~~~~~~~~ @@ -114,3 +122,22 @@ precision are also available by adding the F and L suffixes respectively. .. cvar:: NPY_2_PI Two times the reciprocal of pi (:math:`\frac{2}{\pi}`) + +.. cvar:: NPY_EULER + + The Euler constant (:math:`\lim_{n\rightarrow \infty}{\sum_{k=1}^n{\frac{1}{k}} - \ln n}`) + +Linking against the core math library in an extension +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.4.0 + +To use the core math library in your own extension, you need to add the npymath +compile and link options to your extension in your setup.py: + + >>> from numpy.distutils.misc_utils import get_info + >>> info = get_info('npymath') + >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info) + +In other words, the usage of info is exactly the same as when using blas_info +and co. diff --git a/doc/source/reference/generalized_ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst index d9f3818b9..870e5dbc4 100644 --- a/doc/source/reference/generalized_ufuncs.rst +++ b/doc/source/reference/c-api.generalized-ufuncs.rst @@ -1,6 +1,6 @@ -=============================== -Generalized Universal Functions -=============================== +================================== +Generalized Universal Function API +================================== There is a general need for looping over not only functions on scalars but also over functions on vectors (or arrays), as explained on @@ -91,14 +91,14 @@ dimensions. The signature is represented by a string of the following format: * Core dimensions of each input or output array are represented by a - list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar + list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar input/output is denoted by ``()``. Instead of ``i_1``, ``i_2``, etc, one can use any valid Python variable name. * Dimension lists for different arguments are separated by ``","``. Input/output arguments are separated by ``"->"``. * If one uses the same dimension name in multiple locations, this enforces the same size (or broadcastable size) of the corresponding - dimensions. + dimensions. The formal syntax of signatures is as follows:: diff --git a/doc/source/reference/c-api.rst b/doc/source/reference/c-api.rst index 158e04a16..9bcc68b49 100644 --- a/doc/source/reference/c-api.rst +++ b/doc/source/reference/c-api.rst @@ -45,4 +45,5 @@ code. c-api.dtype c-api.array c-api.ufunc + c-api.generalized-ufuncs c-api.coremath diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index b99702e11..ece7f341b 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -917,6 +917,18 @@ PyArrayMultiIter_Type to be broadcast together. On return, the iterators are adjusted for broadcasting. +PyArrayNeighborhoodIter_Type +---------------------------- + +.. cvar:: PyArrayNeighborhoodIter_Type + + This is an iterator object that makes it easy to loop over an N-dimensional + neighborhood. + +.. ctype:: PyArrayNeighborhoodIterObject + + The C-structure corresponding to an object of :cdata:`PyArrayNeighborhoodIter_Type` is + the :ctype:`PyArrayNeighborhoodIterObject`. PyArrayFlags_Type ----------------- diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index bd0ee8e02..6a6a0dff0 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -70,43 +70,45 @@ Functions operation. Each ufunc object contains pointers to 1-d loops implementing the basic functionality for each supported type. - :param nin: - - The number of inputs to this operation. - - :param nout: - - The number of outputs - - :param ntypes: + .. note:: - How many different data-type "signatures" the ufunc has implemented. + The *func*, *data*, *types*, *name*, and *doc* arguments are not + copied by :cfunc:`PyUFunc_FromFuncAndData`. The caller must ensure + that the memory used by these arrays is not freed as long as the + ufunc object is alive. :param func: - Must to an array of length *ntypes* containing :ctype:`PyUFuncGenericFunction` items. These items are pointers to - functions that acutally implement the underlying - (element-by-element) function :math:`N` times. T + functions that actually implement the underlying + (element-by-element) function :math:`N` times. - :param types: + :param data: + Should be ``NULL`` or a pointer to an array of size *ntypes* + . This array may contain arbitrary extra-data to be passed to + the corresponding 1-d loop function in the func array. + :param types: Must be of length (*nin* + *nout*) \* *ntypes*, and it contains the data-types (built-in only) that the corresponding function in the *func* array can deal with. - :param data: + :param ntypes: + How many different data-type "signatures" the ufunc has implemented. - Should be ``NULL`` or a pointer to an array of size *ntypes* - . This array may contain arbitrary extra-data to be passed to - the corresponding 1-d loop function in the func array. + :param nin: + The number of inputs to this operation. - :param name: + :param nout: + The number of outputs + :param identity: + XXX: Undocumented + + :param name: The name for the ufunc. :param doc: - Allows passing in a documentation string to be stored with the ufunc. The documentation string should not contain the name of the function or the calling signature as that will be @@ -114,7 +116,6 @@ Functions accessing the **__doc__** attribute of the ufunc. :param check_return: - Unused and present for backwards compatibility of the C-API. A corresponding *check_return* integer does exist in the ufunc structure and it does get set with this value when the ufunc diff --git a/doc/source/reference/distutils.rst b/doc/source/reference/distutils.rst index 051a1c031..bb01a529a 100644 --- a/doc/source/reference/distutils.rst +++ b/doc/source/reference/distutils.rst @@ -67,223 +67,49 @@ misc_util files in the numpy distribution are good examples of how to use the :class:`Configuration` instance. - .. method:: todict() - - Return a dictionary compatible with the keyword arguments of distutils - setup function. Thus, this method may be used as - setup(\**config.todict()). - - .. method:: get_distribution() - - Return the distutils distribution object for self. - - .. method:: get_subpackage(subpackage_name, subpackage_path=None) - - Return a Configuration instance for the sub-package given. If - subpackage_path is None then the path is assumed to be the local path - plus the subpackage_name. If a setup.py file is not found in the - subpackage_path, then a default configuration is used. - - .. method:: add_subpackage(subpackage_name, subpackage_path=None) - - Add a sub-package to the current Configuration instance. This is - useful in a setup.py script for adding sub-packages to a package. The - sub-package is contained in subpackage_path / subpackage_name and this - directory may contain a setup.py script or else a default setup - (suitable for Python-code-only subpackages) is assumed. If the - subpackage_path is None, then it is assumed to be located in the local - path / subpackage_name. - - .. method:: self.add_data_files(*files) - - Add files to the list of data_files to be included with the package. - The form of each element of the files sequence is very flexible - allowing many combinations of where to get the files from the package - and where they should ultimately be installed on the system. The most - basic usage is for an element of the files argument sequence to be a - simple filename. This will cause that file from the local path to be - installed to the installation path of the self.name package (package - path). The file argument can also be a relative path in which case the - entire relative path will be installed into the package directory. - Finally, the file can be an absolute path name in which case the file - will be found at the absolute path name but installed to the package - path. - - This basic behavior can be augmented by passing a 2-tuple in as the - file argument. The first element of the tuple should specify the - relative path (under the package install directory) where the - remaining sequence of files should be installed to (it has nothing to - do with the file-names in the source distribution). The second element - of the tuple is the sequence of files that should be installed. The - files in this sequence can be filenames, relative paths, or absolute - paths. For absolute paths the file will be installed in the top-level - package installation directory (regardless of the first argument). - Filenames and relative path names will be installed in the package - install directory under the path name given as the first element of - the tuple. An example may clarify:: - - self.add_data_files('foo.dat', - ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']), - 'bar/cat.dat', - '/full/path/to/can.dat') - - will install these data files to:: - - <package install directory>/ - foo.dat - fun/ - gun.dat - nun/ - pun.dat - sun.dat - bar/ - car.dat - can.dat - - where <package install directory> is the package (or sub-package) - directory such as '/usr/lib/python2.4/site-packages/mypackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage') or '/usr/lib/python2.4/site- - packages/mypackage/mysubpackage' ('C: \\Python2.4 \\Lib \\site-packages \\mypackage \\mysubpackage'). - - - An additional feature is that the path to a data-file can actually be - a function that takes no arguments and returns the actual path(s) to - the data-files. This is useful when the data files are generated while - building the package. - - .. method:: add_data_dir(data_path) - - Recursively add files under data_path to the list of data_files to be - installed (and distributed). The data_path can be either a relative - path-name, or an absolute path-name, or a 2-tuple where the first - argument shows where in the install directory the data directory - should be installed to. For example suppose the source directory - contains fun/foo.dat and fun/bar/car.dat:: - - self.add_data_dir('fun') - self.add_data_dir(('sun', 'fun')) - self.add_data_dir(('gun', '/full/path/to/fun')) - - Will install data-files to the locations:: - - <package install directory>/ - fun/ - foo.dat - bar/ - car.dat - sun/ - foo.dat - bar/ - car.dat - gun/ - foo.dat - car.dat - - .. method:: add_include_dirs(*paths) - - Add the given sequence of paths to the beginning of the include_dirs - list. This list will be visible to all extension modules of the - current package. - - .. method:: add_headers(*files) - - Add the given sequence of files to the beginning of the headers list. - By default, headers will be installed under <python- - include>/<self.name.replace('.','/')>/ directory. If an item of files - is a tuple, then its first argument specifies the actual installation - location relative to the <python-include> path. - - .. method:: add_extension(name, sources, **kw) - - Create and add an Extension instance to the ext_modules list. The - first argument defines the name of the extension module that will be - installed under the self.name package. The second argument is a list - of sources. This method also takes the following optional keyword - arguments that are passed on to the Extension constructor: - include_dirs, define_macros, undef_macros, library_dirs, libraries, - runtime_library_dirs, extra_objects, swig_opts, depends, language, - f2py_options, module_dirs, and extra_info. - - The self.paths(...) method is applied to all lists that may contain - paths. The extra_info is a dictionary or a list of dictionaries whose - content will be appended to the keyword arguments. The depends list - contains paths to files or directories that the sources of the - extension module depend on. If any path in the depends list is newer - than the extension module, then the module will be rebuilt. - - The list of sources may contain functions (called source generators) - which must take an extension instance and a build directory as inputs - and return a source file or list of source files or None. If None is - returned then no sources are generated. If the Extension instance has - no sources after processing all source generators, then no extension - module is built. + .. automethod:: todict - .. method:: add_library(name, sources, **build_info) + .. automethod:: get_distribution - Add a library to the list of libraries. Allowed keyword arguments are - depends, macros, include_dirs, extra_compiler_args, and f2py_options. - The name is the name of the library to be built and sources is a list - of sources (or source generating functions) to add to the library. + .. automethod:: get_subpackage - .. method:: add_scripts(*files) + .. automethod:: add_subpackage - Add the sequence of files to the beginning of the scripts list. - Scripts will be installed under the <prefix>/bin/ directory. + .. automethod:: add_data_files - .. method:: paths(*paths) + .. automethod:: add_data_dir - Applies glob.glob(...) to each path in the sequence (if needed) and - pre-pends the local_path if needed. Because this is called on all - source lists, this allows wildcard characters to be specified in lists - of sources for extension modules and libraries and scripts and allows - path-names be relative to the source directory. + .. automethod:: add_include_dirs - .. method:: get_config_cmd() + .. automethod:: add_headers - Returns the numpy.distutils config command instance. + .. automethod:: add_extension - .. method:: get_build_temp_dir() + .. automethod:: add_library - Return a path to a temporary directory where temporary files should be - placed. + .. automethod:: add_scripts - .. method:: have_f77c() + .. automethod:: add_installed_library - True if a Fortran 77 compiler is available (because a simple Fortran - 77 code was able to be compiled successfully). + .. automethod:: add_npy_pkg_config - .. method:: have_f90c() + .. automethod:: paths - True if a Fortran 90 compiler is available (because a simple Fortran - 90 code was able to be compiled successfully) + .. automethod:: get_config_cmd - .. method:: get_version() + .. automethod:: get_build_temp_dir - Return a version string of the current package or None if the version - information could not be detected. This method scans files named - __version__.py, <packagename>_version.py, version.py, and - __svn_version__.py for string variables version, __version\__, and - <packagename>_version, until a version number is found. + .. automethod:: have_f77c - .. method:: make_svn_version_py() + .. automethod:: have_f90c - Appends a data function to the data_files list that will generate - __svn_version__.py file to the current package directory. This file - will be removed from the source directory when Python exits (so that - it can be re-generated next time the package is built). This is - intended for working with source directories that are in an SVN - repository. + .. automethod:: get_version - .. method:: make_config_py() + .. automethod:: make_svn_version_py - Generate a package __config__.py file containing system information - used during the building of the package. This file is installed to the - package installation directory. - - .. method:: get_info(*names) - - Return information (from system_info.get_info) for all of the names in - the argument list in a single dictionary. + .. automethod:: make_config_py + .. automethod:: get_info Other modules ------------- @@ -299,6 +125,83 @@ Other modules log.set_verbosity exec_command +Building Installable C libraries +================================ + +Conventional C libraries (installed through add_library) are not installed, and +are just used during the build (they are statically linked). An installable C +library is a pure C library, which does not depend on the python C runtime, and +is installed such as it may be used by third-party packages. To build and +install the C library, you just use the method add_installed_library instead of +add_library, which takes the same arguments except for an additional +install_dir argument:: + + >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib') + +npy-pkg-config files +-------------------- + +To make the necessary build options available to third parties, you could use +the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is +based on an .ini file which contains all the options. A .ini file is very +similar to .pc files as used by the pkg-config unix utility:: + + [meta] + Name: foo + Version: 1.0 + Description: foo library + + [variables] + prefix = /home/user/local + libdir = ${prefix}/lib + includedir = ${prefix}/include + + [default] + cflags = -I${includedir} + libs = -L${libdir} -lfoo + +Generally, the file needs to be generated during the build, since it needs some +information known at build time only (e.g. prefix). This is mostly automatic if +one uses the Configuration method add_npy_pkg_config. Assuming we have a +template file foo.ini.in as follows:: + + [meta] + Name: foo + Version: @version@ + Description: foo library + + [variables] + prefix = @prefix@ + libdir = ${prefix}/lib + includedir = ${prefix}/include + + [default] + cflags = -I${includedir} + libs = -L${libdir} -lfoo + +and the following code in setup.py:: + + >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib') + >>> subst = {'version': '1.0'} + >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst) + +This will install the file foo.ini into the directory package_dir/lib, and the +foo.ini file will be generated from foo.ini.in, where each @version@ will be +replaced by subst_dict['version']. The dictionary has an additional prefix +substitution rule automatically added, which contains the install prefix (since +this is not easy to get from setup.py). npy-pkg-config files can also be +installed at the same location as used for numpy, using the path returned from +get_npy_pkg_dir function. + +Reusing a C library from another package +---------------------------------------- + +Info are easily retrieved from the get_info function in numpy.distutils.misc_util:: + + >>> info = get_info('npymath') + >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info) + +An additional list of paths to look for .ini files can be given to get_info. Conversion of ``.src`` files ============================ diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 0d83053ac..00317a18e 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -19,7 +19,6 @@ For learning how to use NumPy, see also :ref:`user`. arrays ufuncs - generalized_ufuncs routines ctypes distutils @@ -37,8 +36,6 @@ the functions are written by numerous contributors and developers of Numpy, both prior to and during the `Numpy Documentation Marathon <http://scipy.org/Developer_Zone/DocMarathon2008>`__. -The Documentation Marathon is still ongoing. Please help us write -better documentation for Numpy by joining it! Instructions on how to -join and what to do can be found +Please help to improve NumPy's documentation! Instructions on how to +join the ongoing documentation marathon can be found `on the scipy.org website <http://scipy.org/Developer_Zone/DocMarathon2008>`__ - diff --git a/doc/source/reference/routines.indexing.rst b/doc/source/reference/routines.indexing.rst index f618fa0a4..9d8fde882 100644 --- a/doc/source/reference/routines.indexing.rst +++ b/doc/source/reference/routines.indexing.rst @@ -21,6 +21,13 @@ Generating index arrays ix_ ogrid unravel_index + diag_indices + diag_indices_from + mask_indices + tril_indices + tril_indices_from + triu_indices + triu_indices_from Indexing-like operations ------------------------ @@ -42,6 +49,7 @@ Inserting data into arrays place put putmask + fill_diagonal Iterating over arrays --------------------- diff --git a/doc/source/reference/routines.set.rst b/doc/source/reference/routines.set.rst index 4c298e80f..27c6aeb89 100644 --- a/doc/source/reference/routines.set.rst +++ b/doc/source/reference/routines.set.rst @@ -8,16 +8,15 @@ Making proper sets .. autosummary:: :toctree: generated/ - unique1d + unique Boolean operations ------------------ .. autosummary:: :toctree: generated/ + in1d intersect1d - intersect1d_nu setdiff1d - setmember1d setxor1d union1d diff --git a/doc/source/reference/routines.statistics.rst b/doc/source/reference/routines.statistics.rst index b41b62839..578cbd09a 100644 --- a/doc/source/reference/routines.statistics.rst +++ b/doc/source/reference/routines.statistics.rst @@ -35,6 +35,7 @@ Correlating :toctree: generated/ corrcoef + acorrelate correlate cov diff --git a/doc/source/reference/routines.testing.rst b/doc/source/reference/routines.testing.rst index 5a5f4cb8c..075c1e3a9 100644 --- a/doc/source/reference/routines.testing.rst +++ b/doc/source/reference/routines.testing.rst @@ -29,6 +29,7 @@ Decorators .. autosummary:: :toctree: generated/ + decorators.deprecated decorators.knownfailureif decorators.setastest decorators.skipif diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index d63486342..8096e1497 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -102,19 +102,24 @@ Output type determination The output of the ufunc (and its methods) is not necessarily an :class:`ndarray`, if all input arguments are not :class:`ndarrays <ndarray>`. -All output arrays will be passed to the :obj:`__array_wrap__` -method of the input (besides :class:`ndarrays <ndarray>`, and scalars) -that defines it **and** has the highest :obj:`__array_priority__` of -any other input to the universal function. The default -:obj:`__array_priority__` of the ndarray is 0.0, and the default -:obj:`__array_priority__` of a subtype is 1.0. Matrices have -:obj:`__array_priority__` equal to 10.0. +All output arrays will be passed to the :obj:`__array_prepare__` and +:obj:`__array_wrap__` methods of the input (besides +:class:`ndarrays <ndarray>`, and scalars) that defines it **and** has +the highest :obj:`__array_priority__` of any other input to the +universal function. The default :obj:`__array_priority__` of the +ndarray is 0.0, and the default :obj:`__array_priority__` of a subtype +is 1.0. Matrices have :obj:`__array_priority__` equal to 10.0. The ufuncs can also all take output arguments. The output will be cast if necessary to the provided output array. If a class with an :obj:`__array__` method is used for the output, results will be written to the object returned by :obj:`__array__`. Then, if the class -also has an :obj:`__array_wrap__` method, the returned +also has an :obj:`__array_prepare__` method, it is called so metadata +may be determined based on the context of the ufunc (the context +consisting of the ufunc itself, the arguments passed to the ufunc, and +the ufunc domain.) The array object returned by +:obj:`__array_prepare__` is passed to the ufunc for computation. +Finally, if the class also has an :obj:`__array_wrap__` method, the returned :class:`ndarray` result will be passed to that method just before passing control back to the caller. @@ -549,6 +554,7 @@ single operation. isinf isnan signbit + copysign modf ldexp frexp diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 8d8812c80..a9945a0d1 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -19,9 +19,9 @@ and classes, see :ref:`reference`. .. toctree:: :maxdepth: 2 + install howtofind basics performance misc c-info - diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst new file mode 100644 index 000000000..472ee20e3 --- /dev/null +++ b/doc/source/user/install.rst @@ -0,0 +1,148 @@ +***************************** +Building and installing NumPy +***************************** + +Binary installers +================= + +In most use cases the best way to install NumPy on your system is by using an +installable binary package for your operating system. + +Windows +------- + +Good solutions for Windows are, The Enthought Python Distribution `(EPD) +<http://www.enthought.com/products/epd.php>`_ (which provides binary installers +for Windows, OS X and Redhat) and `Python (x, y) <http://www.pythonxy.com>`_. +Both of these packages include Python, NumPy and many additional packages. +A lightweight alternative is to download the Python installer from +`www.python.org <http://www.python.org>`_ and the NumPy installer for your +Python version from the Sourceforge `download site +<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_ + +Linux +----- + +Most of the major distributions provide packages for NumPy, but these can lag +behind the most recent NumPy release. Pre-built binary packages for Ubuntu are +available on the `scipy ppa <https://edge.launchpad.net/~scipy/+archive/ppa>`_. +Redhat binaries are available in the `EPD +<http://www.enthought.com/products/epd.php>`_. + +Mac OS X +-------- + +A universal binary installer for NumPy is available from the `download site +<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_. +The `EPD <http://www.enthought.com/products/epd.php>`_ provides NumPy binaries. + +Building from source +==================== + +A general overview of building NumPy from source is given here, with detailed +instructions for specific platforms given seperately. + +Prerequisites +------------- + +Building NumPy requires the following software installed: + +1) Python 2.4.x, 2.5.x or 2.6.x + + On Debian and derivative (Ubuntu): python, python-dev + + On Windows: the official python installer at + `www.python.org <http://www.python.org>`_ is enough + + Make sure that the Python package distutils is installed before + continuing. For example, in Debian GNU/Linux, distutils is included + in the python-dev package. + + Python must also be compiled with the zlib module enabled. + +2) Compilers + + To build any extension modules for Python, you'll need a C compiler. Various + NumPy modules use FORTRAN 77 libraries, so you'll also need a FORTRAN 77 + compiler installed. + + Note that NumPy is developed mainly using GNU compilers. Compilers from other + vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, Lahey, HP, + IBM, Microsoft are only supported in the form of community feedback, and may + not work out of the box. GCC 3.x (and later) compilers are recommended. + +3) Linear Algebra libraries + + NumPy does not require any external linear algebra libraries to be installed. + However, if these are available, NumPy's setup script can detect them and use + them for building. A number of different LAPACK library setups can be used, + including optimized LAPACK libraries such as ATLAS, MKL or the + Accelerate/vecLib framework on OS X. + +FORTRAN ABI mismatch +-------------------- + +The two most popular open source fortran compilers are g77 and gfortran. +Unfortunately, they are not ABI compatible, which means that concretely you +should avoid mixing libraries built with one with another. In particular, if +your blas/lapack/atlas is built with g77, you *must* use g77 when building +numpy and scipy; on the contrary, if your atlas is built with gfortran, you +*must* build numpy/scipy with gfortran. This applies for most other cases where +different FORTRAN compilers might have been used. + +Choosing the fortran compiler +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To build with g77: + + python setup.py build --fcompiler=gnu + +To build with gfortran: + + python setup.py build --fcompiler=gnu95 + +For more information see: + + python setup.py build --help-fcompiler + +How to check the ABI of blas/lapack/atlas +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One relatively simple and reliable way to check for the compiler used to build +a library is to use ldd on the library. If libg2c.so is a dependency, this +means that g77 has been used. If libgfortran.so is a a dependency, gfortran has +been used. If both are dependencies, this means both have been used, which is +almost always a very bad idea. + +Building with ATLAS support +--------------------------- + +Ubuntu 8.10 (Intrepid) +~~~~~~~~~~~~~~~~~~~~~~ + +You can install the necessary packages for optimized ATLAS with this command: + + sudo apt-get install libatlas-base-dev + +If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should +also install the corresponding package for optimal performances. For example, +for SSE2: + + sudo apt-get install libatlas3gf-sse2 + +*NOTE*: if you build your own atlas, Intrepid changed its default fortran +compiler to gfortran. So you should rebuild everything from scratch, including +lapack, to use it on Intrepid. + +Ubuntu 8.04 and lower +~~~~~~~~~~~~~~~~~~~~~ + +You can install the necessary packages for optimized ATLAS with this command: + + sudo apt-get install atlas3-base-dev + +If you have a recent CPU with SIMD suppport (SSE, SSE2, etc...), you should +also install the corresponding package for optimal performances. For example, +for SSE2: + + sudo apt-get install atlas3-sse2 diff --git a/doc/sphinxext/README.txt b/doc/sphinxext/README.txt new file mode 100644 index 000000000..96477033b --- /dev/null +++ b/doc/sphinxext/README.txt @@ -0,0 +1,26 @@ +===================================== +numpydoc -- Numpy's Sphinx extensions +===================================== + +Numpy's documentation uses several custom extensions to Sphinx. These +are shipped in this ``numpydoc`` package, in case you want to make use +of them in third-party projects. + +The following extensions are available: + + - ``numpydoc``: support for the Numpy docstring format in Sphinx, and add + the code description directives ``np-function``, ``np-cfunction``, etc. + that support the Numpy docstring syntax. + + - ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes. + + - ``numpydoc.plot_directives``: Adaptation of Matplotlib's ``plot::`` + directive. Note that this implementation may still undergo severe + changes or eventually be deprecated. + + - ``numpydoc.only_directives``: (DEPRECATED) + + - ``numpydoc.autosummary``: (DEPRECATED) An ``autosummary::`` directive. + Available in Sphinx 0.6.2 and (to-be) 1.0 as ``sphinx.ext.autosummary``, + and it the Sphinx 1.0 version is recommended over that included in + Numpydoc. diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/docscrape.py index f374b3ddc..0e073da93 100644 --- a/doc/sphinxext/docscrape.py +++ b/doc/sphinxext/docscrape.py @@ -8,7 +8,7 @@ import re import pydoc from StringIO import StringIO from warnings import warn -4 + class Reader(object): """A line-based string reader. @@ -386,6 +386,8 @@ class NumpyDocString(object): out += self._str_see_also(func_role) for s in ('Notes','References','Examples'): out += self._str_section(s) + for param_list in ('Attributes', 'Methods'): + out += self._str_param_list(param_list) out += self._str_index() return '\n'.join(out) @@ -477,21 +479,19 @@ class ClassDoc(NumpyDocString): NumpyDocString.__init__(self, doc) + if not self['Methods']: + self['Methods'] = [(name, '', '') for name in sorted(self.methods)] + + if not self['Attributes']: + self['Attributes'] = [(name, '', '') + for name in sorted(self.properties)] + @property def methods(self): return [name for name,func in inspect.getmembers(self._cls) if not name.startswith('_') and callable(func)] - def __str__(self): - out = '' - out += super(ClassDoc, self).__str__() - out += "\n\n" - - #for m in self.methods: - # print "Parsing `%s`" % m - # out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n' - # out += '.. index::\n single: %s; %s\n\n' % (self._name, m) - - return out - - + @property + def properties(self): + return [name for name,func in inspect.getmembers(self._cls) + if not name.startswith('_') and func is None] diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/docscrape_sphinx.py index 5b60567b3..12907731e 100644 --- a/doc/sphinxext/docscrape_sphinx.py +++ b/doc/sphinxext/docscrape_sphinx.py @@ -44,6 +44,55 @@ class SphinxDocString(NumpyDocString): out += [''] return out + @property + def _obj(self): + if hasattr(self, '_cls'): + return self._cls + elif hasattr(self, '_f'): + return self._f + return None + + def _str_member_list(self, name): + """ + Generate a member listing, autosummary:: table where possible, + and a table where not. + + """ + out = [] + if self[name]: + out += ['.. rubric:: %s' % name, ''] + prefix = getattr(self, '_name', '') + + if prefix: + prefix = '~%s.' % prefix + + autosum = [] + others = [] + for param, param_type, desc in self[name]: + param = param.strip() + if not self._obj or hasattr(self._obj, param): + autosum += [" %s%s" % (prefix, param)] + else: + others.append((param, param_type, desc)) + + if autosum: + out += ['.. autosummary::', ' :toctree:', ''] + out += autosum + + if others: + maxlen_0 = max([len(x[0]) for x in others]) + maxlen_1 = max([len(x[1]) for x in others]) + hdr = "="*maxlen_0 + " " + "="*maxlen_1 + " " + "="*10 + fmt = '%%%ds %%%ds ' % (maxlen_0, maxlen_1) + n_indent = maxlen_0 + maxlen_1 + 4 + out += [hdr] + for param, param_type, desc in others: + out += [fmt % (param.strip(), param_type)] + out += self._str_indent(desc, n_indent) + out += [hdr] + out += [''] + return out + def _str_section(self, name): out = [] if self[name]: @@ -95,7 +144,7 @@ class SphinxDocString(NumpyDocString): out += [''] # Latex collects all references to a separate bibliography, # so we need to insert links to it - if sphinx.__version__ >= 0.6: + if sphinx.__version__ >= "0.6": out += ['.. only:: latex',''] else: out += ['.. latexonly::',''] @@ -127,14 +176,15 @@ class SphinxDocString(NumpyDocString): out += self._str_index() + [''] out += self._str_summary() out += self._str_extended_summary() - for param_list in ('Parameters', 'Attributes', 'Methods', - 'Returns','Raises'): + for param_list in ('Parameters', 'Returns', 'Raises'): out += self._str_param_list(param_list) out += self._str_warnings() out += self._str_see_also(func_role) out += self._str_section('Notes') out += self._str_references() out += self._str_examples() + for param_list in ('Attributes', 'Methods'): + out += self._str_member_list(param_list) out = self._str_indent(out,indent) return '\n'.join(out) @@ -144,6 +194,11 @@ class SphinxFunctionDoc(SphinxDocString, FunctionDoc): class SphinxClassDoc(SphinxDocString, ClassDoc): pass +class SphinxObjDoc(SphinxDocString): + def __init__(self, obj, doc): + self._f = obj + SphinxDocString.__init__(self, doc) + def get_doc_object(obj, what=None, doc=None): if what is None: if inspect.isclass(obj): @@ -161,5 +216,4 @@ def get_doc_object(obj, what=None, doc=None): else: if doc is None: doc = pydoc.getdoc(obj) - return SphinxDocString(doc) - + return SphinxObjDoc(obj, doc) diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc.py index 846dd7b85..707107daf 100644 --- a/doc/sphinxext/numpydoc.py +++ b/doc/sphinxext/numpydoc.py @@ -18,6 +18,7 @@ It will: import os, re, pydoc from docscrape_sphinx import get_doc_object, SphinxDocString +from sphinx.util.compat import Directive import inspect def mangle_docstrings(app, what, name, obj, options, lines, @@ -25,29 +26,29 @@ def mangle_docstrings(app, what, name, obj, options, lines, if what == 'module': # Strip top title - title_re = re.compile(r'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*', + title_re = re.compile(ur'^\s*[#*=]{4,}\n[a-z0-9 -]+\n[#*=]{4,}\s*', re.I|re.S) - lines[:] = title_re.sub('', "\n".join(lines)).split("\n") + lines[:] = title_re.sub(u'', u"\n".join(lines)).split(u"\n") else: - doc = get_doc_object(obj, what, "\n".join(lines)) + doc = get_doc_object(obj, what, u"\n".join(lines)) doc.use_plots = app.config.numpydoc_use_plots - lines[:] = str(doc).split("\n") + lines[:] = unicode(doc).split(u"\n") if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \ obj.__name__: if hasattr(obj, '__module__'): - v = dict(full_name="%s.%s" % (obj.__module__, obj.__name__)) + v = dict(full_name=u"%s.%s" % (obj.__module__, obj.__name__)) else: v = dict(full_name=obj.__name__) - lines += ['', '.. htmlonly::', ''] - lines += [' %s' % x for x in + lines += [u'', u'.. htmlonly::', ''] + lines += [u' %s' % x for x in (app.config.numpydoc_edit_link % v).split("\n")] # replace reference numbers so that there are no duplicates references = [] for line in lines: line = line.strip() - m = re.match(r'^.. \[([a-z0-9_.-])\]', line, re.I) + m = re.match(ur'^.. \[([a-z0-9_.-])\]', line, re.I) if m: references.append(m.group(1)) @@ -56,14 +57,14 @@ def mangle_docstrings(app, what, name, obj, options, lines, if references: for i, line in enumerate(lines): for r in references: - if re.match(r'^\d+$', r): - new_r = "R%d" % (reference_offset[0] + int(r)) + if re.match(ur'^\d+$', r): + new_r = u"R%d" % (reference_offset[0] + int(r)) else: - new_r = "%s%d" % (r, reference_offset[0]) - lines[i] = lines[i].replace('[%s]_' % r, - '[%s]_' % new_r) - lines[i] = lines[i].replace('.. [%s]' % r, - '.. [%s]' % new_r) + new_r = u"%s%d" % (r, reference_offset[0]) + lines[i] = lines[i].replace(u'[%s]_' % r, + u'[%s]_' % new_r) + lines[i] = lines[i].replace(u'.. [%s]' % r, + u'.. [%s]' % new_r) reference_offset[0] += len(references) @@ -78,8 +79,8 @@ def mangle_signature(app, what, name, obj, options, sig, retann): doc = SphinxDocString(pydoc.getdoc(obj)) if doc['Signature']: - sig = re.sub("^[^(]*", "", doc['Signature']) - return sig, '' + sig = re.sub(u"^[^(]*", u"", doc['Signature']) + return sig, u'' def initialize(app): try: @@ -96,6 +97,78 @@ def setup(app, get_doc_object_=get_doc_object): app.add_config_value('numpydoc_edit_link', None, True) app.add_config_value('numpydoc_use_plots', None, False) + # Extra mangling directives + name_type = { + 'cfunction': 'function', + 'cmember': 'attribute', + 'cmacro': 'function', + 'ctype': 'class', + 'cvar': 'object', + 'class': 'class', + 'function': 'function', + 'attribute': 'attribute', + 'method': 'function', + 'staticmethod': 'function', + 'classmethod': 'function', + } + + for name, objtype in name_type.items(): + app.add_directive('np-' + name, wrap_mangling_directive(name, objtype)) + +#------------------------------------------------------------------------------ +# Input-mangling directives +#------------------------------------------------------------------------------ +from docutils.statemachine import ViewList + +def get_directive(name): + from docutils.parsers.rst import directives + try: + return directives.directive(name, None, None)[0] + except AttributeError: + pass + try: + # docutils 0.4 + return directives._directives[name] + except (AttributeError, KeyError): + raise RuntimeError("No directive named '%s' found" % name) + +def wrap_mangling_directive(base_directive_name, objtype): + base_directive = get_directive(base_directive_name) + + if inspect.isfunction(base_directive): + base_func = base_directive + class base_directive(Directive): + required_arguments = base_func.arguments[0] + optional_arguments = base_func.arguments[1] + final_argument_whitespace = base_func.arguments[2] + option_spec = base_func.options + has_content = base_func.content + def run(self): + return base_func(self.name, self.arguments, self.options, + self.content, self.lineno, + self.content_offset, self.block_text, + self.state, self.state_machine) + + class directive(base_directive): + def run(self): + env = self.state.document.settings.env + + name = None + if self.arguments: + m = re.match(r'^(.*\s+)?(.*?)(\(.*)?', self.arguments[0]) + name = m.group(2).strip() + + if not name: + name = self.arguments[0] + + lines = list(self.content) + mangle_docstrings(env.app, objtype, name, None, None, lines) + self.content = ViewList(lines, self.content.parent) + + return base_directive.run(self) + + return directive + #------------------------------------------------------------------------------ # Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5) #------------------------------------------------------------------------------ diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py index f564cd670..8de8c7399 100644 --- a/doc/sphinxext/plot_directive.py +++ b/doc/sphinxext/plot_directive.py @@ -73,6 +73,7 @@ TODO """ import sys, os, glob, shutil, imp, warnings, cStringIO, re, textwrap, traceback +import sphinx import warnings warnings.warn("A plot_directive module is also available under " @@ -157,7 +158,7 @@ except ImportError: TEMPLATE = """ {{ source_code }} -.. htmlonly:: +{{ only_html }} {% if source_code %} (`Source code <{{ source_link }}>`__) @@ -188,7 +189,7 @@ TEMPLATE = """ ) {% endfor %} -.. latexonly:: +{{ only_latex }} {% for img in images %} .. image:: {{ build_dir }}/{{ img.basename }}.pdf @@ -304,11 +305,20 @@ def run(arguments, content, options, state_machine, state, lineno): opts = [':%s: %s' % (key, val) for key, val in options.items() if key in ('alt', 'height', 'width', 'scale', 'align', 'class')] + if sphinx.__version__ >= "0.6": + only_html = ".. only:: html" + only_latex = ".. only:: latex" + else: + only_html = ".. htmlonly::" + only_latex = ".. latexonly::" + result = format_template( TEMPLATE, dest_dir=dest_dir_link, build_dir=build_dir_link, source_link=source_link, + only_html=only_html, + only_latex=only_latex, options=opts, images=images, source_code=source_code) |
