[Numpy-svn] r5166 - in trunk/numpy: . core lib

[numpy-svn at scipy.org]

Author: stefan
Date: 2008-05-14 07:51:23 -0500 (Wed, 14 May 2008)
New Revision: 5166

Modified:
   trunk/numpy/__init__.py
   trunk/numpy/core/defmatrix.py
   trunk/numpy/lib/io.py
Log:
Merge docstrings from wiki.


Modified: trunk/numpy/__init__.py
===================================================================
--- trunk/numpy/__init__.py	2008-05-14 05:57:52 UTC (rev 5165)
+++ trunk/numpy/__init__.py	2008-05-14 12:51:23 UTC (rev 5166)
@@ -1,14 +1,65 @@
 """
 NumPy
-==========
+=====
+
 Provides
-   1) An array object of arbitrary homogeneous items
-   2) Fast mathematical operations over arrays
-   3) Linear Algebra, Fourier Transforms, Random Number Generation
+  1. An array object of arbitrary homogeneous items
+  2. Fast mathematical operations over arrays
+  3. Linear Algebra, Fourier Transforms, Random Number Generation
 
-Documentation is available in the docstrings and at
+Documentation is available in the docstrings and at http://www.scipy.org
 
-http://www.scipy.org
+Available subpackages
+---------------------
+core
+    Defines a multi-dimensional array and useful procedures
+    for Numerical computation.
+lib
+    Basic functions used by several sub-packages and useful
+    to have in the main name-space.
+random
+    Core Random Tools
+linalg
+    Core Linear Algebra Tools
+fft
+    Core FFT routines
+testing
+    Numpy testing tools
+
+The following sub-packages must be explicitly imported:
+
+f2py
+    Fortran to Python Interface Generator.
+distutils
+    Enhancements to distutils with support for
+    Fortran compilers support and more.
+
+
+Global symbols from subpackages
+-------------------------------
+========  =================================
+core      all (use numpy.* not numpy.core.*)
+lib       all (use numpy.* not numpy.lib.*)
+testing   NumpyTest
+========  =================================
+
+
+Utility tools
+-------------
+
+test
+    Run numpy unittests
+pkgload
+    Load numpy packages
+show_config
+    Show numpy build configuration
+dual
+    Overwrite certain functions with high-performance Scipy tools
+matlib
+    Make everything matrices.
+__version__
+    Numpy version string
+
 """
 
 # We first need to detect if we're being called as part of the numpy setup

Modified: trunk/numpy/core/defmatrix.py
===================================================================
--- trunk/numpy/core/defmatrix.py	2008-05-14 05:57:52 UTC (rev 5165)
+++ trunk/numpy/core/defmatrix.py	2008-05-14 12:51:23 UTC (rev 5166)
@@ -125,19 +125,20 @@
 
 
 class matrix(N.ndarray):
-    """mat = matrix(data, dtype=None, copy=True)
+    """
+    mat = matrix(data, dtype=None, copy=True)
 
     Returns a matrix from an array-like object, or a string of
     data.  A matrix is a specialized 2-d array that retains
-    it's 2-d nature through operations and where '*' means matrix
+    its 2-d nature through operations and where '*' means matrix
     multiplication and '**' means matrix power.
 
     Parameters
     ----------
     data : array-like or string
        If data is a string, then interpret the string as a matrix
-         with commas or spaces separating columns and semicolons
-         separating rows.
+       with commas or spaces separating columns and semicolons
+       separating rows.
        If data is array-like than convert the array to a matrix.
     dtype : data-type
        Anything that can be interpreted as a NumPy datatype.
@@ -152,6 +153,7 @@
     >>> print a
     [[1 2]
      [3 4]]
+
     """
     __array_priority__ = 10.0
     def __new__(subtype, data, dtype=None, copy=True):
@@ -532,18 +534,22 @@
 
 
 def bmat(obj, ldict=None, gdict=None):
-    """Build a matrix object from string, nested sequence, or array.
+    """
+    Build a matrix object from string, nested sequence, or array.
 
-    Example
+    Examples
     --------
-    F = bmat('A, B; C, D')
-    F = bmat([[A,B],[C,D]])
-    F = bmat(r_[c_[A,B],c_[C,D]])
+    >>> F = bmat('A, B; C, D')
+    >>> F = bmat([[A,B],[C,D]])
+    >>> F = bmat(r_[c_[A,B],c_[C,D]])
 
-    all produce the same Matrix Object    [ A  B ]
-                                          [ C  D ]
+    All of these produce the same matrix::
 
+        [ A  B ]
+        [ C  D ]
+
     if A, B, C, and D are appropriately shaped 2-d arrays.
+
     """
     if isinstance(obj, str):
         if gdict is None:

Modified: trunk/numpy/lib/io.py
===================================================================
--- trunk/numpy/lib/io.py	2008-05-14 05:57:52 UTC (rev 5165)
+++ trunk/numpy/lib/io.py	2008-05-14 12:51:23 UTC (rev 5166)
@@ -428,7 +428,9 @@
 
 import re
 def fromregex(file, regexp, dtype):
-    """Construct an array from a text file, using regular-expressions parsing.
+    """
+    Construct a record array from a text file, using
+    regular-expressions parsing.
 
     Array is constructed from all matches of the regular expression
     in the file. Groups in the regular expression are converted to fields.
@@ -436,19 +438,20 @@
     Parameters
     ----------
     file : str or file
-        File name or file object to read
+        File name or file object to read.
     regexp : str or regexp
-        Regular expression to use to parse the file
+        Regular expression used to parse the file.
+        Groups in the regular expression correspond to fields in the dtype.
     dtype : dtype or dtype list
         Dtype for the structured array
 
-    Example
-    -------
-    >>> import numpy as np
+    Examples
+    --------
     >>> f = open('test.dat', 'w')
-    >>> f.write("1312 foo\n1534  bar\n 444   qux")
+    >>> f.write("1312 foo\\n1534  bar\\n444   qux")
     >>> f.close()
-    >>> np.fromregex('test.dat', r"(\d+)\s+(...)", [('num', np.int64), ('key', 'S3')])
+    >>> np.fromregex('test.dat', r"(\\d+)\\s+(...)",
+    ...              [('num', np.int64), ('key', 'S3')])
     array([(1312L, 'foo'), (1534L, 'bar'), (444L, 'qux')],
           dtype=[('num', '<i8'), ('key', '|S3')])