[h5py] 259/455: Update docs
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:39 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 02564a35448e1375e639c33c2321aa7050cacb8f
Author: andrewcollette <andrew.collette at gmail.com>
Date: Mon Jun 1 23:15:39 2009 +0000
Update docs
---
docs/source/guide/attr.rst | 104 ++++++
docs/source/guide/dataset.rst | 266 +++++++++++++++
docs/source/guide/file.rst | 110 ++++++
docs/source/guide/group.rst | 282 ++++++++++++++++
docs/source/guide/hl.rst | 753 +-----------------------------------------
docs/source/guide/vl.rst | 59 ++++
6 files changed, 838 insertions(+), 736 deletions(-)
diff --git a/docs/source/guide/attr.rst b/docs/source/guide/attr.rst
new file mode 100644
index 0000000..1394c81
--- /dev/null
+++ b/docs/source/guide/attr.rst
@@ -0,0 +1,104 @@
+.. _attributes:
+
+==========
+Attributes
+==========
+
+Groups and datasets can have small bits of named information attached to them.
+This is the official way to store metadata in HDF5. Each of these objects
+has a small proxy object (:class:`AttributeManager`) attached to it as
+``<obj>.attrs``. This dictionary-like object works like a :class:`Group`
+object, with the following differences:
+
+- Entries may only be scalars and NumPy arrays
+- Each attribute must be small (recommended < 64k for HDF5 1.6)
+- No partial I/O (i.e. slicing) is allowed for arrays
+
+They support the same dictionary API as groups.
+
+Reference
+---------
+
+.. class:: AttributeManager
+
+ .. method:: __getitem__(name) -> NumPy scalar or ndarray
+
+ Retrieve an attribute given a string name.
+
+ .. method:: __setitem__(name, value)
+
+ Set an attribute. Value must be convertible to a NumPy scalar
+ or array.
+
+ .. method:: __delitem__(name)
+
+ Delete an attribute.
+
+ .. method:: create(name, data=None, shape=None, dtype=None)
+
+ Create an attribute, optionally initializing it.
+
+ name
+ Name of the new attribute (required)
+
+ data
+ An array to initialize the attribute.
+ Required unless "shape" is given.
+
+ shape
+ Shape of the attribute. Overrides data.shape if both are
+ given. The total number of points must be unchanged.
+
+ dtype
+ Data type of the attribute. Overrides data.dtype if both
+ are given. Must be conversion-compatible with data.dtype.
+
+ .. method:: modify(name, value)
+
+ Change the value of an attribute while preserving its type.
+
+ Differs from __setitem__ in that the type of an existing attribute
+ is preserved. Useful for interacting with externally generated files.
+
+ If the attribute doesn't exist, it will be automatically created.
+
+ .. method:: __len__
+
+ Number of attributes
+
+ .. method:: __iter__
+
+ Yields the names of attributes
+
+ .. method:: __contains__(name)
+
+ See if the given attribute is present
+
+ .. method:: keys
+
+ Get a list of attribute names
+
+ .. method:: iterkeys
+
+ Get an iterator over attribute names
+
+ .. method:: values
+
+ Get a list with all attribute values
+
+ .. method:: itervalues
+
+ Get an iterator over attribute values
+
+ .. method:: items
+
+ Get an list of (name, value) pairs for all attributes.
+
+ .. method:: iteritems
+
+ Get an iterator over (name, value) pairs
+
+ .. method:: get(name, default)
+
+ Return the specified attribute, or default if it doesn't exist.
+
diff --git a/docs/source/guide/dataset.rst b/docs/source/guide/dataset.rst
new file mode 100644
index 0000000..9ca82ca
--- /dev/null
+++ b/docs/source/guide/dataset.rst
@@ -0,0 +1,266 @@
+.. _datasets:
+
+========
+Datasets
+========
+
+Datasets, like NumPy arrays, they are homogenous collections of data elements,
+with an immutable datatype and (hyper)rectangular shape. Unlike NumPy arrays,
+they support a variety of transparent storage features such as compression,
+error-detection, and chunked I/O.
+
+They are represented in h5py by a thin proxy class which supports familiar
+NumPy operations like slicing, along with a variety of descriptive attributes.
+
+Datasets are created using either :meth:`Group.create_dataset` or
+:meth:`Group.require_dataset`. Existing datasets should be retrieved using
+the group indexing syntax (``dset = group["name"]``).
+
+NumPy compatibility
+-------------------
+
+Datasets implement the following parts of the NumPy-array user interface:
+
+ - Slicing: simple indexing and a subset of advanced indexing
+ - **shape** attribute
+ - **dtype** attribute
+
+.. _dsetfeatures:
+
+Special features
+----------------
+
+Unlike memory-resident NumPy arrays, HDF5 datasets support a number of optional
+features. These are enabled by the keywords provided to
+:meth:`Group.create_dataset`. Some of the more useful are:
+
+Chunked storage
+ HDF5 can store data in "chunks" indexed by B-trees, as well as in the
+ traditional contiguous manner. This can dramatically increase I/O
+ performance for certain patterns of access; for example, reading every
+ n-th element along the fastest-varying dimension.
+
+Compression
+ Transparent compression can substantially reduce
+ the storage space needed for the dataset. Beginning with h5py 1.1,
+ three techniques are available, "gzip", "lzf" and "szip". See the
+ ``filters`` module for more information.
+
+Error-Detection
+ All versions of HDF5 include the *fletcher32* checksum filter, which enables
+ read-time error detection for datasets. If part of a dataset becomes
+ corrupted, a read operation on that section will immediately fail with
+ H5Error.
+
+Resizing
+ When using HDF5 1.8,
+ datasets can be resized, up to a maximum value provided at creation time.
+ You can specify this maximum size via the *maxshape* argument to
+ :meth:`create_dataset <Group.create_dataset>` or
+ :meth:`require_dataset <Group.require_dataset>`. Shape elements with the
+ value ``None`` indicate unlimited dimensions.
+
+ Later calls to :meth:`Dataset.resize` will modify the shape in-place::
+
+ >>> dset = grp.create_dataset((10,10), '=f8', maxshape=(None, None))
+ >>> dset.shape
+ (10, 10)
+ >>> dset.resize((20,20))
+ >>> dset.shape
+ (20, 20)
+
+ Resizing an array with existing data works differently than in NumPy; if
+ any axis shrinks, the data in the missing region is discarded. Data does
+ not "rearrange" itself as it does when resizing a NumPy array.
+
+.. _slicing_access:
+
+Slicing access
+--------------
+
+The best way to get at data is to use the traditional NumPy extended-slicing
+syntax. Slice specifications are translated directly to HDF5 *hyperslab*
+selections, and are are a fast and efficient way to access data in the file.
+The following slicing arguments are recognized:
+
+ * Numbers: anything that can be converted to a Python long
+ * Slice objects: please note negative values are not allowed
+ * Field names, in the case of compound data
+ * At most one ``Ellipsis`` (``...``) object
+
+Here are a few examples (output omitted)
+
+ >>> dset = f.create_dataset("MyDataset", data=numpy.ones((10,10,10),'=f8'))
+ >>> dset[0,0,0]
+ >>> dset[0,2:10,1:9:3]
+ >>> dset[0,...]
+ >>> dset[:,::2,5]
+
+Simple array broadcasting is also supported:
+
+ >>> dset[0] # Equivalent to dset[0,...]
+
+For compound data, you can specify multiple field names alongside the
+numeric slices:
+
+ >>> dset["FieldA"]
+ >>> dset[0,:,4:5, "FieldA", "FieldB"]
+ >>> dset[0, ..., "FieldC"]
+
+Coordinate lists
+----------------
+
+For any axis, you can provide an explicit list of points you want; for a
+dataset with shape (10, 10)::
+
+ >>> dset.shape
+ (10, 10)
+ >>> result = dset[0, [1,3,8]]
+ >>> result.shape
+ (3,)
+ >>> result = dset[1:6, [5,8,9]]
+ >>> result.shape
+ (5, 3)
+
+The following restrictions exist:
+
+* List selections may not be empty
+* Selection coordinates must be given in increasing order
+* Duplicate selections are ignored
+
+.. _sparse_selection:
+
+Sparse selection
+----------------
+
+Additional mechanisms exist for the case of scattered and/or sparse selection,
+for which slab or row-based techniques may not be appropriate.
+
+Boolean "mask" arrays can be used to specify a selection. The result of
+this operation is a 1-D array with elements arranged in the standard NumPy
+(C-style) order:
+
+ >>> arr = numpy.arange(100).reshape((10,10))
+ >>> dset = f.create_dataset("MyDataset", data=arr)
+ >>> result = dset[arr > 50]
+ >>> result.shape
+ (49,)
+
+Advanced selection
+------------------
+
+The ``selections`` module contains additional classes which provide access to
+HDF5 dataspace selection techniques, including point-based selection. These
+are especially useful for read_direct and write_direct.
+
+Length and iteration
+--------------------
+
+As with NumPy arrays, the ``len()`` of a dataset is the length of the first
+axis. Since Python's ``len`` is limited by the size of a C long, it's
+recommended you use the syntax ``dataset.len()`` instead of ``len(dataset)``
+on 32-bit platforms, if you expect the length of the first row to exceed 2**32.
+
+Iterating over a dataset iterates over the first axis. However, modifications
+to the yielded data are not recorded in the file. Resizing a dataset while
+iterating has undefined results.
+
+Reference
+---------
+
+.. class:: Dataset
+
+ Represents an HDF5 dataset. All properties are read-only.
+
+ .. attribute:: name
+
+ Full name of this dataset in the file (e.g. ``/grp/MyDataset``)
+
+ .. attribute:: attrs
+
+ Provides access to HDF5 attributes; see :ref:`attributes`.
+
+ .. attribute:: shape
+
+ Numpy-style shape tuple with dataset dimensions
+
+ .. attribute:: dtype
+
+ Numpy dtype object representing the dataset type
+
+ .. attribute:: value
+
+ Special read-only property; for a regular dataset, it's equivalent to
+ dset[:] (an ndarray with all points), but for a scalar dataset, it's
+ a NumPy scalar instead of an 0-dimensional ndarray.
+
+ .. attribute:: chunks
+
+ Dataset chunk size, or None if chunked layout isn't used.
+
+ .. attribute:: compression
+
+ None or a string indicating the compression strategy;
+ one of "gzip", "lzf", or "lzf".
+
+ .. attribute:: compression_opts
+
+ Setting for the compression filter
+
+ .. attribute:: shuffle
+
+ Is the shuffle filter being used? (T/F)
+
+ .. attribute:: fletcher32
+
+ Is the fletcher32 filter (error detection) being used? (T/F)
+
+ .. attribute:: maxshape
+
+ Maximum allowed size of the dataset, as specified when it was created.
+
+ .. method:: __getitem__(*args) -> NumPy ndarray
+
+ Read a slice from the dataset. See :ref:`slicing_access`.
+
+ .. method:: __setitem__(*args, val)
+
+ Write to the dataset. See :ref:`slicing_access`.
+
+ .. method:: read_direct(dest, source_sel=None, dest_sel=None)
+
+ Read directly from HDF5 into an existing NumPy array. The "source_sel"
+ and "dest_sel" arguments may be Selection instances (from the
+ selections module) or the output of ``numpy.s_``. Standard broadcasting
+ is supported.
+
+ .. method:: write_direct(source, source_sel=None, dest_sel=None)
+
+ Write directly to HDF5 from a NumPy array. The "source_sel"
+ and "dest_sel" arguments may be Selection instances (from the
+ selections module) or the output of ``numpy.s_``. Standard broadcasting
+ is supported.
+
+ .. method:: resize(shape, axis=None)
+
+ Change the size of the dataset to this new shape. Must be compatible
+ with the *maxshape* as specified when the dataset was created. If
+ the keyword *axis* is provided, the argument should be a single
+ integer instead; that axis only will be modified.
+
+ **Only available with HDF5 1.8**
+
+ .. method:: __len__
+
+ The length of the first axis in the dataset (TypeError if scalar).
+ This **does not work** on 32-bit platforms, if the axis in question
+ is larger than 2^32. Use :meth:`len` instead.
+
+ .. method:: len()
+
+ The length of the first axis in the dataset (TypeError if scalar).
+ Works on all platforms.
+
+ .. method:: __iter__
+
+ Iterate over rows (first axis) in the dataset. TypeError if scalar.
diff --git a/docs/source/guide/file.rst b/docs/source/guide/file.rst
new file mode 100644
index 0000000..9fbaa84
--- /dev/null
+++ b/docs/source/guide/file.rst
@@ -0,0 +1,110 @@
+.. _hlfile:
+
+============
+File Objects
+============
+
+Opening & creating files
+------------------------
+
+HDF5 files work generally like standard Python file objects. They support
+standand modes like r/w/a, and should be closed when they are no longer in
+use. However, there is obviously no concept of "text" vs "binary" mode.
+
+ >>> f = h5py.File('myfile.hdf5','r')
+
+Valid modes are:
+
+ === ================================================
+ r Readonly, file must exist
+ r+ Read/write, file must exist
+ w Create file, truncate if exists
+ w- Create file, fail if exists
+ a Read/write if exists, create otherwise (default)
+ === ================================================
+
+File drivers
+------------
+
+HDF5 ships with a variety of different low-level drivers, which map the logical
+HDF5 address space to different storage mechanisms. You can specify which
+driver you want to use when the file is opened::
+
+ >>> f = h5py.File('myfile.hdf5', driver=*driver name*, *driver_kwds*)
+
+For example, the HDF5 "core" driver can be used to create a purely in-memory
+HDF5 file, optionally written out to disk when it is closed. Currently
+supported drivers are:
+
+None
+ Use the standard HDF5 driver appropriate for the current platform.
+ On UNIX, this is the H5FD_SEC2 driver; on Windows, it is
+ H5FD_WINDOWS.
+
+'sec2'
+ Unbuffered, optimized I/O using standard POSIX functions.
+
+'stdio'
+ Buffered I/O using functions from stdio.h.
+
+'core'
+ Memory-map the entire file; all operations are performed in
+ memory and written back out when the file is closed. Keywords:
+
+ backing_store
+ If True (default), save changes to a real file
+ when closing. If False, the file exists purely
+ in memory and is discarded when closed.
+
+ block_size
+ Increment (in bytes) by which memory is extended.
+ Default is 1 megabyte (1024**2).
+
+'family'
+ Store the file on disk as a series of fixed-length chunks. Useful
+ if the file system doesn't allow large files. Note: the filename
+ you provide *must* contain the string "%d", which will be replaced
+ by the file sequence number. Keywords:
+
+ memb_size
+ Maximum file size (default is 2**31-1).
+
+Reference
+---------
+
+In addition to the properties and methods defined here, File objects inherit
+the full API of Group objects; in this case, the group in question is the
+*root group* (/) of the file.
+
+.. class:: File
+
+ Represents an HDF5 file on disk, and provides access to the root
+ group (``/``).
+
+ See also :class:`Group`, of which this is a subclass.
+
+ .. attribute:: name
+
+ HDF5 filename
+
+ .. attribute:: mode
+
+ Mode (``r``, ``w``, etc) used to open file
+
+ .. attribute:: driver
+
+ Driver ('sec2', 'stdio', etc.) used to open file
+
+ .. method:: __init__(name, mode='a', driver=None, **driver_kwds)
+
+ Open or create an HDF5 file.
+
+ .. method:: close()
+
+ Close the file. As with Python files, it's good practice to call
+ this when you're done.
+
+ .. method:: flush()
+
+ Ask the HDF5 library to flush its buffers for this file.
+
diff --git a/docs/source/guide/group.rst b/docs/source/guide/group.rst
new file mode 100644
index 0000000..5c73903
--- /dev/null
+++ b/docs/source/guide/group.rst
@@ -0,0 +1,282 @@
+=============
+Group Objects
+=============
+
+Groups are the container mechanism by which HDF5 files are organized. From
+a Python perspective, they operate somewhat like dictionaries. In this case
+the "keys" are the names of group entries, and the "values" are the entries
+themselves (:class:`Group` and :class:`Dataset`) objects. Objects are
+retrieved from the file using the standard indexing notation::
+
+ >>> file_obj = File('myfile.hdf5')
+ >>> subgroup = file_obj['/subgroup']
+ >>> dset = subgroup['MyDataset'] # full name /subgroup/Mydataset
+
+Objects can be deleted from the file using the standard syntax::
+
+ >>> del subgroup["MyDataset"]
+
+Group objects implement the following subset of the Python "mapping" interface:
+
+- Container syntax: ``if name in group``
+- Iteration; yields member names: ``for name in group``
+- Length: ``len(group)``
+- :meth:`keys() <Group.keys>`
+- :meth:`values() <Group.values>`
+- :meth:`items() <Group.items>`
+- :meth:`iterkeys() <Group.iterkeys>`
+- :meth:`itervalues() <Group.itervalues>`
+- :meth:`iteritems() <Group.iteritems>`
+- :meth:`__setitem__() <Group.__setitem__>`
+- :meth:`__getitem__() <Group.__getitem__>`
+- :meth:`__delitem__() <Group.__delitem__>`
+- :meth:`get() <Group.get>`
+
+Reference
+---------
+
+.. class:: Group
+
+ .. attribute:: name
+
+ Full name of this group in the file (e.g. ``/grp/thisgroup``)
+
+ .. attribute:: attrs
+
+ Dictionary-like object which provides access to this group's
+ HDF5 attributes. See :ref:`attributes` for details.
+
+ .. method:: __getitem__(name) -> Group or Dataset
+
+ Open an object in this group.
+
+ .. method:: __setitem__(name, object)
+
+ Add the given object to the group.
+
+ The action taken depends on the type of object assigned:
+
+ **Named HDF5 object** (Dataset, Group, Datatype)
+ A hard link is created in this group which points to the
+ given object.
+
+ **Numpy ndarray**
+ The array is converted to a dataset object, with default
+ settings (contiguous storage, etc.). See :meth:`create_dataset`
+ for a more flexible way to do this.
+
+ **Numpy dtype**
+ Commit a copy of the datatype as a
+ :ref:`named datatype <named_types>` in the file.
+
+ **Anything else**
+ Attempt to convert it to an ndarray and store it. Scalar
+ values are stored as scalar datasets. Raise ValueError if we
+ can't understand the resulting array dtype.
+
+ If a group member of the same name already exists, the assignment
+ will fail.
+
+ .. method:: __delitem__(name)
+
+ Remove (unlink) this member.
+
+ .. method:: create_group(name) -> Group
+
+ Create a new HDF5 group.
+
+ Fails with H5Error if the group already exists.
+
+ .. method:: require_group(name) -> Group
+
+ Open the specified HDF5 group, creating it if it doesn't exist.
+
+ Fails with H5Error if an incompatible object (dataset or named type)
+ already exists.
+
+ .. method:: create_dataset(name, [shape, [dtype]], [data], **kwds) -> Dataset
+
+ Create a new dataset. There are two logical ways to specify the dataset:
+
+ 1. Give the shape, and optionally the dtype. If the dtype is not given,
+ single-precision floating point ('=f4') will be assumed.
+ 2. Give a NumPy array (or anything that can be converted to a NumPy array)
+ via the "data" argument. The shape and dtype of this array will be
+ used, and the dataset will be initialized to its contents.
+
+ Additional keyword parameters control the details of how the dataset is
+ stored.
+
+ **shape** (None or tuple)
+ NumPy-style shape tuple. Required if data is not given.
+
+ **dtype** (None or dtype)
+ NumPy dtype (or anything that can be converted). Optional;
+ the default is '=f4'. Will override the dtype of any data
+ array given via the *data* parameter.
+
+ **data** (None or ndarray)
+ Either a NumPy ndarray or anything that can be converted to one.
+
+ Keywords (see :ref:`dsetfeatures`):
+
+ **chunks** (None, True or shape tuple)
+ Store the dataset in chunked format. Automatically
+ selected if any of the other keyword options are given. If you
+ don't provide a shape tuple, the library will guess one for you.
+ Chunk sizes of 100kB-300kB work best with HDF5.
+
+ **compression** (None, string ["gzip" | "lzf" | "szip"] or int 0-9)
+ Enable dataset compression. DEFLATE, LZF and (where available)
+ SZIP are supported. An integer is interpreted as a GZIP level
+ for backwards compatibility
+
+ **compression_opts** (None, or special value)
+ Setting for compression filter; legal values for each filter
+ type are:
+
+ ====== ======================================
+ "gzip" Integer 0-9
+ "lzf" (none allowed)
+ "szip" 2-tuple ('ec'|'nn', even integer 0-32)
+ ====== ======================================
+
+ See the ``filters`` module for a detailed description of each
+ of these filters.
+
+ **shuffle** (True/False)
+ Enable/disable data shuffling, which can improve compression
+ performance.
+
+ **fletcher32** (True/False)
+ Enable Fletcher32 error detection; may be used with or without
+ compression.
+
+ **maxshape** (None or shape tuple)
+ Make the dataset extendable, up to this maximum shape. Should be a
+ NumPy-style shape tuple. Dimensions with value None have no upper
+ limit.
+
+ .. method:: require_dataset(name, [shape, [dtype]], [data], **kwds) -> Dataset
+
+ Open a new dataset, creating one if it doesn't exist.
+
+ This method operates exactly like :meth:`create_dataset`, except that if
+ a dataset with compatible shape and dtype already exists, it is opened
+ instead. The additional keyword arguments are only honored when actually
+ creating a dataset; they are ignored for the comparison.
+
+ If an existing incompatible object (Group or Datatype) already exists
+ with the given name, fails with H5Error.
+
+ .. method:: copy(source, dest, name=None)
+
+ **Only available with HDF5 1.8**
+
+ Recusively copy an object from one location to another, or between files.
+
+ Copies the given object, and (if it is a group) all objects below it in
+ the hierarchy. The destination need not be in the same file.
+
+ **source** (Group, Dataset, Datatype or str)
+ Source object or path.
+
+ **dest** (Group or str)
+ Destination. Must be either Group or path. If a Group object, it may
+ be in a different file.
+
+ **name** (None or str)
+ If the destination is a Group object, you can override the name
+ for the newly created member. Otherwise a new name will be chosen
+ using basename(source.name).
+
+ .. method:: visit(func) -> None or return value from func
+
+ **Only available with HDF5 1.8**
+
+ Recursively iterate a callable over objects in this group.
+
+ You supply a callable (function, method or callable object); it
+ will be called exactly once for each link in this group and every
+ group below it. Your callable must conform to the signature::
+
+ func(<member name>) -> <None or return value>
+
+ Returning None continues iteration, returning anything else stops
+ and immediately returns that value from the visit method. No
+ particular order of iteration within groups is guranteed.
+
+ Example::
+
+ >>> # List the entire contents of the file
+ >>> f = File("foo.hdf5")
+ >>> list_of_names = []
+ >>> f.visit(list_of_names.append)
+
+ .. method:: visititems(func) -> None or return value from func
+
+ **Only available with HDF5 1.8**
+
+ Recursively visit names and objects in this group and subgroups.
+
+ You supply a callable (function, method or callable object); it
+ will be called exactly once for each link in this group and every
+ group below it. Your callable must conform to the signature::
+
+ func(<member name>, <object>) -> <None or return value>
+
+ Returning None continues iteration, returning anything else stops
+ and immediately returns that value from the visit method. No
+ particular order of iteration within groups is guranteed.
+
+ Example::
+
+ # Get a list of all datasets in the file
+ >>> mylist = []
+ >>> def func(name, obj):
+ ... if isinstance(obj, Dataset):
+ ... mylist.append(name)
+ ...
+ >>> f = File('foo.hdf5')
+ >>> f.visititems(func)
+
+ .. method:: __len__
+
+ Number of group members
+
+ .. method:: __iter__
+
+ Yields the names of group members
+
+ .. method:: __contains__(name)
+
+ See if the given name is in this group.
+
+ .. method:: keys
+
+ Get a list of member names
+
+ .. method:: iterkeys
+
+ Get an iterator over member names. Equivalent to iter(group).
+
+ .. method:: values
+
+ Get a list with all objects in this group.
+
+ .. method:: itervalues
+
+ Get an iterator over objects in this group
+
+ .. method:: items
+
+ Get an list of (name, object) pairs for the members of this group.
+
+ .. method:: iteritems
+
+ Get an iterator over (name, object) pairs for the members of this group.
+
+ .. method:: get(name, default)
+
+ Retrieve the member, or *default* if it doesn't exist.
+
diff --git a/docs/source/guide/hl.rst b/docs/source/guide/hl.rst
index 1c91ae2..7094483 100644
--- a/docs/source/guide/hl.rst
+++ b/docs/source/guide/hl.rst
@@ -11,13 +11,14 @@ The high-level interface is the most convenient method to talk to HDF5. There
are three main abstractions: files, groups, and datasets. Each is documented
separately below.
-You may want to read the :ref:`quick start guide <quick>` to get a general
-overview.
+.. toctree::
+ :maxdepth: 2
-Everything useful in this module is automatically exported to the `h5py`
-package namespace; you can do::
-
- >>> from h5py import * # or from h5py import File, etc.
+ file
+ group
+ dataset
+ attr
+ vl
General information about h5py and HDF5
=======================================
@@ -33,25 +34,21 @@ root group ``/`` (represented by the :class:`File` class) at the base.
Wherever a name or path is called for, it may be relative or absolute.
Unfortunately, the construct ``..`` (parent group) is not allowed.
-
Exceptions
----------
-Standard Python exceptions like TypeError and ValueError are raised in
-response to inappropriate arguments. When an error is encountered by the
-HDF5 library itself, h5py.H5Error (or more commonly, a subclass) is raised.
-For example::
+As of version 1.2, h5py uses a "hybrid" exception system. When an error is
+detected inside HDF5, an exception is raised which inherits from both a
+standard Python exception (TypeError, ValueError, etc), and an HDF5-specific
+exception class (a subclass of H5Error).
- >>> try:
- >>> myfile = h5py.File(some_name)
- >>> except TypeError:
- >>> print "Argument some_name isn't a string!"
- >>> except H5Error:
- >>> print "Problem opening the file %s" % some_name
+It's recommended that you use the standard Python exceptions in you code;
+for example, when indexing a Group object:
-In practice, all H5Error exceptions contain a useful stacktrace generated
-by the library itself, including a good description of where and why the error
-occurred.
+ >>> try:
+ >>> grp = mygroup[name]
+ >>> except KeyError:
+ >>> print 'Group "%s" does not exist' % name
Library configuration
---------------------
@@ -77,15 +74,6 @@ concurrency (and as it is not necessarily thread-safe), access to the library
is automatically serialized. The GIL is released around read/write operations
so that non-HDF5 threads (GUIs, computation) can continue to execute.
-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.
-
Metadata
--------
@@ -95,716 +83,9 @@ small, named bits of data. :class:`Group`, :class:`Dataset` and even
behavior, named ``<obj>.attrs``. This is the correct way to store metadata
in HDF5 files.
-.. _hlfile:
-
-File Objects
-============
-
-To open an HDF5 file, just instantiate the File object directly::
-
- >>> from h5py import File # or import *
- >>> file_obj = File('myfile.hdf5','r')
-
-Valid modes (like Python's file() modes) are:
-
- === ================================================
- r Readonly, file must exist
- r+ Read/write, file must exist
- w Create file, truncate if exists
- w- Create file, fail if exists
- a Read/write if exists, create otherwise (default)
- === ================================================
-
-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, even if an exception has been raised::
-
- >>> with File('myfile.hdf5', 'r') as file_obj:
- ... # do stuff with file_obj
- ...
- >>> # file_obj is guaranteed closed at end of block
-
-
-Reference
----------
-
-.. class:: File
-
- Represents an HDF5 file on disk, and provides access to the root
- group (``/``).
-
- See also :class:`Group`, of which this is a subclass.
-
- .. attribute:: name
-
- HDF5 filename
-
- .. attribute:: mode
-
- Mode (``r``, ``w``, etc) used to open file
-
- .. method:: __init__(name, mode='a')
-
- Open or create an HDF5 file.
-
- .. method:: close()
-
- Close the file. As with Python files, it's good practice to call
- this when you're done.
-
- .. method:: flush()
-
- Ask the HDF5 library to flush its buffers for this file.
-
-
-Groups
-======
-
-Groups are the container mechanism by which HDF5 files are organized. From
-a Python perspective, they operate somewhat like dictionaries. In this case
-the "keys" are the names of group entries, and the "values" are the entries
-themselves (:class:`Group` and :class:`Dataset`) objects. Objects are
-retrieved from the file using the standard indexing notation::
-
- >>> file_obj = File('myfile.hdf5')
- >>> subgroup = file_obj['/subgroup']
- >>> dset = subgroup['MyDataset'] # full name /subgroup/Mydataset
-
-Objects can be deleted from the file using the standard syntax::
-
- >>> del subgroup["MyDataset"]
-
-However, new groups and datasets should generally be created using method calls
-like :meth:`create_group <Group.create_group>` or
-:meth:`create_dataset <Group.create_dataset>`.
-Assigning a name to an existing Group or Dataset
-(e.g. ``group['name'] = another_group``) will create a new link in the file
-pointing to that object. Assigning dtypes and NumPy arrays results in
-different behavior; see :meth:`Group.__setitem__` for details.
-
-In addition, the following behavior approximates the Python dictionary API:
-
-- Container syntax (``if name in group``)
-- Iteration yields member names (``for name in group``)
-- Length (``len(group)``)
-- :meth:`listnames <Group.listnames>`
-- :meth:`iternames <Group.iternames>`
-- :meth:`listobjects <Group.listobjects>`
-- :meth:`iterobjects <Group.iterobjects>`
-- :meth:`listitems <Group.listitems>`
-- :meth:`iteritems <Group.iteritems>`
-
-Reference
----------
-
-.. class:: Group
-
- .. attribute:: name
-
- Full name of this group in the file (e.g. ``/grp/thisgroup``)
-
- .. attribute:: attrs
-
- Dictionary-like object which provides access to this group's
- HDF5 attributes. See :ref:`attributes` for details.
-
- .. method:: __getitem__(name) -> Group or Dataset
-
- Open an object in this group.
-
- .. method:: __setitem__(name, object)
-
- Add the given object to the group.
-
- The action taken depends on the type of object assigned:
-
- **Named HDF5 object** (Dataset, Group, Datatype)
- A hard link is created in this group which points to the
- given object.
-
- **Numpy ndarray**
- The array is converted to a dataset object, with default
- settings (contiguous storage, etc.). See :meth:`create_dataset`
- for a more flexible way to do this.
-
- **Numpy dtype**
- Commit a copy of the datatype as a
- :ref:`named datatype <named_types>` in the file.
-
- **Anything else**
- Attempt to convert it to an ndarray and store it. Scalar
- values are stored as scalar datasets. Raise ValueError if we
- can't understand the resulting array dtype.
-
- If a group member of the same name already exists, the assignment
- will fail.
-
- .. method:: __delitem__(name)
-
- Remove (unlink) this member.
-
- .. method:: create_group(name) -> Group
-
- Create a new HDF5 group.
-
- Fails with H5Error if the group already exists.
-
- .. method:: require_group(name) -> Group
-
- Open the specified HDF5 group, creating it if it doesn't exist.
-
- Fails with H5Error if an incompatible object (dataset or named type)
- already exists.
-
- .. method:: create_dataset(name, [shape, [dtype]], [data], **kwds) -> Dataset
-
- Create a new dataset. There are two logical ways to specify the dataset:
-
- 1. Give the shape, and optionally the dtype. If the dtype is not given,
- single-precision floating point ('=f4') will be assumed.
- 2. Give a NumPy array (or anything that can be converted to a NumPy array)
- via the "data" argument. The shape and dtype of this array will be
- used, and the dataset will be initialized to its contents.
-
- Additional keyword parameters control the details of how the dataset is
- stored.
-
- **shape** (None or tuple)
- NumPy-style shape tuple. Required if data is not given.
-
- **dtype** (None or dtype)
- NumPy dtype (or anything that can be converted). Optional;
- the default is '=f4'. Will override the dtype of any data
- array given via the *data* parameter.
-
- **data** (None or ndarray)
- Either a NumPy ndarray or anything that can be converted to one.
-
- Keywords (see :ref:`dsetfeatures`):
-
- **chunks** (None, True or shape tuple)
- Store the dataset in chunked format. Automatically
- selected if any of the other keyword options are given. If you
- don't provide a shape tuple, the library will guess one for you.
-
- **compression** (None, string ["gzip" | "lzf" | "szip"] or int 0-9)
- Enable dataset compression. DEFLATE, LZF and (where available)
- SZIP are supported. An integer is interpreted as a GZIP level
- for backwards compatibility
-
- **compression_opts** (None, or special value)
- Setting for compression filter; legal values for each filter
- type are:
-
- ====== ======================================
- "gzip" Integer 0-9
- "lzf" (none allowed)
- "szip" 2-tuple ('ec'|'nn', even integer 0-32)
- ====== ======================================
-
- See the ``filters`` module for a detailed description of each
- of these filters.
-
- **shuffle** (True/False)
- Enable/disable data shuffling, which can improve compression
- performance. Automatically enabled when compression is used.
-
- **fletcher32** (True/False)
- Enable Fletcher32 error detection; may be used with or without
- compression.
-
- **maxshape** (None or shape tuple)
- Make the dataset extendable, up to this maximum shape. Should be a
- NumPy-style shape tuple. Dimensions with value None have no upper
- limit.
-
- .. method:: require_dataset(name, [shape, [dtype]], [data], **kwds) -> Dataset
-
- Open a new dataset, creating one if it doesn't exist.
-
- This method operates exactly like :meth:`create_dataset`, except that if
- a dataset with compatible shape and dtype already exists, it is opened
- instead. The additional keyword arguments are only honored when actually
- creating a dataset; they are ignored for the comparison.
-
- If an existing incompatible object (Group or Datatype) already exists
- with the given name, fails with H5Error.
-
- .. method:: copy(source, dest, name=None)
-
- **Only available with HDF5 1.8**
-
- Recusively copy an object from one location to another, or between files.
-
- Copies the given object, and (if it is a group) all objects below it in
- the hierarchy. The destination need not be in the same file.
-
- **source** (Group, Dataset, Datatype or str)
- Source object or path.
-
- **dest** (Group or str)
- Destination. Must be either Group or path. If a Group object, it may
- be in a different file.
-
- **name** (None or str)
- If the destination is a Group object, you can override the name
- for the newly created member. Otherwise a new name will be chosen
- using basename(source.name).
-
- .. method:: visit(func) -> None or return value from func
-
- **Only available with HDF5 1.8**
-
- Recursively iterate a callable over objects in this group.
-
- You supply a callable (function, method or callable object); it
- will be called exactly once for each link in this group and every
- group below it. Your callable must conform to the signature::
-
- func(<member name>) -> <None or return value>
-
- Returning None continues iteration, returning anything else stops
- and immediately returns that value from the visit method. No
- particular order of iteration within groups is guranteed.
-
- Example::
-
- >>> # List the entire contents of the file
- >>> f = File("foo.hdf5")
- >>> list_of_names = []
- >>> f.visit(list_of_names.append)
-
- .. method:: visititems(func) -> None or return value from func
-
- **Only available with HDF5 1.8**
-
- Recursively visit names and objects in this group and subgroups.
-
- You supply a callable (function, method or callable object); it
- will be called exactly once for each link in this group and every
- group below it. Your callable must conform to the signature::
-
- func(<member name>, <object>) -> <None or return value>
-
- Returning None continues iteration, returning anything else stops
- and immediately returns that value from the visit method. No
- particular order of iteration within groups is guranteed.
-
- Example::
-
- # Get a list of all datasets in the file
- >>> mylist = []
- >>> def func(name, obj):
- ... if isinstance(obj, Dataset):
- ... mylist.append(name)
- ...
- >>> f = File('foo.hdf5')
- >>> f.visititems(func)
-
- .. method:: __len__
-
- Number of group members
-
- .. method:: __iter__
-
- Yields the names of group members
-
- .. method:: __contains__(name)
-
- See if the given name is in this group.
-
- .. method:: listnames
-
- Get a list of member names
-
- .. method:: iternames
-
- Get an iterator over member names. Equivalent to iter(group).
-
- .. method:: listobjects
-
- Get a list with all objects in this group.
-
- .. method:: iterobjects
-
- Get an iterator over objects in this group
-
- .. method:: listitems
-
- Get an list of (name, object) pairs for the members of this group.
-
- .. method:: iteritems
-
- Get an iterator over (name, object) pairs for the members of this group.
-
-.. _datasets:
-
-Datasets
-========
-
-Datasets are where most of the information in an HDF5 file resides. Like
-NumPy arrays, they are homogenous collections of data elements, with an
-immutable datatype and (hyper)rectangular shape. Unlike NumPy arrays, they
-support a variety of transparent storage features such as compression,
-error-detection, and chunked I/O.
-
-Metadata can be associated with an HDF5 dataset in the form of an "attribute".
-It's recommended that you use this scheme for any small bits of information
-you want to associate with the dataset. For example, a descriptive title,
-digitizer settings, or data collection time are appropriate things to store
-as HDF5 attributes.
-
-Datasets are created using either :meth:`Group.create_dataset` or
-:meth:`Group.require_dataset`. Existing datasets should be retrieved using
-the group indexing syntax (``dset = group["name"]``).
-
-A subset of the NumPy indexing techniques is supported, including the
-traditional extended-slice syntax, named-field access, and boolean arrays.
-Discrete coordinate selection is also supported via an special indexer class.
-
-Properties
-----------
-
-Like Numpy arrays, Dataset objects have attributes named "shape" and "dtype":
-
- >>> dset.dtype
- dtype('complex64')
- >>> dset.shape
- (4, 5)
-
-
-.. _dsetfeatures:
-
-Special features
-----------------
-
-Unlike memory-resident NumPy arrays, HDF5 datasets support a number of optional
-features. These are enabled by the keywords provided to
-:meth:`Group.create_dataset`. Some of the more useful are:
-
-Compression
- Transparent compression (keyword *compression*) can substantially reduce
- the storage space needed for the dataset. Beginning with h5py 1.1,
- three techniques are available, "gzip", "lzf" and "szip". See the
- ``filters`` module for more information.
-
-Error-Detection
- All versions of HDF5 include the *fletcher32* checksum filter, which enables
- read-time error detection for datasets. If part of a dataset becomes
- corrupted, a read operation on that section will immediately fail with
- H5Error.
-
-Resizing
- When using HDF5 1.8,
- datasets can be resized, up to a maximum value provided at creation time.
- You can specify this maximum size via the *maxshape* argument to
- :meth:`create_dataset <Group.create_dataset>` or
- :meth:`require_dataset <Group.require_dataset>`. Shape elements with the
- value ``None`` indicate unlimited dimensions.
-
- Later calls to :meth:`Dataset.resize` will modify the shape in-place::
-
- >>> dset = grp.create_dataset((10,10), '=f8', maxshape=(None, None))
- >>> dset.shape
- (10, 10)
- >>> dset.resize((20,20))
- >>> dset.shape
- (20, 20)
-
- You can also resize a single axis at a time::
-
- >>> dset.resize(35, axis=1)
- >>> dset.shape
- (20, 35)
-
- Resizing an array with existing data works differently than in NumPy; if
- any axis shrinks, the data in the missing region is discarded. Data does
- not "rearrange" itself as it does when resizing a NumPy array.
-
- .. note::
- Only datasets stored in "chunked" format can be resized. This format
- is automatically selected when any of the advanced storage options is
- used, or a *maxshape* tuple is provided. By default an appropriate
- chunk size is selected based on the shape and type of the dataset; you
- can also manually specify a chunk shape via the ``chunks`` keyword.
-
-.. _slicing_access:
-
-Slicing access
---------------
-
-The best way to get at data is to use the traditional NumPy extended-slicing
-syntax. Slice specifications are translated directly to HDF5 *hyperslab*
-selections, and are are a fast and efficient way to access data in the file.
-The following slicing arguments are recognized:
-
- * Numbers: anything that can be converted to a Python long
- * Slice objects: please note negative values are not allowed
- * Field names, in the case of compound data
- * At most one ``Ellipsis`` (``...``) object
-
-Here are a few examples (output omitted)
-
- >>> dset = f.create_dataset("MyDataset", data=numpy.ones((10,10,10),'=f8'))
- >>> dset[0,0,0]
- >>> dset[0,2:10,1:9:3]
- >>> dset[0,...]
- >>> dset[:,::2,5]
-
-Simple array broadcasting is also supported:
-
- >>> dset[0] # Equivalent to dset[0,...]
-
-For compound data, you can specify multiple field names alongside the
-numeric slices:
-
- >>> dset["FieldA"]
- >>> dset[0,:,4:5, "FieldA", "FieldB"]
- >>> dset[0, ..., "FieldC"]
-
-Coordinate lists
-----------------
-
-For any axis, you can provide an explicit list of points you want; for a
-dataset with shape (10, 10)::
-
- >>> dset.shape
- (10, 10)
- >>> result = dset[0, [1,3,8]]
- >>> result.shape
- (3,)
- >>> result = dset[1:6, [5,8,9]]
- >>> result.shape
- (5, 3)
-
-The following restrictions exist:
-
-* List selections may not be empty
-* Selection coordinates must be given in increasing order
-* Duplicate selections are ignored
-
-.. _sparse_selection:
-
-Sparse selection
-----------------
-
-Additional mechanisms exist for the case of scattered and/or sparse selection,
-for which slab or row-based techniques may not be appropriate.
-
-Boolean "mask" arrays can be used to specify a selection. The result of
-this operation is a 1-D array with elements arranged in the standard NumPy
-(C-style) order:
-
- >>> arr = numpy.arange(100).reshape((10,10))
- >>> dset = f.create_dataset("MyDataset", data=arr)
- >>> result = dset[arr > 50]
- >>> result.shape
- (49,)
-
-Advanced selection
-------------------
-
-The ``selections`` module contains additional classes which provide access to
-HDF5 dataspace selection techniques, including point-based selection. These
-are especially useful for read_direct and write_direct.
-
-Length and iteration
---------------------
-
-As with NumPy arrays, the ``len()`` of a dataset is the length of the first
-axis. Since Python's ``len`` is limited by the size of a C long, it's
-recommended you use the syntax ``dataset.len()`` instead of ``len(dataset)``
-on 32-bit platforms, if you expect the length of the first row to exceed 2**32.
-
-Iterating over a dataset iterates over the first axis. However, modifications
-to the yielded data are not recorded in the file. Resizing a dataset while
-iterating has undefined results.
-
-Reference
----------
-
-.. class:: Dataset
-
- Represents an HDF5 dataset. All properties are read-only.
-
- .. attribute:: name
-
- Full name of this dataset in the file (e.g. ``/grp/MyDataset``)
-
- .. attribute:: attrs
-
- Provides access to HDF5 attributes; see :ref:`attributes`.
-
- .. attribute:: shape
-
- Numpy-style shape tuple with dataset dimensions
-
- .. attribute:: dtype
-
- Numpy dtype object representing the dataset type
-
- .. attribute:: value
-
- Special read-only property; for a regular dataset, it's equivalent to
- dset[:] (an ndarray with all points), but for a scalar dataset, it's
- a NumPy scalar instead of an 0-dimensional ndarray.
-
- .. attribute:: chunks
-
- Dataset chunk size, or None if chunked layout isn't used.
-
- .. attribute:: compression
-
- None or a string indicating the compression strategy;
- one of "gzip", "lzf", or "lzf".
-
- .. attribute:: compression_opts
-
- Setting for the compression filter
-
- .. attribute:: shuffle
-
- Is the shuffle filter being used? (T/F)
-
- .. attribute:: fletcher32
-
- Is the fletcher32 filter (error detection) being used? (T/F)
-
- .. attribute:: maxshape
-
- Maximum allowed size of the dataset, as specified when it was created.
-
- .. method:: __getitem__(*args) -> NumPy ndarray
-
- Read a slice from the dataset. See :ref:`slicing_access`.
-
- .. method:: __setitem__(*args, val)
-
- Write to the dataset. See :ref:`slicing_access`.
-
- .. method:: read_direct(dest, source_sel=None, dest_sel=None)
-
- Read directly from HDF5 into an existing NumPy array. The "source_sel"
- and "dest_sel" arguments may be Selection instances (from the
- selections module) or the output of ``numpy.s_``. Standard broadcasting
- is supported.
-
- .. method:: write_direct(source, source_sel=None, dest_sel=None)
-
- Write directly to HDF5 from a NumPy array. The "source_sel"
- and "dest_sel" arguments may be Selection instances (from the
- selections module) or the output of ``numpy.s_``. Standard broadcasting
- is supported.
-
- .. method:: resize(shape, axis=None)
-
- Change the size of the dataset to this new shape. Must be compatible
- with the *maxshape* as specified when the dataset was created. If
- the keyword *axis* is provided, the argument should be a single
- integer instead; that axis only will be modified.
-
- **Only available with HDF5 1.8**
-
- .. method:: __len__
-
- The length of the first axis in the dataset (TypeError if scalar).
- This **does not work** on 32-bit platforms, if the axis in question
- is larger than 2^32. Use :meth:`len` instead.
-
- .. method:: len()
-
- The length of the first axis in the dataset (TypeError if scalar).
- Works on all platforms.
-
- .. method:: __iter__
-
- Iterate over rows (first axis) in the dataset. TypeError if scalar.
-
-
-.. _attributes:
-
-Attributes
-==========
-
-Groups and datasets can have small bits of named information attached to them.
-This is the official way to store metadata in HDF5. Each of these objects
-has a small proxy object (:class:`AttributeManager`) attached to it as
-``<obj>.attrs``. This dictionary-like object works like a :class:`Group`
-object, with the following differences:
-
-- Entries may only be scalars and NumPy arrays
-- Each attribute must be small (recommended < 64k for HDF5 1.6)
-- No partial I/O (i.e. slicing) is allowed for arrays
-
-They support the same dictionary API as groups, including the following:
-
-- Container syntax (``if name in obj.attrs``)
-- Iteration yields member names (``for name in obj.attrs``)
-- Number of attributes (``len(obj.attrs)``)
-- :meth:`listnames <AttributeManager.listnames>`
-- :meth:`iternames <AttributeManager.iternames>`
-- :meth:`listobjects <AttributeManager.listobjects>`
-- :meth:`iterobjects <AttributeManager.iterobjects>`
-- :meth:`listitems <AttributeManager.listitems>`
-- :meth:`iteritems <AttributeManager.iteritems>`
-
-Reference
----------
-
-.. class:: AttributeManager
-
- .. method:: __getitem__(name) -> NumPy scalar or ndarray
-
- Retrieve an attribute given a string name.
-
- .. method:: __setitem__(name, value)
-
- Set an attribute. Value must be convertible to a NumPy scalar
- or array.
-
- .. method:: __delitem__(name)
-
- Delete an attribute.
-
- .. method:: __len__
-
- Number of attributes
-
- .. method:: __iter__
-
- Yields the names of attributes
-
- .. method:: __contains__(name)
-
- See if the given attribute is present
-
- .. method:: listnames
-
- Get a list of attribute names
-
- .. method:: iternames
-
- Get an iterator over attribute names
-
- .. method:: listobjects
-
- Get a list with all attribute values
-
- .. method:: iterobjects
-
- Get an iterator over attribute values
-
- .. method:: listitems
- Get an list of (name, value) pairs for all attributes.
- .. method:: iteritems
- Get an iterator over (name, value) pairs
.. _named_types:
diff --git a/docs/source/guide/vl.rst b/docs/source/guide/vl.rst
new file mode 100644
index 0000000..191f2f3
--- /dev/null
+++ b/docs/source/guide/vl.rst
@@ -0,0 +1,59 @@
+=========================
+VL and Enum types in h5py
+=========================
+
+HDF5 supports a few types which have no direct NumPy equivalent. Among the
+most useful and widely used are *variable-length* (VL) types, and enumerated
+types. As of version 1.2, h5py fully supports HDF5 enums, and has partial
+support for VL types.
+
+VL strings
+----------
+
+In HDF5, data in VL format is stored as arbitrary-length vectors of a base
+type. In particular, strings are stored C-style in null-terminated buffers.
+NumPy has no native mechanism to support this. Unfortunately, this is the
+de facto standard for representing strings in the HDF5 C API, and in many
+HDF5 applications.
+
+Thankfully, NumPy has a generic pointer type in the form of the "object" ("O")
+dtype. In h5py 1.2, variable-length strings are mapped to object arrays. A
+small amount of metadata attached to an "O" dtype tells h5py that its contents
+should be converted to VL strings when stored in the file.
+
+VL functions
+------------
+
+Existing VL strings can be read and written to with no additional effort;
+Python strings and fixed-length NumPy strings can be auto-converted to VL
+data and stored. However, creating VL data requires the use of a special
+"hinted" dtype object. Two functions are provided at the package level to
+perform this function:
+
+ .. function:: h5py.new_vlen(basetype)
+
+ Create a new object dtype which represents a VL type. Currently
+ *basetype* must be the Python string type (str).
+
+ .. function:: h5py.get_vlen(dtype)
+
+ Get the base type of a variable-length dtype, or None if *dtype*
+ doesn't represent a VL type.
+
+Here's an example showing how to create a VL array of strings::
+
+ >>> f = h5py.File('foo.hdf5')
+ >>> dt = h5py.new_vlen(str)
+ >>> ds = f.create_dataset('VLDS', (100,100), dtype=dt)
+ >>> ds.dtype.kind
+ ... 'O'
+ >>> h5py.get_vlen(ds.dtype)
+ ... <type 'str'>
+
+
+
+
+
+
+
+
--
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