[h5py] 84/455: Introduce info.txt; auto-import highlevel objects in h5py __init__

[Ghislain Vaillant]

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 8d25f85c099107d2ac0532638b278b7f2046605a
Author: andrewcollette <andrew.collette at gmail.com>
Date:   Sat Jul 26 22:04:30 2008 +0000

    Introduce info.txt; auto-import highlevel objects in h5py __init__
---
 docs/info.txt    | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 h5py/__init__.py |  5 +++-
 h5py/h5.pyx      |  2 +-
 setup.py         | 14 +++++++----
 4 files changed, 89 insertions(+), 7 deletions(-)

diff --git a/docs/info.txt b/docs/info.txt
new file mode 100644
index 0000000..3109a80
--- /dev/null
+++ b/docs/info.txt
@@ -0,0 +1,75 @@
+
+
+Threading
+=========
+
+All h5py routines are thread-safe in the sense that they are implemented in
+C, and (with a few exceptions) hold the global intepreter lock until they
+finish.  From the standpoint of a Python programmer, they are atomic operations;
+the execution of all threads blocks until they complete.  This means you
+can call the same method on the same object from two different threads, and the
+two calls will execute serially without interfering with one another.
+
+Additionally, each ObjectID instance provides a reentrant lock via the property
+"pylock".  If you acquire this lock, the HDF5 structure you've got hold of
+is guaranteed not to be modified by another thread until you release it.  This
+is the case even your HDF5 structure is "pointed to" by different ObjectID
+instances.
+ 
+Non-Blocking Routines
+---------------------
+
+A few methods will release the global interpreter lock around I/O operations
+which can take a long time to complete.  These methods always acquire their
+own "pylock" lock before beginning.  They are still thread-safe in that
+multiple threads attempting to run the same routine will execute serially,
+although threads that do other things can run unimpeded.
+
+The following operations will release the GIL:
+    
+    * DatasetID.read
+    * DatasetID.write
+
+Customizing Locks
+-----------------
+
+Because applications that use h5py may have their own threading systems, the
+type of lock used is settable at runtime.  The settable property
+h5.config.RLock determines the lock class used.  This can be set to any
+callable which produces a reentrant lock.  It must implement the following
+methods:
+
+    __enter__(), __exit__()     For the Python context manager protocol
+    acquire(), release()        For manual lock management
+
+The default lock type is the native Python threading.RLock, but h5py makes no
+assumptions about the behavior or implementation of locks beyond reentrance and
+the existence of the four required methods above.
+
+ObjectID Hashing
+----------------
+
+H5py uses a global weak-reference dictionary to keep track of which lock goes
+with which ObjectID instance.  For this to work, there must be a way to
+identify which ObjectID instances point to the same HDF5 structure.  Two rules
+make this possible:
+
+    A. ObjectID instances which point to the same HDF5 structure must both
+       have the same hash() value.
+    B. ObjectID instances which point to the same HDF5 structure must evauluate
+       as equal.
+
+For named objects like datasets, groups, and files, the hash is derived from
+properties like fileno and objno, which are guaranteed by the library to be
+unique among open files.  For all other objects, the HDF5 identifier determines
+uniqueness.
+
+
+
+
+
+
+
+
+
+
diff --git a/h5py/__init__.py b/h5py/__init__.py
index 7cdbf48..f02274a 100644
--- a/h5py/__init__.py
+++ b/h5py/__init__.py
@@ -24,7 +24,10 @@ __doc__ = \
 
 import utils, h5, h5a, h5d, h5f, h5g, h5i, h5p, h5r, h5s, h5t, h5z, highlevel
 
+from highlevel import File, Group, Dataset, Datatype, AttributeManager
+
 __doc__ = __doc__ % (h5.version, h5.hdf5_version, h5.api_version)
 
 __all__ = ['h5', 'h5f', 'h5g', 'h5s', 'h5t', 'h5d', 'h5a', 'h5p',
-           'h5z', 'h5i', 'highlevel']
+           'h5z', 'h5i', 'File', 'Group', 'Dataset',
+           'Datatype', 'AttributeManager']
diff --git a/h5py/h5.pyx b/h5py/h5.pyx
index af5d0e1..69b808e 100644
--- a/h5py/h5.pyx
+++ b/h5py/h5.pyx
@@ -193,7 +193,7 @@ cdef class ObjectID:
 
     property pylock:
         """ RLock or equivalent for threads.  The same lock is returned for
-            equal objects (objects which point to the same HDF5 structure).
+            objects which point to the same HDF5 structure.
         """
         def __get__(self):
             if self._cfg is None:
diff --git a/setup.py b/setup.py
index b058fe2..2bc7a63 100644
--- a/setup.py
+++ b/setup.py
@@ -303,10 +303,11 @@ class dev(Command):
 
     def run(self):
         if self.clean:
-            try:
-                shutil.rmtree('build')
-            except OSError:
-                pass
+            for x in ('build','docs/html'):
+                try:
+                    shutil.rmtree(x)
+                except OSError:
+                    pass
             fnames = [ x+'.dep' for x in pyrex_sources ] + \
                      [ x+'.c' for x in pyrex_sources ] + \
                      [ 'MANIFEST']
@@ -320,9 +321,12 @@ class dev(Command):
         if self.doc:
             buildobj = self.distribution.get_command_obj('build')
             buildobj.run()
+            if not os.path.exists('docs/html'):
+                os.mkdir('docs', 0755)
+                os.mkdir('docs/html', 0755)
 
             retval = os.spawnlp(os.P_WAIT, 'epydoc', '-q', '--html',
-                        '-o', 'docs/', '--config', 'docs.cfg', 
+                        '-o', 'docs/html', '--config', 'docs.cfg', 
                         os.path.join(buildobj.build_lib, NAME) )
             if retval != 0:
                 raise DistutilsExecError("Could not run epydoc to build documentation.")

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/h5py.git