[h5py] 452/455: Add compat file and fix sphinx warnings

[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 dc5aa8abe322bbb898f373e27c214f89038c1138
Author: andrewcollette <andrew.collette at gmail.com>
Date:   Sun Mar 14 23:14:49 2010 +0000

    Add compat file and fix sphinx warnings
---
 docs/source/api/low/h5d.rst  | 14 +++++++++
 docs/source/guide/compat.rst | 71 ++++++++++++++++++++++++++++++++++++++++++++
 docs/source/guide/hl.rst     |  1 -
 h5py/highlevel.py            |  4 ++-
 4 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/docs/source/api/low/h5d.rst b/docs/source/api/low/h5d.rst
index ea51b41..5d3a3c8 100644
--- a/docs/source/api/low/h5d.rst
+++ b/docs/source/api/low/h5d.rst
@@ -3,3 +3,17 @@ Module H5D
 
 .. automodule:: h5py.h5d
     :members:
+
+Module constants
+----------------
+
+.. _ref.h5d.ALLOC_TIME:
+
+Allocation times
+~~~~~~~~~~~~~~~~
+
+.. data:: ALLOC_TIME_DEFAULT
+.. data:: ALLOC_TIME_LATE 
+.. data:: ALLOC_TIME_EARLY
+.. data:: ALLOC_TIME_INCR  
+
diff --git a/docs/source/guide/compat.rst b/docs/source/guide/compat.rst
new file mode 100644
index 0000000..ccb5c62
--- /dev/null
+++ b/docs/source/guide/compat.rst
@@ -0,0 +1,71 @@
+*******************
+Compatibility Guide
+*******************
+
+File compatibility
+==================
+
+Types
+-----
+
+H5py now supports all native HDF5 types with the exception of generic VLENs
+and time datatypes.  When a type cannot be understood, TypeError is raised
+during conversion.
+
+Low-level protocol only
+-----------------------
+
+The files h5py writes are "plain-vanilla" HDF5.  Higher-level protocols
+(such as those which specify a mandatory series of attributes attached to
+a dataset) are not used by h5py directly.  This allows h5py to achieve a
+high degree of compatibility, at the cost of leaving higher level
+protocols to the user.
+
+LZF filter
+----------
+
+H5py includes a new high-speed compresion filter called LZF.  While a
+standalone version of this filter (written in C) is available, it is unlikely
+to be installed in many non-Python environments.  Use LZF with this in mind.
+
+SZIP filter
+-----------
+
+HDF5 includes a compression filter called SZIP as part of the standard
+distribution.  This filter contains patented software and consequently h5py
+is unable to include the compression element in our binary releases, although
+decompression of existing SZIP data is possible
+
+HDF5 1.6/1.8 compatibility
+--------------------------
+
+The files written by HDF5 1.6 and 1.8 are almost always interoperable, unless
+(in the case of a file written on 1.8) new features are used.  However, there
+are reports of third-party software (certain older versions of Matlab and
+IDL) which crash when reading a 1.8 file, even without new features.
+
+Third-party applications
+========================
+
+PyTables
+--------
+
+H5py and PyTables seem to coexist well, even in the same thread.  If you
+notice any problems, please let us know
+
+Applications which use the HDF5 error system
+--------------------------------------------
+
+In order to function properly, h5py has to install a custom error handler.  It's
+possible that a third-party program could be called from Python which does
+not like this, either installing its own error handler over h5py's (thereby
+breaking h5py), or having its handler replaced.
+
+In order to address this, the h5py error handler is only installed (1) in the
+main thread, and (2) in any thread which uses the high-level interface.
+Additionally, it can be deactivated manually by calling 
+h5py.h5e.unregister_thread() at any time.  If you encounter compatibility
+problems with third-party HDF5 client code, please let us know.
+
+
+
diff --git a/docs/source/guide/hl.rst b/docs/source/guide/hl.rst
index 2ed2310..0b75126 100644
--- a/docs/source/guide/hl.rst
+++ b/docs/source/guide/hl.rst
@@ -17,7 +17,6 @@ separately below.
     file
     group
     dataset
-    links
     attr
     refs
     vl
diff --git a/h5py/highlevel.py b/h5py/highlevel.py
index baa034e..45f058e 100644
--- a/h5py/highlevel.py
+++ b/h5py/highlevel.py
@@ -1350,7 +1350,8 @@ class Dataset(HLObject):
 
 class AttributeManager(_DictCompat):
 
-    """ Allows dictionary-style access to an HDF5 object's attributes.
+    """ 
+        Allows dictionary-style access to an HDF5 object's attributes.
 
         These are created exclusively by the library and are available as
         a Python attribute at <object>.attrs
@@ -1366,6 +1367,7 @@ class AttributeManager(_DictCompat):
         To modify an existing attribute while preserving its type, use the
         method modify().  To specify an attribute of a particular type and
         shape (or to create an empty attribute), use create().
+
     """
 
     def __init__(self, parent):

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