[h5py] 70/455: HL tweaks; doc changes for 0.2
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 f86c79d6e57a731d99c6031345e5cb5eb43e4fce
Author: andrewcollette <andrew.collette at gmail.com>
Date: Wed Jul 9 04:04:11 2008 +0000
HL tweaks; doc changes for 0.2
---
LICENSE.txt | 2 +-
README.txt | 12 +++++
h5py/h5.pyx | 22 ++++-----
h5py/h5d.pyx | 1 -
h5py/h5f.pyx | 1 -
h5py/h5g.pyx | 2 +-
h5py/h5i.pyx | 6 ---
h5py/h5r.pyx | 4 --
h5py/h5s.pyx | 1 -
h5py/h5t.pyx | 1 -
h5py/h5z.pyx | 1 -
h5py/highlevel.py | 136 +++++++++++++++++++++++++++++++++++++++++++-----------
h5py/utils_hl.py | 4 ++
setup.py | 24 +++++-----
14 files changed, 148 insertions(+), 69 deletions(-)
diff --git a/LICENSE.txt b/LICENSE.txt
index 49e0846..15b30f2 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -1,4 +1,4 @@
-Copyright Notice and Statement for the h5py Project:
+Copyright Notice and Statement for the h5py Project
Copyright (c) 2008 Andrew Collette
http://h5py.alfven.org
diff --git a/README.txt b/README.txt
index 4a7aace..623a3ca 100644
--- a/README.txt
+++ b/README.txt
@@ -114,6 +114,18 @@ Procedure
4. Run ``sudo python setup.py install`` to install into your main Python
package directory.
+Additional options
+------------------
+ --pyrex Have Pyrex recompile changed pyx files.
+ --pyrex-only Have Pyrex recompile changed pyx files, and stop.
+ --pyrex-force Recompile all pyx files, regardless of timestamps.
+ --no-pyrex Don't run Pyrex, no matter what
+
+ --api=<n> Specifies API version. Only --api=16 is currently allowed.
+ --debug=<n> If nonzero, compile in debug mode. The number is
+ interpreted as a logging-module level number. Requires
+ Pyrex for recompilation.
+
Bugs
----
I expect there are still a few. :) A FAQ page will soon be created at the
diff --git a/h5py/h5.pyx b/h5py/h5.pyx
index c75f4a8..47dc821 100644
--- a/h5py/h5.pyx
+++ b/h5py/h5.pyx
@@ -12,14 +12,20 @@
"""
Common module for the HDF5 low-level interface library.
- Library version and API information lives here:
- - HDF5_VERS, HDF5_VERS_TPL: Library version
- - API_VERS, API_VERS_TPL: API version (1.6 or 1.8) used to compile h5py.
+ This is an internal module which is designed to set up the library and
+ enable HDF5 exception handline. It also enables debug logging, if the
+ library has been compiled with a nonzero debugging level.
+
+ Useful things defined here:
+
+ hdf5_version: String with library version (e.g. "1.6.5")
+ hdf5_version_tuple: Tuple form of the version (e.g. (1,6,5))
+ api_version: String form of the API used (e.g. "1.6")
+ api_version_tuple: Tuple form of the version (e.g. (1,6))
All exception classes and error handling functions are also in this module.
- This module is designed to be imported before any other h5py module is
- executed. It opens the library and enables debug logging, if required.
+
"""
include "conditions.pxi"
@@ -65,12 +71,6 @@ def _open():
"""
H5open()
-class DDict(dict):
- """ Internal class.
- """
- def __missing__(self, key):
- return '*INVALID* (%s)' % str(key)
-
# === Identifier wrappers =====================================================
cdef class ObjectID:
diff --git a/h5py/h5d.pyx b/h5py/h5d.pyx
index 64092c8..b4fc89c 100644
--- a/h5py/h5d.pyx
+++ b/h5py/h5d.pyx
@@ -25,7 +25,6 @@ from utils cimport check_numpy_read, check_numpy_write, \
# Runtime imports
import h5
-from h5 import DDict
import h5t
import h5s
diff --git a/h5py/h5f.pyx b/h5py/h5f.pyx
index 0f3f402..4ede49f 100644
--- a/h5py/h5f.pyx
+++ b/h5py/h5f.pyx
@@ -26,7 +26,6 @@ from utils cimport emalloc, efree, pybool
# Runtime imports
import h5
-from h5 import DDict
# === Public constants and data structures ====================================
diff --git a/h5py/h5g.pyx b/h5py/h5g.pyx
index 32823aa..f41d47c 100644
--- a/h5py/h5g.pyx
+++ b/h5py/h5g.pyx
@@ -19,7 +19,7 @@ from utils cimport emalloc, efree
# Runtime imports
import h5
-from h5 import DDict, H5Error
+from h5 import H5Error
# === Public constants and data structures ====================================
diff --git a/h5py/h5i.pyx b/h5py/h5i.pyx
index c87d895..5977168 100644
--- a/h5py/h5i.pyx
+++ b/h5py/h5i.pyx
@@ -20,7 +20,6 @@ from utils cimport emalloc, efree
# Runtime imports
import h5
-from h5 import DDict
# === Public constants and data structures ====================================
@@ -35,11 +34,6 @@ GENPROP_CLS = H5I_GENPROP_CLS
GENPROP_LST = H5I_GENPROP_LST
DATATYPE = H5I_DATATYPE
-PY_TYPE = DDict({ H5I_BADID: 'BAD ID', H5I_FILE: 'FILE', H5I_GROUP: 'GROUP',
- H5I_DATASET: 'DATASET', H5I_ATTR: 'ATTRIBUTE',
- H5I_REFERENCE: 'REFERENCE', H5I_GENPROP_CLS: 'PROPERTY LIST CLASS',
- H5I_GENPROP_LST: 'PROPERTY LIST', H5I_DATATYPE: 'DATATYPE' })
-
# === Identifier API ==========================================================
def get_type(ObjectID obj not None):
diff --git a/h5py/h5r.pyx b/h5py/h5r.pyx
index e9a09db..1d66968 100644
--- a/h5py/h5r.pyx
+++ b/h5py/h5r.pyx
@@ -19,16 +19,12 @@ from h5g cimport H5G_obj_t
# Runtime imports
import h5
-from h5 import DDict
# === Public constants and data structures ====================================
OBJECT = H5R_OBJECT
DATASET_REGION = H5R_DATASET_REGION
-PY_TYPE = {H5R_OBJECT: 'OBJECT', H5R_DATASET_REGION: 'DATASET REGION' }
-PY_TYPE = DDict(PY_TYPE)
-
cdef union ref_u:
hobj_ref_t obj_ref
hdset_reg_ref_t reg_ref
diff --git a/h5py/h5s.pyx b/h5py/h5s.pyx
index 499ebbc..d9bd34c 100644
--- a/h5py/h5s.pyx
+++ b/h5py/h5s.pyx
@@ -20,7 +20,6 @@ from utils cimport require_tuple, require_list, convert_dims, convert_tuple, \
# Runtime imports
import h5
-from h5 import DDict
cdef object lockid(hid_t id_):
cdef SpaceID space
diff --git a/h5py/h5t.pyx b/h5py/h5t.pyx
index 70654ed..9bbf867 100644
--- a/h5py/h5t.pyx
+++ b/h5py/h5t.pyx
@@ -28,7 +28,6 @@ from utils cimport emalloc, efree, pybool, \
# Runtime imports
import h5
-from h5 import DDict, ArgsError
import sys
# === Custom C API ============================================================
diff --git a/h5py/h5z.pyx b/h5py/h5z.pyx
index 39a6938..ff0fd17 100644
--- a/h5py/h5z.pyx
+++ b/h5py/h5z.pyx
@@ -19,7 +19,6 @@ from utils cimport pybool
# Runtime imports
import h5
-from h5 import DDict
# === Public constants and data structures ====================================
diff --git a/h5py/highlevel.py b/h5py/highlevel.py
index 45d80c5..d4b9597 100644
--- a/h5py/highlevel.py
+++ b/h5py/highlevel.py
@@ -9,6 +9,36 @@
# $Date$
#
#-
+
+"""
+ Provides high-level Python objects for HDF5 files, groups, and datasets.
+
+ Groups provide dictionary-like access to and iteration over their members.
+ File objects implicitly perform these operations on the root ('/') group.
+
+ Datasets support full Numpy-style slicing and partial I/0, including
+ recarray-style access to named fields. A minimal Numpy interface is
+ included, with shape and dtype properties.
+
+ A strong emphasis has been placed on reasonable automatic conversion from
+ Python types to their HDF5 equivalents. Setting and retrieving HDF5 data
+ is almost always handled by a simple assignment. For example, you can
+ create an initialize and HDF5 dataset simply by assigning a Numpy array
+ to a group:
+
+ group["name"] = numpy.ones((10,50), dtype='<i2')
+
+ To make it easier to get data in and out of Python, a simple command-line
+ shell comes attached to all File objects via the method File.browse().
+ You can explore an HDF5 file, and import datasets, groups, and named
+ types into your main interactive Python session.
+
+ Although it's not required to use this high-level interface, the full power
+ of the h5py low-level library wrapping is available for these objects.
+ Each highlevel object carries an identifier object (obj.id), which can be
+ used by h5py.h5* functions or methods.
+"""
+
import os
import numpy
import inspect
@@ -28,8 +58,20 @@ except ImportError:
class HLObject(object):
+ """
+ Base class for high-level interface objects.
+
+ All objects of this class support the following properties:
+
+ id: Low-level identifer, compatible with the h5py.h5* modules.
+ name: (Some) name of this object in the HDF5 file.
+ attrs: HDF5 attributes of this object. See the AttributeManager docs.
+ """
+
name = property(lambda self: h5i.get_name(self.id),
doc = "Name of this object in the HDF5 file. Not necessarily unique.")
+ attrs = property(lambda self: self._attrs,
+ doc = "Provides access to HDF5 attributes. See AttributeManager.")
def __repr__(self):
return str(self)
@@ -38,11 +80,24 @@ class Group(HLObject):
""" Represents an HDF5 group.
- Iterating over a group yields the names of its members.
- """
+ Group(parent, name, create=False)
- attrs = property(lambda self: self._attrs,
- doc = "Provides access to HDF5 attributes. See AttributeManager.")
+ Group members can be accessed dictionary-style (Group["name"]). HDF5
+ objects can be automatically created in the group by assigning Numpy
+ arrays, dtypes, or other Group, Dataset or Datatype objects with this
+ syntax. See the __setitem__ docstring for a complete list.
+
+ The len() of a group is the number of members, and iterating over a
+ group yields the names of its members, in arbitary library-defined
+ order.
+
+ Subgroups and datasets can be created via the convenience functions
+ create_group and create_dataset, as well as by calling the appropriate
+ class constructor.
+
+ Group attributes are accessed via Group.attrs; see the docstring for
+ the AttributeManager class.
+ """
def __init__(self, parent_object, name, create=False):
""" Create a new Group object, from a parent object and a name.
@@ -130,6 +185,8 @@ class Group(HLObject):
def create_group(self, name):
""" Create and return a subgroup.
+
+ Fails if the group already exists.
"""
return Group(self, name, create=True)
@@ -137,15 +194,15 @@ class Group(HLObject):
""" Create and return a dataset. Keyword arguments:
You must specify either "data", or both "type" and "shape".
- data: Numpy array from which the dataset will be constructed
+ data: Numpy array from which the dataset is 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*
+ shuffle: Use the shuffle filter (needs compression) T/F*
+ fletcher32: Enable Fletcher32 error detection T/F*
"""
return Dataset(self, name, **kwds)
@@ -170,12 +227,19 @@ class File(Group):
""" Represents an HDF5 file on disk.
+ File(name, mode='r', noclobber=False)
+
Created with standard Python syntax File(name, mode).
Legal modes: r, r+, w, w+, a (default 'r')
File objects inherit from Group objects; Group-like methods all
operate on the HDF5 root group ('/'). Like Python file objects, you
must close the file ("obj.close()") when you're done with it.
+
+ The special method browse() will open a command shell, allowing you
+ to browse the file and import objects into the interactive Python
+ session. If the readline module is available, this includes things
+ like command history and tab completion.
"""
name = property(lambda self: self._name,
@@ -223,7 +287,7 @@ class File(Group):
self._rlhist = [] # for readline nonsense
def close(self):
- """ Close this HDF5 file. All open identifiers will become invalid.
+ """ Close this HDF5 file. All open objects will be invalidated.
"""
self.id._close()
self.fid.close()
@@ -243,6 +307,10 @@ class File(Group):
specified, any imported objects will be placed in the caller's
global() dictionary.
"""
+ if not self.id._valid:
+ print "Can't browse: this file is closed."
+ return
+
if dict is None:
dict = inspect.currentframe().f_back.f_globals
@@ -270,7 +338,20 @@ class File(Group):
class Dataset(HLObject):
- """ High-level interface to an HDF5 dataset
+ """ High-level interface to an HDF5 dataset.
+
+ Dataset(group, name, data=None, dtype=None, shape=None, **kwds)
+
+ Datasets behave superficially like Numpy arrays. The full Numpy
+ slicing syntax, including recarray indexing of named fields (even
+ more than one), is supported. The object returned is always a
+ Numpy ndarray.
+
+ Additionally, the following properties are provided:
+ shape: Numpy-style shape tuple of dimsensions
+ dtype: Numpy dtype representing the datatype
+ value: Copy of the full dataset, as either a Numpy array or a
+ Numpy/Python scalar, depending on the shape.
"""
shape = property(lambda self: self.id.shape,
@@ -279,9 +360,6 @@ class Dataset(HLObject):
dtype = property(lambda self: self.id.dtype,
doc = "Numpy dtype representing the datatype")
- attrs = property(lambda self: self._attrs,
- doc = "Provides access to HDF5 attributes. See AttributeManager.")
-
def _getval(self):
arr = self[...]
if arr.shape == ():
@@ -441,26 +519,25 @@ class Dataset(HLObject):
str(self.shape), repr(self.dtype))
return "Closed dataset"
-class AttributeManager(HLObject):
+class AttributeManager(object):
""" Allows dictionary-style access to an HDF5 object's attributes.
- You should never have to create one of these; they come attached to
- Group, Dataset and NamedType objects as "obj.attrs".
+ These come attached to HDF5 objects as Obj.attrs. You should never
+ create one yourself.
- - Access existing attributes with "obj.attrs['attr_name']". If the
- attribute is scalar, a scalar value is returned, else an ndarray.
+ Like the members of groups, attributes are accessed using dict-style
+ syntax. Anything which can be reasonably converted to a Numpy array or
+ Numpy scalar can be stored.
- - Set attributes with "obj.attrs['attr_name'] = value". Note that
- this will overwrite an existing attribute.
+ Since attributes are typically used for small scalar values, acessing
+ a scalar attribute returns a Numpy/Python scalar, not an 0-dimensional
+ array. Non-scalar data is always returned as an ndarray.
- - Delete attributes with "del obj.attrs['attr_name']".
-
- - Iterating over obj.attrs yields the names of the attributes. The
- method iteritems() yields (name, value) pairs.
-
- - len(obj.attrs) returns the number of attributes.
+ The len() of this object is the number of attributes; iterating over
+ it yields the attribute names.
"""
+
def __init__(self, parent):
self.id = parent.id
@@ -506,7 +583,7 @@ class AttributeManager(HLObject):
def __str__(self):
if self.id._valid:
- rstr = 'Attributes of "%s": ' % hbasename(self.name)
+ rstr = 'Attributes of "%s": ' % hbasename(h5i.get_name(self.id))
if len(self) == 0:
rstr += '(none)'
else:
@@ -522,9 +599,12 @@ class AttributeManager(HLObject):
class Datatype(HLObject):
"""
- Represents an HDF5 datatype.
+ Represents an HDF5 named datatype.
+
+ These intentionally only represent named types, and exist mainly so
+ that you can access their attributes.
- These intentionally only represent named types.
+ The property Datatype.dtype provides a Numpy dtype equivalent.
"""
dtype = property(lambda self: self.id.dtype)
diff --git a/h5py/utils_hl.py b/h5py/utils_hl.py
index 7acfecb..412c61b 100644
--- a/h5py/utils_hl.py
+++ b/h5py/utils_hl.py
@@ -48,6 +48,10 @@ def slicer(shape, args):
else:
slices.append(entry)
+ # If only named fields are provided
+ if len(slices) == 0:
+ slices = [Ellipsis]
+
start = []
count = []
stride = []
diff --git a/setup.py b/setup.py
index 34cbe88..8ec510c 100644
--- a/setup.py
+++ b/setup.py
@@ -30,9 +30,10 @@
python setup.py test
Additional options (for all modes):
- --pyrex Have Pyrex recompile changed *.pyx files.
- --pyrex-only Have Pyrex recompile changed *.pyx files, and stop.
- --pyrex-force Recompile all *.pyx files, regardless of timestamps.
+ --pyrex Have Pyrex recompile changed pyx files.
+ --pyrex-only Have Pyrex recompile changed pyx files, and stop.
+ --pyrex-force Recompile all pyx files, regardless of timestamps.
+ --no-pyrex Don't run Pyrex, no matter what
--api=<n> Specifies API version. Only "16" is currently allowed.
--debug=<n> If nonzero, compile in debug mode. The number is
@@ -84,10 +85,10 @@ def warn(instring):
ENABLE_PYREX = False
PYREX_ONLY = False
PYREX_FORCE = False
+PYREX_FORCE_OFF = False
API_VERS = (1,6)
DEBUG_LEVEL = 0
-DEV_MODE = False
for arg in sys.argv[:]:
if arg == '--pyrex':
@@ -101,6 +102,9 @@ for arg in sys.argv[:]:
ENABLE_PYREX=True
PYREX_FORCE = True
sys.argv.remove(arg)
+ elif arg == '--no-pyrex':
+ PYREX_FORCE_OFF = True
+ sys.argv.remove(arg)
elif arg.find('--api=') == 0:
api = arg[6:]
if api == '16':
@@ -112,9 +116,6 @@ for arg in sys.argv[:]:
DEBUG_LEVEL = int(arg[8:])
sys.argv.remove(arg)
-if "dev" in sys.argv:
- DEV_MODE = True
-
if 'sdist' in sys.argv and os.path.exists('MANIFEST'):
warn("Cleaning up stale MANIFEST file")
os.remove('MANIFEST')
@@ -202,7 +203,7 @@ except IOError:
if not all([os.path.exists(x+'.c') for x in pyrex_sources]):
ENABLE_PYREX = True
-if ENABLE_PYREX:
+if ENABLE_PYREX and not PYREX_FORCE_OFF:
print "Running Pyrex..."
try:
from Pyrex.Compiler.Main import Version
@@ -222,10 +223,7 @@ if ENABLE_PYREX:
results = compile_multiple( [x+'.pyx' for x in pyrex_sources], opts)
if results.num_errors != 0:
- if DEV_MODE:
- warn("%d Pyrex compilation errors encountered." % results.num_errors)
- else:
- fatal("%d Pyrex compilation errors encountered; aborting." % results.num_errors)
+ fatal("%d Pyrex compilation errors encountered; aborting." % results.num_errors)
if PYREX_ONLY:
exit(0)
else:
@@ -234,7 +232,7 @@ if ENABLE_PYREX:
except ImportError:
fatal("Pyrex recompilation required, but Pyrex not installed.")
else:
- print "Pyrex not required, skipping."
+ print "Skipping Pyrex..."
# Create extensions
pyx_extensions = []
--
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