[h5py] 138/455: Doc fixes, move version info
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:26 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 70f31dead697e3af1a2c48c38f9c85f41e6e829e
Author: andrewcollette <andrew.collette at gmail.com>
Date: Thu Oct 16 23:26:07 2008 +0000
Doc fixes, move version info
---
docs/source/build.rst | 2 +
docs/source/index.rst | 38 ++++++------
docs/source/quick.rst | 155 +++++++++++++++++++++++++++++++------------------
h5py/__init__.py | 15 +++--
h5py/h5.pyx | 10 +---
h5py/tests/__init__.py | 2 +-
h5py/tests/test_h5.py | 10 +---
7 files changed, 137 insertions(+), 95 deletions(-)
diff --git a/docs/source/build.rst b/docs/source/build.rst
index 17912c3..8850943 100644
--- a/docs/source/build.rst
+++ b/docs/source/build.rst
@@ -42,6 +42,8 @@ Procedure
3. Run ``python setup.py test`` to run unit tests in-place (optional)
4. Run ``sudo python setup.py install`` to install into your main Python
package directory.
+5. ``cd`` out of the installation directory before importing h5py, to prevent
+ Python from trying to run from the source folder.
Additional options
------------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 7ed6f6d..70ba088 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -3,31 +3,33 @@
Python bindings for the HDF5 library
====================================
-The h5py package provides both a high- and low-level interface to the
-`HDF5 library`__ from Python. The low-level interface is
-intended to be a complete wrapping of the HDF5 1.6 API, while the high-
-level component supports Python-style object-oriented access to HDF5 files,
-datasets and groups.
+The `HDF5 library`__ is a versatile, mature library designed for the storage
+of numerical data. The h5py package provides a simple, Pythonic interface to
+HDF5. A straightforward high-level interface allows the manipulation of
+HDF5 files, groups and datasets using established Python and NumPy metaphors.
__ http://www.hdfgroup.com/HDF5
-The goal of this package is not to provide yet another scientific data
-model. It is an attempt to create as straightforward a binding as possible
-to the existing HDF5 API and abstractions, so that Python programs can
-easily deal with HDF5 files and exchange data with other HDF5-aware
-applications.
+Additionally, the library offers a low-level interface which exposes the
+majority of the HDF5 C API in a Pythonic, object-oriented fashion. This
+interface is documented `separately`__.
-Important links:
- * `Main project page`__
- * `Auto-generated API docs`__
- * `Google Code development page`__
- * `Windows installers`__
- * Mail: "h5py" at the domain "alfven" dot "org"
+__ http://h5py.alfven.org/docs
+
+The major design goals for h5py are simplicity and interoperability. You don't
+need to learn any new concepts beyond the basic principles of HDF5 and NumPy
+arrays, and the files you create with h5py can be opened with any other
+HDF5-aware program.
+
+* `Downloads for Unix/Windows, and bug tracker (Google Code)`__
+* `Alternate Windows installers`__
+* `Low-level API documentation`__
+
+* Mail: "h5py" at the domain "alfven" dot "org"
-__ http://h5py.alfven.org
-__ http://h5py.alfven.org/docs/
__ http://h5py.googlecode.com
__ http://h5py.alfven.org/windows/
+__ http://h5py.alfven.org/docs/
Contents:
diff --git a/docs/source/quick.rst b/docs/source/quick.rst
index 45f55e9..0ce2108 100644
--- a/docs/source/quick.rst
+++ b/docs/source/quick.rst
@@ -2,6 +2,46 @@
Quick Start Guide
*****************
+What is HDF5?
+=============
+
+It's a filesystem for your data.
+
+Only two kinds of objects are stored in HDF5 files:
+*datasets*, which are homogenous, regular arrays of data (just like
+NumPy arrays), and *groups*, which are containers that store datasets and
+other groups. Each file is organized using a filesystem metaphor; groups
+are like folders, and datasets are like files. The syntax for accessing
+objects in the file is the traditional POSIX filesystem syntax. Here
+are some examples::
+
+ / (Root group)
+ /MyGroup (Subgroup)
+ /MyGroup/DS1 (Dataset stored in subgroup)
+ /MyGroup/Subgroup/DS2 (and so on)
+
+What is h5py?
+=============
+
+It's a simple Python interface to HDF5. You can interact with files, groups
+and datasets using traditional Python and NumPy metaphors. For example,
+groups behave like dictionaries, and datasets have shape and dtype attributes,
+and can be sliced and indexed just like real NumPy arrays. Datatypes are
+specified using standard NumPy dtype objects.
+
+You don't need to know anything about the HDF5 library to use h5py, apart from
+the basic metaphors of files, groups and datasets. The library handles all
+data conversion transparently, and datasets support advanced features like
+efficient multidimensional indexing and nested compound datatypes.
+
+One additional benefit of h5py is that the files it reads and writes are
+"plain-vanilla" HDF5 files. No Python-specific metadata or features are used.
+You can read HDF5 files created by any application, and write files that any
+HDF5-aware application can understand.
+
+Getting data into HDF5
+======================
+
First, install h5py by following the `installation instructions`__.
__ http://h5py.alfven.org/build.html
@@ -14,10 +54,6 @@ The rest of the examples here assume you've done this. Among other things, it
imports the three classes ``File``, ``Group`` and ``Dataset``, which will cover
99% of your needs.
-
-Getting data into HDF5
-======================
-
Create a new file
-----------------
@@ -29,14 +65,18 @@ Files are opened using a Python-file-like syntax::
>>> type(f)
<class 'h5py.highlevel.File'>
+In the filesystem metaphor of HDF5, the file object does double duty as the
+*root group* (named "/" like its POSIX counterpart). You can store datasets
+in it directly, or create subgroups to keep your data better organized.
+
Create a dataset
----------------
(Main chapter: :ref:`Datasets`)
-Datasets are like Numpy arrays which reside on disk; they are identified by
-a unique name, shape, and a Numpy dtype. The easiest way to create them is
-with a method of the File object you already have::
+Datasets are like Numpy arrays which reside on disk; they are associated with
+a name, shape, and a Numpy dtype. The easiest way to create them is with a
+method of the File object you already have::
>>> dset = f.create_dataset("MyDataset", (2,3), '=i4')
>>> dset
@@ -45,7 +85,7 @@ with a method of the File object you already have::
<class 'h5py.highlevel.Dataset'>
This creates a new 2-d 6-element (2x3) dataset containing 32-bit signed integer
-data, in native byte order, located in the file at "/MyDataset".
+data, in native byte order, located in the root group at "/MyDataset".
Or you can auto-create a dataset from an array, just by giving it a name:
@@ -63,7 +103,7 @@ Shape and dtype information is always available via properties:
Read & write data
-----------------
-You can now store data in it using the Numpy-like slicing syntax::
+You can now store data in it using Numpy-like slicing syntax::
>>> print dset[...]
[[0 0 0]
@@ -79,8 +119,7 @@ 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. This
-will automatically close all the open HDF5 objects::
+remember to close the file before exiting Python, to prevent data loss::
>>> dset
Dataset "MyDataset": (2L, 3L) dtype('int32')
@@ -92,18 +131,15 @@ will automatically close all the open HDF5 objects::
Groups & multiple objects
=========================
-Like a filesystem, HDF5 supports the concept of storing multiple objects in
-containers, called "groups". The File object behaves as one of these
-groups (it's actually the *root group* "``/``", again like a UNIX filesystem).
-You store objects by giving them different names:
+You've already seen that every object in a file is identified by a name:
- >>> f["DS1"] = numpy.ones((2,3))
- >>> f["DS2"] = numpy.ones((1,2))
+ >>> f["DS1"] = numpy.ones((2,3)) # full name "/DS1"
+ >>> f["DS2"] = numpy.ones((1,2)) # full name "/DS2"
>>> f
File "myfile.hdf5", root members: "DS1", "DS2"
-As with other Python container objects, they support iteration and membership
-testing:
+Groups, including the root group ("f", in this example), act somewhat like
+Python dictionaries. They support iteration and membership testing:
>>> list(f)
['DS1', 'DS2']
@@ -125,47 +161,34 @@ You can "delete" (unlink) an object from a group::
>>> "DS" in f
False
-You create additional subgroups by giving them names:
+Most importantly, you can create additional subgroups by giving them names:
- >>> f.create_group('subgrp')
+ >>> g = f.create_group('subgrp')
+ >>> g
Group "subgrp" (0 members)
-
-.. note::
-
- Most HDF5 versions don't support automatic creation of intermediate
- groups; you can't yet do ``f.create_group('foo/bar/baz')``.
-
-
-Group caveats
--------------
+ >>> g.name
+ '/subgrp'
+ >>> dset = g.create_dataset("DS3", (10,10))
+ >>> dset.name
+ '/subgrp/DS3'
-The HDF5 file graph is not limited to a tree configuration. Like hard links in
-a file system, group "members" are actually references to shared HDF5 objects.
-This can lead to odd behavior; for example, it's perfectly legal for a group
-to contain itself. When you assign an existing HDF5 object to a name, HDF5
-will create a new reference (hard link) with that name, which points to the
-object.
+Using this feature you can build up an entire virtual filesystem inside an
+HDF5 file. This hierarchical organization is what gives HDF5 its name.
- >>> dset = f.create_dataset("MyDS", (1,2), '=i2')
- >>> f["DS Alias"] = dset # creates a new hard link
-
-Recursion:
+.. note::
- >>> f["self"] = f
- >>> f.names
- ("self",)
- >>> f["self"].names
- ("self",)
- >>> f["self/self"].names
- ("self",)
+ Most HDF5 versions don't support automatic creation of intermediate
+ groups; you can't yet do ``f.create_group('foo/bar/baz')`` unless both
+ groups "foo" and "bar" already exist.
-While this has many benefits (many paths can share the same underlying data),
-you should be careful not to get yourself into trouble.
Attributes
==========
HDF5 lets you associate small bits of data with both groups and datasets.
+This can be used for metadata like descriptive titles, timestamps, or any
+other purpose you want.
+
A dictionary-like object which exposes this behavior is attached to every
Group and Dataset object as the attribute ``attrs``. You can store any scalar
or array value you like::
@@ -175,16 +198,30 @@ or array value you like::
Attributes of "MyDS": (none)
>>> dset.attrs["Name"] = "My Dataset"
>>> dset.attrs["Frob Index"] = 4
- >>> dset.attrs["Baz Order"] = numpy.arange(10)
+ >>> dset.attrs["Order Array"] = numpy.arange(10)
>>> for name, value in dset.attrs.iteritems():
- ... print name, value
+ ... print name+":", value
...
- Name My Dataset
- Frob Index 4
- Baz Order [0 1 2 3 4 5 6 7 8 9]
+ Name: My Dataset
+ Frob Index: 4
+ Order Array: [0 1 2 3 4 5 6 7 8 9]
+
+
+Named datatypes
+===============
-Attributes can be associated with any named HDF5 object, including the root
-group.
+There is in fact one additional, rarely-used kind of object which can be
+permanently stored in an HDF5 file. You can permanently store a *datatype*
+object in any group, simply by assigning a NumPy dtype to a name:
+
+ >>> f["MyIntegerDatatype"] = numpy.dtype('<i8')
+ >>> htype = f["MyIntegerDatatype"]
+ >>> htype.dtype
+ dtype('int64')
+
+This isn't ordinarily useful because each dataset already carries its own
+dtype attribute. However, if you want to store datatypes which are not used
+in any dataset, this is the right way to do it.
More information
================
@@ -196,6 +233,12 @@ module.
__ http://h5py.alfven.org/docs/
+The `HDF Group`__ website is the final authority on HDF5. Their `user
+manual`__ is a great introduction to the basic concepts of HDF5, albeit from
+the perspective of a C programmer.
+
+__ http://www.hdfgroup.org/HDF5/
+__ http://www.hdfgroup.org/HDF5/doc/UG/index.html
diff --git a/h5py/__init__.py b/h5py/__init__.py
index e9d3d2e..8ea1225 100644
--- a/h5py/__init__.py
+++ b/h5py/__init__.py
@@ -21,18 +21,25 @@ __doc__ = \
HDF5 %s (using %s API)
"""
+try:
+ import h5
+except ImportError:
+ import os.path as op
+ if op.exists('setup.py'):
+ raise ImportError("Exit source directory before importing h5py")
+ raise
-import utils, h5, h5a, h5d, h5f, h5g, h5i, h5p, h5r, h5s, h5t, h5z, highlevel
+import utils, h5, h5a, h5d, h5f, h5g, h5i, h5p, h5r, h5s, h5t, h5z, highlevel, version
from highlevel import File, Group, Dataset, Datatype, AttributeManager, CoordsList
-__doc__ = __doc__ % (h5.version, h5.hdf5_version, h5.api_version)
+__doc__ = __doc__ % (version.version, version.hdf5_version, version.api_version)
__all__ = ['h5', 'h5f', 'h5g', 'h5s', 'h5t', 'h5d', 'h5a', 'h5p', 'h5r',
- 'h5z', 'h5i', 'File', 'Group', 'Dataset',
+ 'h5z', 'h5i', 'version', 'File', 'Group', 'Dataset',
'Datatype', 'AttributeManager', 'CoordsList']
-if h5.api_version_tuple >= (1,8):
+if version.api_version_tuple >= (1,8):
import h5o, h5l
__all__ += ['h5l', 'h5o']
diff --git a/h5py/h5.pyx b/h5py/h5.pyx
index 68fac6e..b1395fd 100644
--- a/h5py/h5.pyx
+++ b/h5py/h5.pyx
@@ -721,13 +721,9 @@ init_hdf5()
# === Module init =============================================================
-hdf5_version_tuple = get_libversion()
-hdf5_version = "%d.%d.%d" % hdf5_version_tuple
-api_version_tuple = (int(H5PY_API/10), H5PY_API%10)
-api_version = "%d.%d" % api_version_tuple
-
-version = H5PY_VERSION
-version_tuple = tuple([int(x) for x in version.split('.')])
+_hdf5_version_tuple = get_libversion()
+_api_version_tuple = (int(H5PY_API/10), H5PY_API%10)
+_version_tuple = tuple([int(x) for x in H5PY_VERSION.split('.')])
diff --git a/h5py/tests/__init__.py b/h5py/tests/__init__.py
index 712ca7d..58a71d2 100644
--- a/h5py/tests/__init__.py
+++ b/h5py/tests/__init__.py
@@ -68,7 +68,7 @@ def runtests(requests=None, verbosity=1):
retval = unittest.TextTestRunner(verbosity=verbosity).run(suite)
if verbosity >= 1:
- print "=== Tested HDF5 %s (%s API) ===" % (h5.hdf5_version, h5.api_version)
+ print "=== Tested HDF5 %s (%s API) ===" % (version.hdf5_version, version.api_version)
return retval.wasSuccessful()
def autotest():
diff --git a/h5py/tests/test_h5.py b/h5py/tests/test_h5.py
index 44ca28f..f5b6bd6 100644
--- a/h5py/tests/test_h5.py
+++ b/h5py/tests/test_h5.py
@@ -14,12 +14,4 @@ import unittest
from h5py import h5
class TestH5(unittest.TestCase):
-
- def test_version(self):
- # For 1.6 API
- tpl = h5.get_libversion()
-
- self.assertEqual(tpl, h5.hdf5_version_tuple)
- self.assertEqual("%d.%d.%d" % tpl, h5.hdf5_version)
- h5.api_version
- h5.api_version_tuple
+ pass
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git
More information about the debian-science-commits
mailing list