[python-hdf5storage] 39/152: Added and fixed documentation.
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Mon Feb 29 08:24:32 UTC 2016
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to annotated tag 0.1
in repository python-hdf5storage.
commit d997d007effb3b567833e4f78d47a82d1daec28b
Author: Freja Nordsiek <fnordsie at gmail.com>
Date: Sun Jan 26 21:32:19 2014 -0500
Added and fixed documentation.
---
hdf5storage/Marshallers.py | 12 ++++----
hdf5storage/__init__.py | 3 +-
hdf5storage/core.py | 32 +++++++++++++++------
hdf5storage/lowlevel.py | 69 ++++++++++++++++++++++++++++++++++++++++++++++
hdf5storage/utilities.py | 39 ++++++++++++--------------
5 files changed, 119 insertions(+), 36 deletions(-)
diff --git a/hdf5storage/Marshallers.py b/hdf5storage/Marshallers.py
index 33974b7..dcdcd45 100644
--- a/hdf5storage/Marshallers.py
+++ b/hdf5storage/Marshallers.py
@@ -47,7 +47,9 @@ class TypeMarshaller(object):
Subclasses should run this class's ``__init__()`` first
thing. Inheritance information is in the **Notes** section of each
- method.
+ method. Generally, ``read``, ``write``, and ``write_metadata`` need
+ to be overridden and the different attributes set to the proper
+ values.
Attributes
----------
@@ -165,7 +167,7 @@ class TypeMarshaller(object):
data
The object to write to file.
type_string : str or None
- The type string for 'data'. If it is ``None``, one will have
+ The type string for `data`. If it is ``None``, one will have
to be gotten by ``get_type_string``.
options : hdf5storage.core.Options
hdf5storage options object.
@@ -187,8 +189,8 @@ class TypeMarshaller(object):
def write_metadata(self, f, grp, name, data, type_string, options):
""" Writes an object to file.
- Writes the metadata for a Python object 'data' to file at 'name'
- in h5py.Group 'grp'. Metadata is written to HDF5
+ Writes the metadata for a Python object `data` to file at `name`
+ in h5py.Group `grp`. Metadata is written to HDF5
Attributes. Existing Attributes that are not being used are
deleted.
@@ -204,7 +206,7 @@ class TypeMarshaller(object):
data
The object to write to file.
type_string : str or None
- The type string for 'data'. If it is ``None``, one will have
+ The type string for `data`. If it is ``None``, one will have
to be gotten by ``get_type_string``.
options : hdf5storage.core.Options
hdf5storage options object.
diff --git a/hdf5storage/__init__.py b/hdf5storage/__init__.py
index 997aaca..704b19f 100644
--- a/hdf5storage/__init__.py
+++ b/hdf5storage/__init__.py
@@ -33,4 +33,5 @@ Version 0.1
__version__ = "0.1"
-from hdf5storage.core import write, read, MarshallerCollection
+from hdf5storage.core import write, read, MarshallerCollection, \
+ Options, Hdf5storageError, CantReadError
diff --git a/hdf5storage/core.py b/hdf5storage/core.py
index 178bb45..dc117d7 100644
--- a/hdf5storage/core.py
+++ b/hdf5storage/core.py
@@ -23,6 +23,7 @@
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
""" Module contains the high level read/write interface and code.
"""
@@ -38,7 +39,8 @@ import h5py
from hdf5storage.utilities import *
-from hdf5storage.lowlevel import write_data, read_data, CantReadError
+from hdf5storage.lowlevel import write_data, read_data, \
+ Hdf5storageError, CantReadError
from hdf5storage import Marshallers
@@ -88,6 +90,8 @@ class Options(object):
See Attributes.
complex_names : tuple of two str, optional
See Attributes.
+ marshaller_collection : MarshallerCollection, optional
+ See Attributes.
Attributes
----------
@@ -116,7 +120,8 @@ class Options(object):
convert_bools_to_uint8=False,
reverse_dimension_order=False,
store_shape_for_empty=False,
- complex_names=('r', 'i')):
+ complex_names=('r', 'i'),
+ marshaller_collection=None):
# Set the defaults.
self._store_type_information = True
@@ -149,9 +154,19 @@ class Options(object):
self.scalar_options = {}
self.array_options = {}
- # Use the default collection of marshallers.
+ # Use the given marshaller collection if it was
+ # given. Otherwise, use the default.
- self.marshaller_collection = MarshallerCollection()
+ #: Collection of marshallers to disk.
+ #:
+ #: MarshallerCollection
+ #:
+ #: See Also
+ #: --------
+ #: MarshallerCollection
+ self.marshaller_collection = marshaller_collection
+ if not isinstance(marshaller_collection, MarshallerCollection):
+ self.marshaller_collection = MarshallerCollection()
@property
def store_type_information(self):
@@ -275,7 +290,7 @@ class Options(object):
If ``True`` (defaults to ``False`` unless MATLAB compatibility
is being done), string types except for ``numpy.str_``
- (``str``, ``bytes``, and ``numpy.string_``) are converted to
+ (``str``, ``bytes``, and ``numpy.bytes_``) are converted to
UTF-16 before being written to file.
Must be ``True`` if doing MATLAB compatibility. MATLAB uses
@@ -388,7 +403,7 @@ class Options(object):
``(r, i)`` where `r` and `i` are two ``str``. When reading and
writing complex numbers, the real part gets the name in `r` and
- the imaginary part gets the name in `i`. :py:mod:`h5py` uses
+ the imaginary part gets the name in `i`. ``h5py`` uses
``('r', 'i')`` by default, unless MATLAB compatibility is being
done in which case its default is ``('real', 'imag')``.
@@ -638,7 +653,8 @@ def write(filename='data.h5', name='/data', data=None,
convert_strings_to_utf16=False,
convert_bools_to_uint8=False,
store_shape_for_empty=False,
- complex_names=('r', 'i')):
+ complex_names=('r', 'i'),
+ marshaller_collection=None):
# Pack the different options into an Options class. The easiest way
# to do this is to get all the arguments (locals() gets them since
# they are the only symbols in the local table at this point) and
@@ -750,7 +766,7 @@ def write(filename='data.h5', name='/data', data=None,
def read(filename='data.h5', name='/data', MATLAB_compatible=False,
- reverse_dimension_order=False, complex_names=('r', 'i')):
+ reverse_dimension_order=False, marshaller_collection=None):
# Pack the different options into an Options class. The easiest way
# to do this is to get all the arguments (locals() gets them since
# they are the only symbols in the local table at this point) and
diff --git a/hdf5storage/lowlevel.py b/hdf5storage/lowlevel.py
index bb40046..a6259cf 100644
--- a/hdf5storage/lowlevel.py
+++ b/hdf5storage/lowlevel.py
@@ -23,6 +23,9 @@
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+""" Module of Exceptions and low level read and write functions.
+
+"""
import posixpath
@@ -42,6 +45,39 @@ class CantReadError(Hdf5storageError):
def write_data(f, grp, name, data, type_string, options):
+ """ Writes a piece of data into an open HDF5 file.
+
+ Low level function to store a Python type (`data`) into the
+ specified Group.
+
+ Parameters
+ ----------
+ f : h5py.File
+ The open HDF5 file.
+ grp : h5py.Group or h5py.File
+ The Group to place the data in.
+ name : str
+ The name to write the data to.
+ data : any
+ The data to write.
+ type_string : str or None
+ The type string of the data, or ``None`` to deduce
+ automatically.
+ options : hdf5storage.core.Options
+ The options to use when writing.
+
+ Raises
+ ------
+ NotImplementedError
+ If writing `data` is not supported.
+
+ See Also
+ --------
+ hdf5storage.core.write : Higher level version.
+ read_data
+ hdf5storage.core.Options
+
+ """
# Get the marshaller for type(data).
tp = type(data)
@@ -59,6 +95,39 @@ def write_data(f, grp, name, data, type_string, options):
def read_data(f, grp, name, options):
+ """ Writes a piece of data into an open HDF5 file.
+
+ Low level function to read a Python type of the specified name from
+ specified Group.
+
+ Parameters
+ ----------
+ f : h5py.File
+ The open HDF5 file.
+ grp : h5py.Group or h5py.File
+ The Group to read the data from.
+ name : str
+ The name of the data to read.
+ options : hdf5storage.core.Options
+ The options to use when reading.
+
+ Returns
+ -------
+ data
+ The data named `name` in Group `grp`.
+
+ Raises
+ ------
+ CantReadError
+ If the data cannot be read successfully.
+
+ See Also
+ --------
+ hdf5storage.core.read : Higher level version.
+ write_data
+ hdf5storage.core.Options
+
+ """
# If name isn't found, return error.
if name not in grp:
raise CantReadError('Could not find '
diff --git a/hdf5storage/utilities.py b/hdf5storage/utilities.py
index ef907dc..f1bc8eb 100644
--- a/hdf5storage/utilities.py
+++ b/hdf5storage/utilities.py
@@ -23,6 +23,7 @@
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
""" Module of functions to set and delete HDF5 attributes.
"""
@@ -36,7 +37,7 @@ def decode_to_str(data):
Decodes `data` to a Python str, which is. If it can't be decoded, it
is returned as is. Unsigned integers, Python ``bytes``, and Numpy
- strings (``numpy.str_`` and ``numpy.string_``).
+ strings (``numpy.str_`` and ``numpy.bytes_``).
Parameters
----------
@@ -89,7 +90,7 @@ def decode_to_numpy_unicode(data):
Decodes `data` to a Numpy unicode string (UTF-32), which is
``numpy.str_``. If it can't be decoded, it is returned as
is. Unsigned integers, Python string types (``str``, ``bytes``), and
- ``numpy.string_`` are supported.
+ ``numpy.bytes_`` are supported.
Parameters
----------
@@ -124,10 +125,10 @@ def decode_to_numpy_unicode(data):
def decode_to_numpy_ascii(data):
- """ Decodes data to Numpy ASCII string (string_).
+ """ Decodes data to Numpy ASCII string (bytes_).
Decodes `data` to a Numpy ASCII string, which is
- ``numpy.string_``. If it can't be decoded, it is returned as
+ ``numpy.bytes_``. If it can't be decoded, it is returned as
is. Unsigned integers, Python string types (``str``, ``bytes``), and
``numpy.str_`` (UTF-32) are supported.
@@ -138,15 +139,15 @@ def decode_to_numpy_ascii(data):
Returns
-------
- numpy.string_ or data
- If `data` can be decoded into a ``numpy.string_``, the decoded
+ numpy.bytes_ or data
+ If `data` can be decoded into a ``numpy.bytes_``, the decoded
version is returned. Otherwise, `data` is returned unchanged.
See Also
--------
decode_to_str
decode_to_numpy_unicode
- numpy.string_
+ numpy.bytes_
"""
# Convert first to a Python str if it isn't already an np.string_.
@@ -304,8 +305,7 @@ def get_attribute(target, name):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to get the
- attribute of.
+ Dataset or Group to get the attribute of.
name : str
Name of the attribute to get.
@@ -330,8 +330,7 @@ def get_attribute_string(target, name):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to get the
- string attribute of.
+ Dataset or Group to get the string attribute of.
name : str
Name of the attribute to get.
@@ -366,11 +365,10 @@ def set_attribute(target, name, value):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to set the
- attribute of.
+ Dataset or Group to set the attribute of.
name : str
Name of the attribute to set.
- value : numpy type other than :py:class:`str_`
+ value : numpy type other than ``numpy.str_``
Value to set the attribute to.
"""
@@ -392,13 +390,12 @@ def set_attribute_string(target, name, value):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to set the
- attribute of.
+ Dataset or Group to set the string attribute of.
name : str
Name of the attribute to set.
value : string
Value to set the attribute to. Can be any sort of string type
- that will convert to a :py:class:`numpy.string_`
+ that will convert to a ``numpy.bytes_``
"""
set_attribute(target, name, np.string_(value))
@@ -414,13 +411,12 @@ def set_attribute_string_array(target, name, string_list):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to set the
- attribute of.
+ Dataset or Group to set the string array attribute of.
name : str
Name of the attribute to set.
string_list : list, tuple
List of strings to set the attribute to. Can be any string type
- that will convert to a :py:class:`numpy.string_`
+ that will convert to a ``numpy.bytes_``
"""
target.attrs.create(name, np.string_(string_list),
@@ -435,8 +431,7 @@ def del_attribute(target, name):
Parameters
----------
target : Dataset or Group
- :py:class:`h5py.Dataset` or :py:class:`h5py.Group` to set the
- attribute of.
+ Dataset or Group to delete attribute of.
name : str
Name of the attribute to delete.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/python-hdf5storage.git
More information about the debian-science-commits
mailing list