[h5py] 432/455: Fix stale section in docs

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to annotated tag 1.3.0
in repository h5py.

commit 9568ecbcdb16f2f11d3f514448fcb1b8e7f97fdd
Author: andrewcollette <andrew.collette at gmail.com>
Date:   Tue Feb 23 19:01:14 2010 +0000

    Fix stale section in docs
---
 docs/source/guide/refs.rst |  2 ++
 docs/source/guide/vl.rst   | 64 ++++++++++++++++++++--------------------------
 2 files changed, 30 insertions(+), 36 deletions(-)

diff --git a/docs/source/guide/refs.rst b/docs/source/guide/refs.rst
index 752f761..4f68458 100644
--- a/docs/source/guide/refs.rst
+++ b/docs/source/guide/refs.rst
@@ -1,3 +1,5 @@
+.. _refs:
+
 ==========
 References
 ==========
diff --git a/docs/source/guide/vl.rst b/docs/source/guide/vl.rst
index 8173dfc..6a6a5bd 100644
--- a/docs/source/guide/vl.rst
+++ b/docs/source/guide/vl.rst
@@ -7,6 +7,21 @@ most useful and widely used are *variable-length* (VL) types, and enumerated
 types.  As of version 1.2, h5py fully supports HDF5 enums, and has partial
 support for VL types.
 
+How special types are represented
+---------------------------------
+
+Since there is no direct NumPy dtype for variable-length strings, enums or
+references, h5py extends the dtype system slightly to let HDF5 know how to
+store these types.  Each type is represented by a native NumPy dtype, with a
+small amount of metadata attached.  NumPy routines ignore the metadata, but
+h5py can use it to determine how to store the data.
+
+There are two functions for creating these "hinted" dtypes:
+
+.. autofunction:: h5py.special_dtype
+
+.. autofunction:: h5py.check_dtype
+
 Variable-length strings
 -----------------------
 
@@ -17,61 +32,35 @@ de facto standard for representing strings in the HDF5 C API, and in many
 HDF5 applications.
 
 Thankfully, NumPy has a generic pointer type in the form of the "object" ("O")
-dtype.  In h5py 1.2, variable-length strings are mapped to object arrays.  A
+dtype.  In h5py, variable-length strings are mapped to object arrays.  A
 small amount of metadata attached to an "O" dtype tells h5py that its contents
 should be converted to VL strings when stored in the file.
 
-
 Existing VL strings can be read and written to with no additional effort; 
 Python strings and fixed-length NumPy strings can be auto-converted to VL
-data and stored.  However, creating VL data requires the use of a special
-"hinted" dtype object.  Two functions are provided at the package level for
-this purpose:
-
-.. function:: h5py.new_vlen(basetype) -> dtype
-
-    Create a new object dtype which represents a VL type.  Currently
-    *basetype* must be the Python string type (str).
-
-.. function:: h5py.get_vlen(dtype) -> dtype or None
-
-    Get the base type of a variable-length dtype, or None if *dtype*
-    doesn't represent a VL type.
+data and stored.
 
 Here's an example showing how to create a VL array of strings::
 
     >>> f = h5py.File('foo.hdf5')
-    >>> dt = h5py.new_vlen(str)
+    >>> dt = h5py.special_dtype(vlen=str)
     >>> ds = f.create_dataset('VLDS', (100,100), dtype=dt)
     >>> ds.dtype.kind
-    ... 'O'
-    >>> h5py.get_vlen(ds.dtype)
-    ... <type 'str'>
+    'O'
+    >>> h5py.check_dtype(vlen=ds.dtype)
+    <type 'str'>
 
 Enumerated types
 ----------------
 
 HDF5 has the concept of an *enumerated type*, which is an integer datatype
 with a restriction to certain named values.  Since NumPy has no such datatype,
-HDF5 ENUM types are read and written as integers.  Like variable-length
-strings, you can create a new enumerated type from a NumPy integer base type
-by using convenience functions to attach a small amount of metadata:
-
-.. function:: h5py.new_enum(dtype, values) -> dtype
-
-    Create a new enumerated type, from a NumPy integer dtype and a dictionary
-    of {"name": value} pairs.  Keys must be strings, and values must be
-    integers.
-
-.. function:: h5py.get_enum(dtype) -> dict or None
-
-    Extract the name/value dictionary from an existing enum dtype.  Returns
-    None if the dtype does not contain metadata.
+HDF5 ENUM types are read and written as integers.
 
-Here's an example::
+Here's an example of creating an enumerated type::
 
-    >>> dt = h5py.new_enum('i', {"RED": 0, "GREEN": 1, "BLUE": 42})
-    >>> h5py.get_enum(dt)
+    >>> dt = h5py.special_dtype(enum=('i', {"RED": 0, "GREEN": 1, "BLUE": 42}))
+    >>> h5py.check_dtype(enum=dt)
     {'BLUE': 42, 'GREEN': 1, 'RED': 0}
     >>> f = h5py.File('foo.hdf5','w')
     >>> ds = f.create_dataset("EnumDS", (100,100), dtype=dt)
@@ -83,7 +72,10 @@ Here's an example::
     >>> ds[1,0]
     0
 
+References
+----------
 
+References have their :ref:`own section <refs>`.
 
 
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git