[h5py] 141/455: More docs modifications
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:26 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to annotated tag 1.3.0
in repository h5py.
commit 3e1d6d10026dee739fabab4752332e3064d1ca6b
Author: andrewcollette <andrew.collette at gmail.com>
Date: Fri Oct 17 22:25:06 2008 +0000
More docs modifications
---
docs/source/conf.py | 3 +-
docs/source/index.rst | 1 -
docs/source/low.rst | 175 ----------------------------------
docs_api/source/conf.py | 6 +-
docs_api/source/index.rst | 19 ----
{docs => docs_api}/source/low/h5.rst | 0
{docs => docs_api}/source/low/h5a.rst | 0
{docs => docs_api}/source/low/h5d.rst | 0
{docs => docs_api}/source/low/h5f.rst | 0
{docs => docs_api}/source/low/h5g.rst | 0
{docs => docs_api}/source/low/h5i.rst | 0
{docs => docs_api}/source/low/h5p.rst | 0
{docs => docs_api}/source/low/h5r.rst | 0
{docs => docs_api}/source/low/h5s.rst | 0
{docs => docs_api}/source/low/h5t.rst | 0
{docs => docs_api}/source/low/h5z.rst | 0
h5py/h5.pyx | 11 ---
h5py/version.py | 6 ++
18 files changed, 10 insertions(+), 211 deletions(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 2496f51..503fa8b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -23,8 +23,7 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-sys.path += [os.path.abspath('.')]
-extensions = ['sphinx.ext.autodoc', 'automod']
+extensions = ['sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 70ba088..ba26fd8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -39,7 +39,6 @@ Contents:
build
quick
datasets
- low
threads
licenses
diff --git a/docs/source/low.rst b/docs/source/low.rst
deleted file mode 100644
index 8a05eb1..0000000
--- a/docs/source/low.rst
+++ /dev/null
@@ -1,175 +0,0 @@
-==============================
-Low-level (``h5py.h5*``) guide
-==============================
-
-This is a general overview of the lowest-level API in h5py, the layer that
-calls into HDF5 directly. A lot of effort has been put into making even this
-component useful in a Python context. It provides the most general interface
-to HDF5, including the vast majority of the C library.
-
-You'll probably also find the `official HDF5 documentation`__ useful as a guide
-to how the library itself operates. In particular, the HDF5 User Guide is
-an excellent description of each major component.
-
-__ http://h5py.alfven.org/docs
-__ http://hdf.ncsa.uiuc.edu/HDF5/doc/index.html
-
-Low-level API reference
-=======================
-
-.. toctree::
- :maxdepth: 2
-
- low/h5
- low/h5a
- low/h5d
- low/h5f
- low/h5g
- low/h5i
- low/h5p
- low/h5r
- low/h5s
- low/h5t
- low/h5z
-
-Library organization
-====================
-
-Modules
--------
-
-While HDF5 is a C library, and therefore uses on global namespace for all
-functions and constants, their naming scheme is designed to partition the API
-into modules of related code. H5py uses this as a guide for the Python-side
-module organization. For example, the Python wrapping of the HDF5 function
-``H5Dwrite`` is contained in module ``h5d``, while the Python equivalent of
-``H5Aiterate`` is in module ``h5a``.
-
-Identifier wrapping
--------------------
-
-No matter how complete, a library full of C functions is not very fun to use.
-Additionally, since HDF5 identifiers are natively expressed as integers, their
-lifespan must be manually tracked by the library user. This quickly becomes
-impossible for applications of even a moderate size; errors will lead to
-resource leaks or (in the worst case) accidentally invalidating identifiers.
-
-Rather than a straight C-API mapping, all HDF5 identifiers are presented as
-Python extension types. The root type ``h5.ObjectID`` provides a container
-for an integer identifier, which allows Python reference counting to manage
-the lifespan of the identifer. When no more references exist to the Python
-object, the HDF5 identifier is automatically closed.
-
- >>> from h5py import h5s
- >>> sid = h5s.create_simple( (2,3) )
- >>> sid
- 67108866 [1] (U) SpaceID
- >>> sid.id
- 67108866
-
-A side benefit is that many HDF5 functions take an identifier as their first
-argument. These are naturally expressed as methods on an identifier object.
-For example, the HDF5 function``H5Dwrite`` becomes the method
-``h5d.DatasetID.write``. Code using this technique is easier to write and
-maintain.
-
- >>> sid.select_hyperslab((0,0),(2,2))
- >>> sid.get_select_bounds()
- ((0L, 0L), (1L, 1L))
-
-State & Hashing
----------------
-
-Since the ``h5py.h5*`` family of modules is intended to be a straightforward
-interface to HDF5, almost all state information resides with the HDF5 library
-itself. A side effect of this is that the hash and equality operations on
-ObjectID instances are determined by the status of the underlying HDF5 object.
-For example, if two GroupID objects with different HDF5 integer identifiers
-point to the same group, they will have identical hashes and compare equal.
-Among other things, this means that you can reliably use identifiers as keys
-in a dictionary.
-
- >>> from h5py import h5f, h5g
- >>> fid = h5f.open('foo.hdf5')
- >>> grp1 = h5g.open(fid, '/')
- >>> grp2 = h5g.open(fid, '/')
- >>> grp1.id == grp2.id
- False
- >>> grp1 == grp2
- True
- >>> hash(grp1) == hash(grp2)
- True
- >>> x = {grp1: "The root group"}
- >>> x[grp2]
- 'The root group'
-
-.. note::
- Currently all subclasses of ObjectID are hashable, including "transient"
- identifiers like datatypes. A future version may restrict hashing to
- "committed", file-resident objects.
-
-Data Conversion
-===============
-
-The natural numerical layer between h5py and the Python user is NumPy. It
-provides the mechanism to transfer large datasets between HDF5 and Python
-analysis routines. Additionally, its type infrastructure ("dtype" objects)
-closely matches the HDF5 hierarchy of types. With very few exceptions, there
-is good mapping between NumPy dtypes and HDF5 basic types.
-
-The actual conversion between datatypes is performed by the optimised routines
-inside the HDF5 library; all h5py does is provide the mapping between NumPy
-and HDF5 type objects. Because the HDF5 typing system is more comprehensive
-than the NumPy system, this is an asymmetrical process.
-
-Translating from an HDF5 datatype object to a dtype results in the closest
-standard NumPy representation of the datatype:
-
- >>> from h5py import h5t
- >>> h5t.STD_I32LE
- 50331712 [1] (L) TypeIntegerID int32
- >>> h5t.STD_I32LE.dtype
- dtype('int32')
-
-In the vast majority of cases the two datatypes will have exactly identical
-binary layouts, but not always. For example, an HDF5 integer can have
-additional leading or trailing padding, which has no NumPy equivalent. In
-this case the dtype will capture the logical intent of the type (as a 32-bit
-signed integer), but not its layout.
-
-The reverse transformation (NumPy type to HDF5 type) is handled by a separate
-function. It's guaranteed to result in an exact, binary-compatible
-representation:
-
- >>> tid = h5t.py_create('=u8')
- >>> tid
- 50331956 [1] (U) TypeIntegerID uint64
-
-The HDF5 library contains translation routines which can handle almost any
-conversion between types of the same class, including odd precisions and
-padding combinations. This process is entirely transparent to the user.
-
-
-API Versioning
-==============
-
-HDF5 recently went though a major release, in the form of version 1.8.0.
-In addition to various stability improvements, it introduces a number of
-new and changed functions. Rather than force people to use a particular
-version, h5py deals with this by specifying an "API compatibility" level.
-In "1.6" mode, the extension can be compiled with either 1.6.X or 1.8.X, and
-will function identically. In this mode, only the functions from the 1.6.X
-series are exposed. In "1.8" mode, new features and function signatures from
-HDF5 1.8.X are available.
-
-Currently, while h5py can be built in both modes, not many 1.8.X features are
-available.
-
-
-
-
-
-
-
-
-
diff --git a/docs_api/source/conf.py b/docs_api/source/conf.py
index 2496f51..bda5050 100644
--- a/docs_api/source/conf.py
+++ b/docs_api/source/conf.py
@@ -36,16 +36,16 @@ source_suffix = '.rst'
master_doc = 'index'
# General substitutions.
-project = 'h5py'
+project = 'h5py Low-Level API'
copyright = '2008, Andrew Collette'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
#
# The short X.Y version.
-version = '0.3'
+version = '0.4'
# The full version, including alpha/beta/rc tags.
-release = '0.3.1'
+release = '0.4.0'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
diff --git a/docs_api/source/index.rst b/docs_api/source/index.rst
deleted file mode 100644
index baff5ce..0000000
--- a/docs_api/source/index.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-.. h5py documentation master file, created by sphinx-quickstart on Fri Oct 17 14:45:28 2008.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to h5py's documentation!
-================================
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
diff --git a/docs/source/low/h5.rst b/docs_api/source/low/h5.rst
similarity index 100%
rename from docs/source/low/h5.rst
rename to docs_api/source/low/h5.rst
diff --git a/docs/source/low/h5a.rst b/docs_api/source/low/h5a.rst
similarity index 100%
rename from docs/source/low/h5a.rst
rename to docs_api/source/low/h5a.rst
diff --git a/docs/source/low/h5d.rst b/docs_api/source/low/h5d.rst
similarity index 100%
rename from docs/source/low/h5d.rst
rename to docs_api/source/low/h5d.rst
diff --git a/docs/source/low/h5f.rst b/docs_api/source/low/h5f.rst
similarity index 100%
rename from docs/source/low/h5f.rst
rename to docs_api/source/low/h5f.rst
diff --git a/docs/source/low/h5g.rst b/docs_api/source/low/h5g.rst
similarity index 100%
rename from docs/source/low/h5g.rst
rename to docs_api/source/low/h5g.rst
diff --git a/docs/source/low/h5i.rst b/docs_api/source/low/h5i.rst
similarity index 100%
rename from docs/source/low/h5i.rst
rename to docs_api/source/low/h5i.rst
diff --git a/docs/source/low/h5p.rst b/docs_api/source/low/h5p.rst
similarity index 100%
rename from docs/source/low/h5p.rst
rename to docs_api/source/low/h5p.rst
diff --git a/docs/source/low/h5r.rst b/docs_api/source/low/h5r.rst
similarity index 100%
rename from docs/source/low/h5r.rst
rename to docs_api/source/low/h5r.rst
diff --git a/docs/source/low/h5s.rst b/docs_api/source/low/h5s.rst
similarity index 100%
rename from docs/source/low/h5s.rst
rename to docs_api/source/low/h5s.rst
diff --git a/docs/source/low/h5t.rst b/docs_api/source/low/h5t.rst
similarity index 100%
rename from docs/source/low/h5t.rst
rename to docs_api/source/low/h5t.rst
diff --git a/docs/source/low/h5z.rst b/docs_api/source/low/h5z.rst
similarity index 100%
rename from docs/source/low/h5z.rst
rename to docs_api/source/low/h5z.rst
diff --git a/h5py/h5.pyx b/h5py/h5.pyx
index e8368ce..746afee 100644
--- a/h5py/h5.pyx
+++ b/h5py/h5.pyx
@@ -17,17 +17,6 @@ __doc__ = \
enable HDF5 exception handline. It also enables debug logging, if the
library has been compiled with a nonzero debugging level.
- Useful things defined here:
-
- version String with h5py version (e.g. "0.2.0")
- version_tuple 3-tuple with h5py version (e.g. (0, 2, 0))
-
- hdf5_version: String with library version (e.g. "1.6.5")
- hdf5_version_tuple: 3-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: 2-tuple form of the version (e.g. (1,6))
-
All exception classes and error handling functions are also in this module.
"""
diff --git a/h5py/version.py b/h5py/version.py
index 62ebd1c..aa2e229 100644
--- a/h5py/version.py
+++ b/h5py/version.py
@@ -9,3 +9,9 @@ hdf5_version = "%d.%d.%d" % hdf5_version_tuple
api_version_tuple = _h5._api_version_tuple
api_version = "%d.%d" % api_version_tuple
+__doc__ = """\
+This is h5py **%s**
+
+* HDF5 version: **%s**
+* API compatibility: **%s**
+""" % (version, hdf5_version, api_version)
--
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