[h5py] 69/455: README update
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:18 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 782d1d38673b5954316cc1dfd0593367a31036ff
Author: andrewcollette <andrew.collette at gmail.com>
Date: Mon Jul 7 23:46:59 2008 +0000
README update
---
README.txt | 263 ++++++++++---------------------------------
h5py/browse.py | 2 +-
h5py/highlevel.py | 32 +++++-
h5py/tests/__init__.py | 4 +-
h5py/tests/test_highlevel.py | 40 +------
setup.py | 12 +-
6 files changed, 96 insertions(+), 257 deletions(-)
diff --git a/README.txt b/README.txt
index 7e02851..4a7aace 100644
--- a/README.txt
+++ b/README.txt
@@ -1,10 +1,11 @@
README for the "h5py" Python/HDF5 interface
===========================================
Copyright (c) 2008 Andrew Collette
+
* http://h5py.alfven.org
* mail: "h5py" at the domain "alfven dot org"
-Version 0.1.1
+Version 0.2.0
Introduction
============
@@ -17,27 +18,16 @@ datasets and groups.
__ http://hdf.ncsa.uiuc.edu
-DISCLAIMER
-==========
-
-This is an early release of h5py. Many functions are untested, and it's
-quite possible that both the high- and low-level APIs will change in the
-future. Also, it hasn't been tested on platforms other than 32-bit x86
-Linux. For these reasons, you should treat it as an alpha.
-
-Contents
-========
-
-* `Introduction`_
-* `Features`_
-* `Installation`_
-* `High-level interface`_
-* `Low-level interface`_
+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.
Documentation
-------------
Extensive documentation is available through docstrings, as well as in
-`HTML format on the web`__ and in the "docs/" directory in this
+`HTML format on the web`__ and in the "docs/" directory in the
distribution. This document is an overview of some of the package's
features and highlights.
@@ -46,75 +36,71 @@ __ http://h5py.alfven.org
Features
========
-- Low-level wrappings for most of the HDF5 1.6 C api. You can call H5*
- functions directly from Python. The wrapped APIs are:
+High-Level
+----------
- ===== ============== =================
- HDF5 Purpose Wrapping
- ===== ============== =================
- H5A Attributes Module h5a
- H5F Files Module h5f
- H5D Datasets Module h5d
- H5G Groups Module h5g
- H5T Datatypes Module h5t
- H5S Dataspaces Module h5s
- H5I Inspection Module h5i
- H5Z Filters Module h5z
- H5P Property lists Module h5p
- H5E Errors Python exceptions
- ===== ============== =================
+- Numpy-style access to HDF5 datasets, with automatic conversion between
+ datatypes. Slice into an HDF5 dataset and get a Numpy array back.
+ Create and use datasets with chunking, compression, or other filters
+ transparently.
- See the section `Low-level interface`_ below for a better overview.
+- Command-line browsing of HDF5 files, including the capability to import
+ HDF5 objects into an interactive Python session.
-- Calls that fail will raise exceptions; no more checking return values.
- Wrapper functions have been carefully designed to provide a Pythonic
- interface to the library. Where multiple similar HDF5 functions exist
- (i.e. link and link2) they have been merged into one function, with
- additional Python keywords.
+- Dictionary-style access to HDF5 groups and attributes, including
+ iteration.
-- Many new, C-level Python functions which smooth some of the rough edges.
- For example, you can create a dataset with associated compression and
- chunking in one function call, get an iterator over the names in a group,
- overwrite attributes without deleting them first, etc.
+- Automatic creation of HDF5 datasets, named types and hard links, by
+ dictionary-style assignment. For example, Group["Name"] = <Numpy array>
+ creates a dataset.
-- Conversion functions between HDF5 datatypes and Numpy dtypes, including
- Numpy's complex numbers. This lets you read/write data directly from an
- HDF5 dataset to a Numpy array, with the HDF5 library performing any
- endianness or precision conversion for you automatically.
+Low-Level
+---------
+
+- Low-level wrappings for most of the HDF5 1.6 C API, divided in an
+ intuitive fashion across modules like h5a, h5d, h5s, etc.
+
+- No more micro-managing of identifiers; a minimal object layer on top of
+ HDF5 integer identifiers means you don't need to remember to close
+ every single identifier you create.
-- High-level interface allows Numpy/Python-style access to HDF5 files and
- datasets, with automatic conversion between datatypes. Slice into an
- HDF5 dataset and get a Numpy array back; no extra work required. You can
- also create datasets which use chunking, compression, or other filters,
- and use them like any other dataset object.
+- Most API functions are presented as methods on object identifiers, rather
+ than functions. In addition to being more Pythonic, this makes programs
+ less verbose and objects easier to inspect from the command line.
-- High-level Group interface allows dictionary-style manipulation of HDF5
- groups and links, including automatic creation of datasets and attributes
- in response to assignment.
+- Automatic exception handling; using the HDF5 error callback mechanism,
+ Python exceptions are raised by the library itself when errors occur.
+ Many new exception classes are provided, based on the HDF5 major error
+ codes.
-- No additional layers of abstraction beyond the HDF5 and Numpy conventions.
- I like PyTables a lot, but I don't speak database-ese. :) There are also
- no new datatypes; just the built-in Numpy ones.
+- Minimal changes to the HDF5 API:
+ - A near-1:1 mapping between HDF5 functions and h5py functions/methods
+ - Constants have their original names; H5P_DEFAULT becomes h5p.DEFAULT
+ - Python extensions are provided only when not doing so would be
+ obviously wrong; you don't need to learn a totally new API
+ - The majority of the HDF5 C-API documentation is still valid for the
+ h5py interface
Installation
============
-Since this is an early release of h5py, only installation from source is
-currently supported. However, Python's distutils makes this relatively
-painless, assuming you have correctly installed the prerequisite packages.
-If possible, it's strongly recommended you use the versions of these
-packages provided by your operating system's package manager/finder.
+
+The h5py package is designed to be installed from source. You will need
+Python and a C compiler, for distutils to build the extensions. Pyrex_ is
+not required unless you want to change compile-time options, like the
+debugging level.
+
+It's strongly recommended you use the versions of these packages provided
+by your operating system's package manager/finder. In particular, HDF5 can
+be painful to install manually.
Requires
--------
- Unix-like environment (created/tested on 32-bit Intel linux)
- Numpy_ 1.0.3 or higher
- HDF5_ 1.6.5 or higher (1.8 support experimental)
-- Pyrex_ 0.9.6.4 or higher
-- gcc (to compile Python extensions)
-
-You might also need to install "libc6-dev" if it's not included by default
-with your OS. If you get compile-time errors about "limits.h", this is why.
+- A working compiler for distutils
+- (Optionally) Pyrex_ 0.9.8.4 or higher
.. _Numpy: http://numpy.scipy.org/
.. _HDF5: http://hdf.ncsa.uiuc.edu/
@@ -130,140 +116,7 @@ Procedure
Bugs
----
-I expect there are many. :) A FAQ page will soon be created at the project
-hosting wiki (http://h5py.googlecode.com); check there. You can open
-a ticket there or email me at "h5py" at the domain "alfven dot org".
-
-
-High-level interface
-====================
-
-The goal of this component is to present access to HDF5 data in a manner
-consistent with the conventions of Python and Numpy. For example, "Group"
-objects allow dictionary-style access to their members, both through the
-familiar "Object['name']" slicing syntax and by iteration. "Dataset"
-objects support multidimensional slicing, Numpy dtype objects, and shape
-tuples.
-
-This interface is extensively documented via module and class docstrings.
-Consult the online HTML documentation (or Python's `help` command) for a
-more comprehensive guide.
-
-Here's a (mockup) example of some of the highlights:
-
-1. File objects support Python-like modes:
-
->>> from h5py.highlevel import File, Dataset, Group
->>> file = File('test_file.hdf5','r')
->>> file
-File "test_file.hdf5", root members: "group1", "dataset"
-
-2. Group objects support things like __len__ and iteration, along with
- dictionary-style access.
-
->>> grp = file["group1"]
->>> len(grp)
-4
->>> list(grp)
-['array1', 'array2', 'array3', 'array4']
-
-3. It's easy to add/remove members. Datasets can even be automatically
- created from Python objects at assignment time:
-
->>> del grp['array2']
->>> list(grp)
-['array1', 'array3', 'array4']
-
->>> grp['My float array'] = [1.0, 2.0, 3.5]
->>> list(grp)
-['array1', 'array3', 'array4', 'My float array']
->>> grp['My float array']
-Dataset: (3L,) dtype('<f4')
-
-4. Datasets support the Numpy attributes shape and dtype. Slicing a
- dataset object returns a Numpy array.
-
->>> dset = file["dataset"]
->>> dset
-Dataset: (3L, 10L) dtype(<f8')
->>> dset.shape # Numpy-style shape tuples for dimensions
-(3L, 10L)
->>> dset.dtype # Genuine Numpy dtype objects represent the datatype
-'<f4'
-
->>> dset[2,7] # Full multidimensional slicing allowed
-2.3
->>> dset[:,7]
-[-1.2, 0.5, 2.3]
->>> dset[0,0:10:2] # Start/stop/strides work, in any combination
-[-0.7, 9.1, 10.2, 2.6, 99.4]
-
->>> type(dset)
-<class 'h5py.highlevel.Dataset'>
->>> type(dset[:,10]) # Slicing produces Numpy ndarrays
-<type 'numpy.ndarray'>
-
-5. Full support for HDF5 scalar and array attributes:
-
->>> list(dest.attrs)
-['Name', 'Id', 'IntArray']
->>> dset.attrs['Name']
-"My Dataset"
->>> dset.attrs['Id']
-42
->>> dset.attrs['IntArray']
-array([0,1,2,3,4,5])
->>> dset.attrs['Name'] = "New name"
->>> dset.attrs['Name']
-"New name"
-
-Low-Level Interface
-===================
-
-The HDF5 library is divided into a number of groups (H5A, H5F, etc) which map
-more-or-less directly into Python modules of the same name. See the module
-and function docstrings (or the online HTML help) for details.
-
-Python extensions
------------------
-Most modules have several functions which are not part of the HDF5 spec.
-These are prefixed with "py" to underscore their unofficial nature. They
-are designed to encapsulate common operations and provide a more Python/
-Numpy-style interface, even at the low level of this interface. For
-example, the functions h5t.py_h5t_to_dtype and h5t.py_dtype_to_h5t allow
-automatic conversion between Numpy dtypes and HDF5 type objects.
-
-Constants
----------
-Constants are also available at the module level. When a constant is part
-of an C enum, the name of the enum is prepended to the constant name. For
-example, the dataspace-related enum H5S_class_t is wrapped like this:
-
- =============== ============== =============
- H5S_class_t h5s module Value
- =============== ============== =============
- H5S_NO_CLASS CLASS_NO_CLASS INT -1
- H5S_SCALAR CLASS_SCALAR INT 0
- H5S_SIMPLE CLASS_SIMPLE INT 1
- H5S_COMPLEX CLASS_COMPLEX INT 2
- <no equivalent> CLASS_MAPPER DDict(...)
- =============== ============== =============
-
-The additional entry CLASS_MAPPER is a dictionary subclass "DDict" which
-maps the integer values to string descriptions. This simplifies debugging
-and logging. The DDict class overrides "dict" so that it will always
-return a value; if the given integer is not in the CLASS enum, the returned
-string is ``"*INVALID* (<given value>)"``.
-
-Exceptions
-----------
-Each HDF5 API function is individually wrapped; the return value
-is checked, and the appropriate exception is raised (from h5py.errors) if
-something has gone wrong. This way you can write more Pythonic, exception-
-based code instead of checking return values.
-
-Additionally, the HDF5 error stack is automatically attached to the
-exception message, giving you a clear picture of what went wrong. The
-library will never print anything to stderr; everything goes through Python.
-
+I expect there are still a few. :) A FAQ page will soon be created at the
+project hosting wiki (http://h5py.googlecode.com); check there. You can
+open a ticket there or email me at "h5py" at the domain "alfven dot org".
diff --git a/h5py/browse.py b/h5py/browse.py
index 1463f21..e263417 100644
--- a/h5py/browse.py
+++ b/h5py/browse.py
@@ -142,7 +142,7 @@ class _H5Browser(Cmd, object):
print pname
except:
raise CmdError('Can\'t list contents of group "%s"' % hbasename(grpname))
-
+
def do_info(self, line):
opts, args = gnu_getopt(shlex.split(line),'')
diff --git a/h5py/highlevel.py b/h5py/highlevel.py
index 1a8ba83..45d80c5 100644
--- a/h5py/highlevel.py
+++ b/h5py/highlevel.py
@@ -18,6 +18,8 @@ from h5py.h5 import H5Error
from utils_hl import slicer, hbasename, strhdr, strlist
from browse import _H5Browser
+__all__ = ["File", "Group", "Dataset", "Datatype"]
+
try:
# For interactive File.browse() capability
import readline
@@ -126,10 +128,29 @@ class Group(HLObject):
for name in self:
yield (name, self[name])
- def desc(self):
- """ Extended description of this group, as a string.
+ def create_group(self, name):
+ """ Create and return a subgroup.
+ """
+ return Group(self, name, create=True)
+
+ def create_dataset(self, name, **kwds):
+ """ Create and return a dataset. Keyword arguments:
- print grp.desc() # contains newlines
+ You must specify either "data", or both "type" and "shape".
+ data: Numpy array from which the dataset will be constructed
+ type: Numpy dtype giving the datatype
+ shape: Numpy-style shape tuple giving the dataspace
+
+ Additional options (* is default):
+ chunks: Tuple of chunk dimensions or None*
+ compression: DEFLATE (gzip) compression level, int or None*
+ shuffle: Use the shuffle filter? (requires compression) T/F*
+ fletcher32: Enable Fletcher32 error detection? T/F*
+ """
+ return Dataset(self, name, **kwds)
+
+ def desc(self):
+ """ Extended (multi-line) description of this group, as a string.
"""
outstr = 'Group "%s" in file "%s":' % \
@@ -219,7 +240,7 @@ class File(Group):
def browse(self, dict=None):
""" Open a command line shell to browse this file. If dict is not
- specified, any imported object will be placed in the caller's
+ specified, any imported objects will be placed in the caller's
global() dictionary.
"""
if dict is None:
@@ -232,7 +253,6 @@ class File(Group):
# The following is an ugly hack to prevent readline from mixing the cmd
# session with IPython's session. Is there a better way to do this?
- hist = None
if readline:
hist = gethist()
readline.clear_history()
@@ -241,7 +261,7 @@ class File(Group):
try:
browser = _H5Browser(self, self._path, importdict=dict)
finally:
- if hist:
+ if readline:
self._rlhist.extend(gethist())
readline.clear_history()
for x in hist:
diff --git a/h5py/tests/__init__.py b/h5py/tests/__init__.py
index ccbd25a..e9760b2 100644
--- a/h5py/tests/__init__.py
+++ b/h5py/tests/__init__.py
@@ -14,13 +14,13 @@ import unittest
import sys
import test_h5a, test_h5d, test_h5f, \
test_h5g, test_h5i, test_h5p, \
- test_h5s, test_h5t, test_h5
+ test_h5s, test_h5
from h5py import *
TEST_CASES = (test_h5a.TestH5A, test_h5d.TestH5D, test_h5f.TestH5F,
test_h5g.TestH5G, test_h5i.TestH5I, test_h5p.TestH5P,
- test_h5s.TestH5S, test_h5t.TestH5T, test_h5.TestH5)
+ test_h5s.TestH5S, test_h5.TestH5)
def buildsuite(cases):
diff --git a/h5py/tests/test_highlevel.py b/h5py/tests/test_highlevel.py
index e4c0996..aed6e80 100644
--- a/h5py/tests/test_highlevel.py
+++ b/h5py/tests/test_highlevel.py
@@ -12,48 +12,12 @@
import unittest
import os
+import tempfile
from numpy import all
import h5py
from h5py.highlevel import *
-# --- Description of the PyTables test file smpl_compound_chunked -------------
-
-HDFNAME2 = os.path.join(os.path.dirname(h5py.__file__), 'tests/data/smpl_compound_chunked.hdf5')
-DTYPE = numpy.dtype([('a_name','>i4'),
- ('c_name','|S6'),
- ('d_name', numpy.dtype( ('>i2', (5,10)) )),
- ('e_name', '>f4'),
- ('f_name', numpy.dtype( ('>f8', (10,)) )),
- ('g_name', '<u1')])
-SHAPE = (6,)
-
-basearray = numpy.ndarray(SHAPE, dtype=DTYPE)
-for i in range(SHAPE[0]):
- basearray[i]["a_name"] = i,
- basearray[i]["c_name"] = "Hello!"
- basearray[i]["d_name"][:] = numpy.sum(numpy.indices((5,10)),0) + i # [:] REQUIRED for some stupid reason
- basearray[i]["e_name"] = 0.96*i
- basearray[i]["f_name"][:] = numpy.array((1024.9637*i,)*10)
- basearray[i]["g_name"] = 109
-
-names = ("a_name","c_name","d_name","e_name","f_name","g_name")
class TestHighlevel(unittest.TestCase):
-
-
- def test_ds(self):
- myfile = File(HDFNAME2,'r')
- try:
- ds = myfile["CompoundChunked"]
- for i in range(6):
- self.assert_(all(ds[i]==basearray[i]), "%d"%i)
- for name in names:
- self.assert_(all(ds[name]==basearray[name]))
- finally:
- myfile.close()
-
-
-
-
-
+ pass
diff --git a/setup.py b/setup.py
index 8f88295..34cbe88 100644
--- a/setup.py
+++ b/setup.py
@@ -269,11 +269,13 @@ class test(Command):
buildobj = self.distribution.get_command_obj('build')
buildobj.run()
oldpath = sys.path
- sys.path = [os.path.abspath(buildobj.build_lib)] + oldpath
- import h5py.tests
- if not h5py.tests.runtests():
- raise DistutilsError("Unit tests failed.")
- sys.path = oldpath
+ try:
+ sys.path = [os.path.abspath(buildobj.build_lib)] + oldpath
+ import h5py.tests
+ if not h5py.tests.runtests():
+ raise DistutilsError("Unit tests failed.")
+ finally:
+ sys.path = oldpath
class dev(Command):
description = "Developer commands (--doc, --clean, --readme=<file>)"
--
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