[h5py] 166/455: Docs update, add announce file

Thu Jul 2 18:19:29 UTC 2015

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 cc64912fa3196f0077dbd7f34dbbfe588967465c
Author: andrewcollette <andrew.collette at gmail.com>
Date:   Fri Nov 28 22:34:42 2008 +0000

    Docs update, add announce file
---
 ANN.txt                     | 96 +++++++++++++++++++++++++++++++++++++++++++++
 docs/source/guide/hl.rst    | 23 ++++++++---
 docs/source/guide/quick.rst |  4 +-
 3 files changed, 115 insertions(+), 8 deletions(-)

diff --git a/ANN.txt b/ANN.txt
new file mode 100644
index 0000000..92c0ee3
--- /dev/null
+++ b/ANN.txt
@@ -0,0 +1,96 @@
+=====================================
+Announcing HDF5 for Python (h5py) 1.0
+=====================================
+
+What is h5py?
+-------------
+
+HDF5 for Python (h5py) is a general-purpose Python interface to the
+Hierarchical Data Format library, version 5.  HDF5 is a versatile,
+mature scientific software library designed for the fast, flexible
+storage of enormous amounts of data.
+
+From a Python programmer's perspective, HDF5 provides a robust way to
+store data, organized by name in a tree-like fashion.  You can create
+datasets (arrays on disk) hundreds of gigabytes in size, and perform
+random-access I/O on desired sections.  Datasets are organized in a
+filesystem-like hierarchy using containers called "groups", and 
+accesed using the tradional POSIX /path/to/resource syntax.
+
+Why should I use it?
+--------------------
+
+H5py provides a simple, robust read/write interface to HDF5 data
+from Python.  Existing Python and NumPy concepts are used for the
+interface; for example, datasets on disk are represented by a proxy
+class that supports slicing, and has dtype and shape attributes.
+HDF5 groups are are presented using a dictionary metaphor, indexed
+by name.
+
+A major design goal of h5py is interoperability; you can read your
+existing data in HDF5 format, and create new files that any HDF5-
+aware program can understand.  No Python-specific extensions are
+used; you're free to implement whatever file structure your application
+desires.
+
+Almost all HDF5 features are available from Python, including things
+like compound datatypes (as used with NumPy recarray types), HDF5
+attributes, hyperslab and point-based I/O, and more recent features
+in HDF 1.8 like resizable datasets and recursive iteration over entire
+files.
+
+The foundation of h5py is a near-complete wrapping of the HDF5 C API.
+HDF5 identifiers are first-class objects which participate in Python
+reference counting, and expose the C API via methods.  This low-level
+interface is also made available to Python programmers, and is
+exhaustively documented.
+
+See the Quick-Start Guide for a longer introduction with code examples:
+
+    http://h5py.alfven.org/docs/guide/quick.html
+
+Where to get it
+---------------
+
+* Main website, documentation:  http://h5py.alfven.org
+* Downloads, bug tracker:       http://h5py.googlecode.com
+
+* The HDF group website also contains a good introduction:
+  http://www.hdfgroup.org/HDF5/doc/H5.intro.html
+
+Requires
+--------
+
+* UNIX-like platform (Linux or Mac OS-X); Windows version is in progress.
+* Python 2.5 or 2.6
+* NumPy 1.0.3 or later (1.1.0 or later recommended)
+* HDF5 1.6.5 or later, including 1.8.  Some features only available
+  when compiled against HDF5 1.8.
+* Optionally, Cython (see cython.org) if you want to use custom install
+  options.  You'll need version 0.9.8.1.1 or later.
+
+About this version
+------------------
+
+Version 1.0 follows version 0.3.1 as the latest public release.  The
+major design phase (which began in May of 2008) is now over; the design
+of the high-level API will be supported as-is for the rest of the 1.X
+series, with minor enhancements.
+
+This is the first version to support Python 2.6, and the first to use
+Cython for the low-level interface.  The license remains 3-clause BSD.
+
+** This project is NOT affiliated with The HDF Group. **
+
+Thanks
+------
+
+Thanks to D. Dale, E. Lawrence and other for their continued support
+and comments.  Also thanks to the PyTables project, for inspiration
+and generously providing their code to the community, and to everyone
+at the HDF Group for creating such a useful piece of software.
+
+
+
+
+
diff --git a/docs/source/guide/hl.rst b/docs/source/guide/hl.rst
index 42810d7..6c809ee 100644
--- a/docs/source/guide/hl.rst
+++ b/docs/source/guide/hl.rst
@@ -56,7 +56,18 @@ function ``h5py.get_config()``.  This object supports the following attributes:
 Threading
 ---------
 
-H5py is now always thread-safe.
+H5py is now always thread-safe.  As HDF5 does not support thread-level
+concurrency (and as it is not necessarily thread-safe), only one thread
+at a time can acquire the lock which manages access to the library.
+
+File compatibility
+------------------
+
+HDF5 in general (and h5py in particular) tries to be as backwards-compatible
+as possible when writing new files.  However, certain combinations of dataset
+filters may cause issues when attempting to read files created with HDF5 1.8
+from an installation using HDF5 1.6.  It's generally best to use the same
+version of HDF5 for all your applications.
 
 
 Files
@@ -77,18 +88,18 @@ Valid modes (like Python's file() modes) are:
      a   Read/write if exists, create otherwise (default)
     ===  ================================================
 
-Like Python files, you must close the file when done::
+Like Python files, you should close the file when done::
 
     >>> file_obj.close()
 
 File objects can also be used as "context managers" along with the new Python
 ``with`` statement.  When used in a ``with`` block, they will be closed at
-the end of the block regardless of what exceptions have been raised::
+the end of the block, even if an exception has been raised::
 
     >>> with File('myfile.hdf5', 'r') as file_obj:
     ...    # do stuff with file_obj
     ...
-    >>> # file_obj is closed at end of block
+    >>> # file_obj is guaranteed closed at end of block
 
 .. note::
 
@@ -117,8 +128,8 @@ Reference
 
     .. method:: close()
 
-        Close the file.  You MUST do this before quitting Python or data may
-        be lost.
+        Close the file.  Like Python files, you should call this when
+        finished to be sure your data is saved.
 
     .. method:: flush()
 
diff --git a/docs/source/guide/quick.rst b/docs/source/guide/quick.rst
index c5a728e..35c5604 100644
--- a/docs/source/guide/quick.rst
+++ b/docs/source/guide/quick.rst
@@ -118,8 +118,8 @@ You can now store data in it using Numpy-like slicing syntax::
 Closing the file
 ----------------
 
-You don't need to do anything special to "close" datasets.  However, you must
-remember to close the file before exiting Python, to prevent data loss::
+You don't need to do anything special to "close" datasets.  However, as with
+Python files you should close the file before exiting::
 
     >>> dset
     Dataset "MyDataset": (2L, 3L) dtype('int32')

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

