[h5py] 146/455: More doc fixes
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Thu Jul 2 18:19:27 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 65fc82886e273326ca03513bfe6b7a0505cae915
Author: andrewcollette <andrew.collette at gmail.com>
Date: Sat Oct 25 02:13:34 2008 +0000
More doc fixes
---
docs_api/source/automod.py | 237 ++++++++++++++++++++++++++++++---------------
h5py/h5f.pyx | 4 +-
h5py/h5p.pyx | 4 +-
h5py/h5p_dcid.pxi | 12 +--
4 files changed, 170 insertions(+), 87 deletions(-)
diff --git a/docs_api/source/automod.py b/docs_api/source/automod.py
index 1956eb1..6d41901 100644
--- a/docs_api/source/automod.py
+++ b/docs_api/source/automod.py
@@ -6,105 +6,179 @@
import re
from functools import partial
+# === Regexp replacement machinery ============================================
+
+role_expr = re.compile(r"(:.+:(?:`.+`)?)")
+
+def safe_replace(istr, expr, rpl):
+ """ Perform a role-safe replacement of all occurances of "expr", using
+ the callable "rpl".
+ """
+ outparts = []
+ for part in role_expr.split(istr):
+ if not role_expr.search(part):
+ part = expr.sub(rpl, part)
+ outparts.append(part)
+ return "".join(outparts)
+
+
+# === Replace literal class names =============================================
+
+class_base = r"""
+(?P<pre>
+ \W+
+)
+(?P<name>%s)
+(?P<post>
+ \W+
+)
+"""
-# --- Literal replacements for common class names ---
-
-class_types = { "ObjectID": "h5py.h5.ObjectID",
+class_exprs = { "ObjectID": "h5py.h5.ObjectID",
"GroupID": "h5py.h5g.GroupID",
"FileID": "h5py.h5f.FileID",
"DatasetID": "h5py.h5d.DatasetID",
"TypeID": "h5py.h5t.TypeID",
"[Dd]ataset creation property list": "h5py.h5p.PropDCID",
- "[Dd]ataset access property list": "h5py.h5p.PropDAID",
+ "[Dd]ataset transfer property list": "h5py.h5p.PropDXID",
"[Ff]ile creation property list": "h5py.h5p.PropFCID",
- "[Ff]ile access property list": "h5py.h5p.PropFAID"}
-
-
-def mkclass(ipt, cls):
- return ":class:`%s <%s>`" % (ipt, cls)
-
-replacements = {}
-replacements.update((x, mkclass(x,y)) for x, y in class_types.items())
-
-def replaceall(instring, rdict):
- for orig, new in rdict.iteritems():
- instring = instring.replace(orig, new)
- return instring
-
-
-# --- "Smart" regexp replacements for UPPER_CASE constant names ---
-
-# Just the constant name, with or without the h5x. prefix.
-# Legal constant names are of the form CONST" or "h5p.CONST"
-const_only = r"(?:h5[a-z]{0,2}\.)?[A-Z_][A-Z0-9_]+"
-
-# Constant name embeddded in context (whitespace, parens, etc.)
-const_pattern = r"(?:^|\s+)\W?%s\*?\W?\.?(?:$|\s+)" % const_only
-
-const_category = r"%s\*" % const_only
+ "[Ff]ile access property list": "h5py.h5p.PropFAID",
+ "[Ll]ink access property list": "h5py.h5p.PropLAID",
+ "[Ll]ink creation property list": "h5py.h5p.PropLCID",
+ "[Gg]roup creation property list": "h5py.h5p.PropGCID"}
+
+
+class_exprs = dict(
+ (re.compile(class_base % x.replace(" ",r"\s"), re.VERBOSE), y) \
+ for x, y in class_exprs.iteritems() )
+
+def replace_class(istr):
+
+ def rpl(target, match):
+ pre, name, post = match.group('pre', 'name', 'post')
+ return '%s:class:`%s <%s>`%s' % (pre, name, target, post)
+
+ for expr, target in class_exprs.iteritems():
+ rpl2 = partial(rpl, target)
+ istr = safe_replace(istr, expr, rpl2)
+
+ return istr
+
+# === Replace constant and category expressions ===============================
+
+# e.g. h5f.OBJ_ALL -> :data:`h5f.OBJ_ALL <h5py.h5f.OBJ_ALL>`
+# and h5f.OBJ* -> :ref:`h5f.OBJ* <ref.h5f.OBJ>`
+
+const_exclude = ['HDF5', 'API', 'H5', 'H5A', 'H5D', 'H5F', 'H5P', 'H5Z', 'INT',
+ 'UINT', 'STRING', 'LONG', 'PHIL', 'GIL', 'TUPLE', 'LIST',
+ 'FORTRAN', 'BOOL', 'NULL', 'NOT', 'SZIP']
+const_exclude = ["%s(?:\W|$)" % x for x in const_exclude]
+const_exclude = "|".join(const_exclude)
+
+const_expr = re.compile(r"""
+(?P<pre>
+ (?:^|\s+) # Must be preceeded by whitespace or string start
+ \W? # May have punctuation ( (CONST) or "CONST" )
+ (?!%s) # Exclude known list of non-constant objects
+)
+(?P<module>h5[a-z]{0,2}\.)? # Optional h5xx. prefix
+(?P<name>[A-Z_][A-Z0-9_]+) # The constant name itself
+(?P<wild>\*)? # Wildcard indicates this is a category
+(?P<post>
+ \W? # May have trailing punctuation
+ (?:$|\s+) # Must be followed by whitespace or end of string
+)
+""" % const_exclude, re.VERBOSE)
+
+def replace_constant(istr, current_module):
+
+ def rpl(match):
+ mod, name, wild = match.group('module', 'name', 'wild')
+ pre, post = match.group('pre', 'post')
+
+ if mod is None:
+ mod = current_module+'.'
+ displayname = name
+ else:
+ displayname = mod+name
-# These match the regexp but are not valid constants
-const_exclude = r"HDF5|API|H5|H5A|H5D|H5F|H5P|H5Z|" + \
- r"INT\s|UINT|STRING|LONG|PHIL|GIL|TUPLE|LIST|FORTRAN|" +\
- r"BOOL|NULL|\sNOT\s|\sSZIP\s"
+ if wild:
+ target = 'ref.'+mod+name
+ role = ':ref:'
+ displayname += '*'
+ else:
+ target = 'h5py.'+mod+name
+ role = ':data:'
-def replace_constant(instring, mod, match):
- """ Callback for re.sub, to generate the ReST for a constant in-place """
+ return '%s%s`%s <%s>`%s' % (pre, role, displayname, target, post)
- matchstring = instring[match.start():match.end()]
+ return safe_replace(istr, const_expr, rpl)
- if re.search(const_exclude, matchstring):
- return matchstring
- if re.search(const_category, matchstring):
- display = re.findall(const_category, matchstring)[0]
- target = display[0:-2]
- target = 'ref.'+target if 'h5' in target else 'ref.%s.%s' % (mod.split('.')[-1], target)
- rpl = ':ref:`%s <%s>`' % (display, target)
- #print rpl
- return re.sub(const_category, rpl, matchstring)
- else:
- display = re.findall(const_only, matchstring)[0]
- target = display
- target = 'h5py.'+target if 'h5' in target else '%s.%s' % (mod, target)
- rpl = ':data:`%s <%s>`' % (display, target)
- return re.sub(const_only, rpl, matchstring)
+# === Replace literal references to modules ===================================
+mod_expr = re.compile(r"""
+(?P<pre>
+ (?:^|\s+) # Must be preceeded by whitespace
+ \W? # Optional opening paren/quote/whatever
+)
+(?!h5py) # Don't match the package name
+(?P<name>h5[a-z]{0,2}) # Names of the form h5, h5a, h5fd
+(?P<post>
+ \W? # Optional closing paren/quote/whatever
+ (?:$|\s+) # Must be followed by whitespace
+)
+""", re.VERBOSE)
-# --- Resolve inline references to modules ---
+def replace_module(istr):
-mod_pattern = re.compile(r"\s+(?!h5py)(?P<name>h5[a-z]{1,2})\W?(?:$|\s+)"
-
-module_pattern = r"\s+h5[a-z]{1,2}\W?(?:$|\s+)"
-module_only = r"h5[a-z]{1,2}"
-module_exclude = r"h5py"
+ def rpl(match):
+ pre, name, post = match.group('pre', 'name', 'post')
+ return '%s:mod:`%s <h5py.%s>`%s' % (pre, name, name, post)
-def replace_module(instring, match):
+ return safe_replace(istr, mod_expr, rpl)
- matchstring = instring[match.start():match.end()]
- if re.search(module_exclude, matchstring):
- return matchstring
+# === Replace parameter lists =================================================
- display = re.findall(module_only, matchstring)[0]
- target = display
+# e.g. " + STRING path ('/default')" -> ":param STRING path: ('/default')"
- rpl = ':mod:`%s <%s>`' % (display, 'h5py.'+target)
- #print rpl
- return re.sub(module_only, rpl, matchstring)
+param_expr = re.compile(r"""
+^
+\s*
+\+
+\s+
+(?P<desc>
+ [^\s\(]
+ .*
+ [^\s\)]
+)
+(?:
+ \s+
+ \(
+ (?P<default>
+ [^\s\(]
+ .*
+ [^\s\)]
+ )
+ \)
+)?
+$
+""", re.VERBOSE)
-# --- Resolve parameter lists
+def replace_param(istr):
+ """ Replace parameter lists. Not role-safe. """
-param_pattern = re.compile(r"^\s*\+\s+(?P<desc>[^\s\(].*[^\s\)])(?:\s+\((?P<default>[^\s\(].*[^\s\)])\))?$")
+ def rpl(match):
+ desc, default = match.group('desc', 'default')
+ default = ' (%s) ' % default if default is not None else ''
+ return ':param %s:%s' % (desc, default)
-def replace_param(instring, match):
+ return param_expr.sub(rpl, istr)
- desc, default = match.group('desc'), match.group('default')
- default = ' (%s) ' % default if default is not None else ''
- return ":param %s:%s" % (desc, default)
-# --- Sphinx extension code ---
+# === Begin Sphinx extension code =============================================
def setup(spx):
@@ -132,12 +206,21 @@ def setup(spx):
mod = obj.__module__
else:
mod = ".".join(name.split('.')[0:2]) # i.e. "h5py.h5z"
- lines[:] = [re.sub(const_pattern, partial(replace_constant, x, mod), x) for x in final_lines]
- lines[:] = [re.sub(module_pattern, partial(replace_module, x), x) for x in lines]
- lines[:] = [re.sub(param_pattern, partial(replace_param, x), x) for x in lines]
- lines[:] = [replaceall(x, replacements) for x in lines]
+ mod = mod.split('.')[1] # i.e. 'h5z'
+
+ del lines[:]
+ for line in final_lines:
+ line = replace_param(line)
+ line = replace_constant(line, mod)
+ line = replace_module(line)
+ line = replace_class(line)
+ line = line.replace('**kwds', '\*\*kwds').replace('*args','\*args')
+ lines.append(line)
+
#print "\n".join(lines)
+
+
def proc_sig(app, what, name, obj, options, signature, return_annotation):
""" Auto-generate function signatures from docstrings """
diff --git a/h5py/h5f.pyx b/h5py/h5f.pyx
index e653ebc..b00cd23 100644
--- a/h5py/h5f.pyx
+++ b/h5py/h5f.pyx
@@ -165,7 +165,7 @@ def get_obj_count(object where=OBJ_ALL, int types=H5F_OBJ_ALL):
special constant OBJ_ALL, to count objects in all files.
type
- Specify what kinds of object to include. May be one of OBJ_*,
+ Specify what kinds of object to include. May be one of OBJ*,
or any bitwise combination (e.g. OBJ_FILE | OBJ_ATTR).
The special value OBJ_ALL matches all object types, and
@@ -193,7 +193,7 @@ def get_obj_ids(object where=OBJ_ALL, int types=H5F_OBJ_ALL):
special constant OBJ_ALL, to list objects in all files.
type
- Specify what kinds of object to include. May be one of OBJ_*,
+ Specify what kinds of object to include. May be one of OBJ*,
or any bitwise combination (e.g. OBJ_FILE | OBJ_ATTR).
The special value OBJ_ALL matches all object types, and
diff --git a/h5py/h5p.pyx b/h5py/h5p.pyx
index 10ad730..baa40ca 100644
--- a/h5py/h5p.pyx
+++ b/h5py/h5p.pyx
@@ -245,7 +245,7 @@ cdef class PropCopyID(PropInstanceID):
"""(UINT flags)
Set flags for object copying process. Legal flags are
- from the h5o.COPY_* family:
+ from the h5o.COPY* family:
h5o.COPY_SHALLOW_HIERARCHY_FLAG
Copy only immediate members of a group.
@@ -268,7 +268,7 @@ cdef class PropCopyID(PropInstanceID):
def get_copy_object(self):
"""() => UINT flags
- Get copy process flags. Legal flags are h5o.COPY_*.
+ Get copy process flags. Legal flags are h5o.COPY*.
"""
cdef unsigned int flags
H5Pget_copy_object(self.id, &flags)
diff --git a/h5py/h5p_dcid.pxi b/h5py/h5p_dcid.pxi
index 1255ea8..f42a49f 100644
--- a/h5py/h5p_dcid.pxi
+++ b/h5py/h5p_dcid.pxi
@@ -198,7 +198,7 @@ cdef class PropDCID(PropCreateID):
- h5z.FILTER_SZIP
flags
- Bit flags (h5z.FLAG_*) setting filter properties
+ Bit flags (h5z.FLAG*) setting filter properties
values
TUPLE of UINTs giving auxiliary data for the filter
@@ -241,8 +241,8 @@ cdef class PropDCID(PropCreateID):
Get information about a filter, identified by its index. Tuple
elements are:
- 0. INT filter code (h5z.FILTER_*)
- 1. UINT flags (h5z.FLAG_*)
+ 0. INT filter code (h5z.FILTER*)
+ 1. UINT flags (h5z.FLAG*)
2. TUPLE of UINT values; filter aux data (16 values max)
3. STRING name of filter (256 chars max)
"""
@@ -288,10 +288,10 @@ cdef class PropDCID(PropCreateID):
"""(INT filter_code) => TUPLE filter_info or None
Get information about a filter, identified by its code (one
- of h5z.FILTER_*). If the filter doesn't exist, returns None.
+ of h5z.FILTER*). If the filter doesn't exist, returns None.
Tuple elements are:
- 0. UINT flags (h5z.FLAG_*)
+ 0. UINT flags (h5z.FLAG*)
1. TUPLE of UINT values; filter aux data (16 values max)
2. STRING name of filter (256 chars max)
"""
@@ -325,7 +325,7 @@ cdef class PropDCID(PropCreateID):
"""(INT filter_class)
Remove a filter from the pipeline. The class code is one of
- h5z.FILTER_*.
+ h5z.FILTER*.
"""
H5Premove_filter(self.id, <H5Z_filter_t>filter_class)
--
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