bee_python 0.0.1

data/tools/epydoc/test/__init__.py

@@ -0,0 +1,97 @@
+# epydoc -- Regression testing
+#
+# Copyright (C) 2005 Edward Loper
+# Author: Edward Loper <edloper@loper.org>
+# URL: <http://epydoc.sf.net>
+#
+# $Id: __init__.py,v 1.1 2009/11/26 13:20:53 casa Exp $
+
+"""
+Regression testing.
+"""
+__docformat__ = 'epytext en'
+
+import unittest, doctest, epydoc, os, os.path, re, sys
+
+def main():
+    try:
+        doctest.register_optionflag
+    except:
+        print ("\n"
+            "The regression test suite requires a more recent version of\n"
+            "doctest (e.g., the version that ships with Python 2.4 or 2.5).\n"
+            "Please place a new version of doctest on your path before \n"
+            "running the test suite.\n")
+        return
+                          
+    
+    PY24 = doctest.register_optionflag('PYTHON2.4')
+    """Flag indicating that a doctest example requires Python 2.4+"""
+    
+    PY25 = doctest.register_optionflag('PYTHON2.5')
+    """Flag indicating that a doctest example requires Python 2.5+"""
+    
+    class DocTestParser(doctest.DocTestParser):
+        """
+        Custom doctest parser that adds support for two new flags
+        +PYTHON2.4 and +PYTHON2.5.
+        """
+        def parse(self, string, name='<string>'):
+            pieces = doctest.DocTestParser.parse(self, string, name)
+            for i, val in enumerate(pieces):
+                if (isinstance(val, doctest.Example) and
+                    ((val.options.get(PY24, False) and
+                      sys.version[:2] < (2,4)) or
+                     (val.options.get(PY25, False) and
+                      sys.version[:2] < (2,5)))):
+                    pieces[i] = doctest.Example('1', '1')
+            return pieces
+
+    # Turn on debugging.
+    epydoc.DEBUG = True
+    
+    # Options for doctest:
+    options = doctest.ELLIPSIS
+    doctest.set_unittest_reportflags(doctest.REPORT_UDIFF)
+
+    # Use a custom parser
+    parser = DocTestParser()
+    
+    # Find all test cases.
+    tests = []
+    testdir = os.path.join(os.path.split(__file__)[0])
+    if testdir == '': testdir = '.'
+    for filename in os.listdir(testdir):
+        if (filename.endswith('.doctest') and
+            check_requirements(os.path.join(testdir, filename))):
+            tests.append(doctest.DocFileSuite(filename, optionflags=options,
+                                              parser=parser))
+            
+    # Run all test cases.
+    unittest.TextTestRunner(verbosity=2).run(unittest.TestSuite(tests))
+
+def check_requirements(filename):
+    """
+    Search for strings of the form::
+    
+        [Require: <module>]
+
+    If any are found, then try importing the module named <module>.
+    If the import fails, then return False.  If all required modules
+    are found, return True.  (This includes the case where no
+    requirements are listed.)
+    """
+    s = open(filename).read()
+    for m in re.finditer('(?mi)^[ ]*\:RequireModule:(.*)$', s):
+        module = m.group(1).strip()
+        try:
+            __import__(module)
+        except ImportError:
+            print ('Skipping %r (required module %r not found)' %
+                   (os.path.split(filename)[-1], module))
+            return False
+    return True
+            
+
+if __name__=='__main__':
+    main()

data/tools/epydoc/test/util.py

@@ -0,0 +1,226 @@
+#
+# epydoc -- Utility functions used by regression tests (*.doctest)
+# Edward Loper
+#
+# Created [01/30/01 05:18 PM]
+# $Id: util.py,v 1.1 2009/11/26 13:20:53 casa Exp $
+#
+
+"""
+Utility functions used by the regression tests (C{*.doctest}).
+"""
+__docformat__ = 'epytext en'
+
+import tempfile, re, os, os.path, textwrap, sys
+from epydoc.docbuilder import build_doc, build_doc_index
+from epydoc.docparser import parse_docs
+from epydoc.docintrospecter import introspect_docs
+from epydoc.apidoc import ClassDoc, RoutineDoc
+from epydoc.markup import ParsedDocstring
+from epydoc.docwriter.html import HTMLWriter
+
+######################################################################
+#{ Test Functions
+######################################################################
+
+def buildvaluedoc(s):
+    """
+    This test function takes a string containing the contents of a
+    module.  It writes the string contents to a file, imports the file
+    as a module, and uses build_doc to build documentation, and
+    returns it as a C{ValueDoc} object.
+    """
+    tmp_dir = write_pystring_to_tmp_dir(s)
+    val_doc = build_doc(os.path.join(tmp_dir, 'epydoc_test.py'))
+    cleanup_tmp_dir(tmp_dir)
+    return val_doc
+
+def runbuilder(s, attribs='', build=None, exclude=''):
+    """
+    This test function takes a string containing the contents of a
+    module.  It writes the string contents to a file, imports the file
+    as a module, and uses build_doc to build documentation, and pretty
+    prints the resulting ModuleDoc object.  The C{attribs} argument
+    specifies which attributes of the C{APIDoc}s should be displayed.
+    The C{build} argument gives the name of a variable in the module
+    whose documentation should be built, instead of bilding docs for
+    the whole module.
+    """
+    # Write it to a temp file.
+    tmp_dir = write_pystring_to_tmp_dir(s)
+    # Build it.
+    val_doc = build_doc(os.path.join(tmp_dir, 'epydoc_test.py'))
+    if build: val_doc = val_doc.variables[build].value
+    # Display it.
+    if isinstance(val_doc, ClassDoc):
+        for val in val_doc.variables.values():
+            if isinstance(val.value, RoutineDoc):
+                fun_to_plain(val.value)
+    s = val_doc.pp(include=attribs.split(),exclude=exclude.split())
+    s = re.sub(r"(filename = ).*", r"\1...", s)
+    s = re.sub(r"(<module 'epydoc_test' from ).*", r'\1...', s)
+    s = re.sub(r"(<function \w+ at )0x\w+>", r"\1...>", s)
+    s = re.sub(r"(<\w+ object at )0x\w+>", r"\1...>", s)
+    print s
+    # Clean up.
+    cleanup_tmp_dir(tmp_dir)
+
+def runparser(s, attribs='', show=None, exclude=''):
+    """
+    This test function takes a string containing the contents of a
+    module, and writes it to a file, uses `parse_docs` to parse it,
+    and pretty prints the resulting ModuleDoc object.  The `attribs`
+    argument specifies which attributes of the `APIDoc`s should be
+    displayed.  The `show` argument, if specifies, gives the name of
+    the object in the module that should be displayed (but the whole
+    module will always be inspected; this just selects what to
+    display).
+    """
+    # Write it to a temp file.
+    tmp_dir = write_pystring_to_tmp_dir(s)
+    # Parse it.
+    val_doc = parse_docs(os.path.join(tmp_dir, 'epydoc_test.py'))
+    if show is not None:
+        for name in show.split('.'):
+            if isinstance(val_doc, ClassDoc):
+                val_doc = val_doc.local_variables[name].value
+            else:
+                val_doc = val_doc.variables[name].value
+    # Display it.
+    s = val_doc.pp(include=attribs.split(), exclude=exclude.split())
+    s = re.sub(r"filename = .*", "filename = ...", s)
+    print s
+    # Clean up.
+    cleanup_tmp_dir(tmp_dir)
+
+def runintrospecter(s, attribs='', introspect=None, exclude=''):
+    """
+    This test function takes a string containing the contents of a
+    module.  It writes the string contents to a file, imports the file
+    as a module, and uses C{introspect_docs} to introspect it, and
+    pretty prints the resulting ModuleDoc object.  The C{attribs}
+    argument specifies which attributes of the C{APIDoc}s should be
+    displayed.  The C{introspect} argument gives the name of a variable
+    in the module whose value should be introspected, instead of
+    introspecting the whole module.
+    """
+    # Write it to a temp file.
+    tmp_dir = write_pystring_to_tmp_dir(s)
+    # Import it.
+    sys.path.insert(0, tmp_dir)
+    if introspect is None:
+        import epydoc_test as val
+    else:
+        exec("from epydoc_test import %s as val" % introspect)
+    del sys.path[0]
+    # Introspect it.
+    val_doc = introspect_docs(val)
+    # Display it.
+    s = val_doc.pp(include=attribs.split(),exclude=exclude.split())
+    s = re.sub(r"(filename = ).*", r"\1...", s)
+    s = re.sub(r"(<module 'epydoc_test' from ).*", r'\1...', s)
+    s = re.sub(r"(<function \w+ at )0x\w+>", r"\1...>", s)
+    s = re.sub(r"(<\w+ object at )0x\w+>", r"\1...>", s)
+    print s
+    # Clean up.
+    cleanup_tmp_dir(tmp_dir)
+
+def print_warnings():
+    """
+    Register a logger that will print warnings & errors.
+    """
+    from epydoc import log
+    del log._loggers[:]
+    log.register_logger(log.SimpleLogger(log.DOCSTRING_WARNING))
+
+def testencoding(s, introspect=True, parse=True, debug=False):
+    """
+    An end-to-end test for unicode encodings.  This function takes a
+    given string, writes it to a python file, and processes that
+    file's documentation.  It then generates HTML output from the
+    documentation, extracts all docstrings from the generated HTML
+    output, and displays them.  (In order to extract & display all
+    docstrings, it monkey-patches the HMTLwriter.docstring_to_html()
+    method.)"""
+    # Monkey-patch docstring_to_html
+    original_docstring_to_html = HTMLWriter.docstring_to_html
+    HTMLWriter.docstring_to_html = print_docstring_as_html
+    
+    # Write s to a temporary file.
+    tmp_dir = tempfile.mkdtemp()
+    path = os.path.join(tmp_dir, 'enc_test.py')
+    out = open(path, 'w')
+    out.write(textwrap.dedent(s))
+    out.close()
+    # Build docs for it
+    docindex = build_doc_index([path], introspect, parse)
+    if docindex is None: return
+    sys.modules.pop('enc_test', None)
+    # Write html output.
+    writer = HTMLWriter(docindex, mark_docstrings=True)
+    writer.write(tmp_dir)
+    for file in os.listdir(tmp_dir):
+        os.unlink(os.path.join(tmp_dir,file))
+    os.rmdir(tmp_dir)
+
+    # Restore the HTMLWriter class to its original state.
+    HTMLWriter.docstring_to_html = original_docstring_to_html
+
+######################################################################
+#{ Helper Functions
+######################################################################
+
+def write_pystring_to_tmp_dir(s):
+    tmp_dir = tempfile.mkdtemp()
+    out = open(os.path.join(tmp_dir, 'epydoc_test.py'), 'w')
+    out.write(textwrap.dedent(s))
+    out.close()
+    return tmp_dir
+
+def cleanup_tmp_dir(tmp_dir):
+    os.unlink(os.path.join(tmp_dir, 'epydoc_test.py'))
+    try: os.unlink(os.path.join(tmp_dir, 'epydoc_test.pyc'))
+    except OSError: pass
+    os.rmdir(tmp_dir)
+    sys.modules.pop('epydoc_test', None)
+
+def to_plain(docstring):
+    """Conver a parsed docstring into plain text"""
+    if isinstance(docstring, ParsedDocstring):
+        docstring = docstring.to_plaintext(None)
+    return docstring.rstrip()
+
+def fun_to_plain(val_doc):
+    """Convert parsed docstrings in text from a RoutineDoc"""
+    for k, v in val_doc.arg_types.items():
+        val_doc.arg_types[k] = to_plain(v)
+    for i, (k, v) in enumerate(val_doc.arg_descrs):
+        val_doc.arg_descrs[i] = (k, to_plain(v))
+
+def print_docstring_as_html(self, parsed_docstring, *varargs, **kwargs):
+    """
+    Convert the given parsed_docstring to HTML and print it.  Ignore
+    any other arguments.  This function is used by L{testencoding} to
+    monkey-patch the HTMLWriter class's docstring_to_html() method.
+    """
+    s = parsed_docstring.to_html(None).strip()
+    s = s.encode('ascii', 'xmlcharrefreplace')
+    s = remove_surrogates(s)
+    print s
+    return ''
+
+def remove_surrogates(s):
+    """
+    The following is a helper function, used to convert two-character
+    surrogate sequences into single characters.  This is needed
+    because some systems create surrogates but others don't.
+    """
+    pieces = re.split('(&#\d+;)', s)
+    for i in range(3, len(pieces)-1, 2):
+        if pieces[i-1] != '': continue
+        high,low = int(pieces[i-2][2:-1]), int(pieces[i][2:-1])
+        if 0xd800 <= high <= 0xdbff and 0xdc00 <= low <= 0xdfff:
+            pieces[i-2] = '&#%d;' % (((high&0x3ff)<<10) +
+                                     (low&0x3ff) + 0x10000)
+            pieces[i] = ''
+    return ''.join(pieces)

data/tools/epydoc/util.py

@@ -0,0 +1,289 @@
+# epydoc -- Utility functions
+#
+# Copyright (C) 2005 Edward Loper
+# Author: Edward Loper <edloper@loper.org>
+# URL: <http://epydoc.sf.net>
+#
+# $Id: util.py,v 1.1 2009/11/26 13:20:42 casa Exp $
+
+"""
+Miscellaneous utility functions that are used by multiple modules.
+
+@group Python source types: is_module_file, is_package_dir, is_pyname,
+    py_src_filename
+@group Text processing: wordwrap, decode_with_backslashreplace,
+    plaintext_to_html
+"""
+__docformat__ = 'epytext en'
+
+import os, os.path, re
+
+######################################################################
+## Python Source Types
+######################################################################
+
+PY_SRC_EXTENSIONS = ['.py', '.pyw']
+PY_BIN_EXTENSIONS = ['.pyc', '.so', '.pyd']
+
+def is_module_file(path):
+    # Make sure it's a file name.
+    if not isinstance(path, basestring):
+        return False
+    (dir, filename) = os.path.split(path)
+    (basename, extension) = os.path.splitext(filename)
+    return (os.path.isfile(path) and
+            re.match('[a-zA-Z_]\w*$', basename) and
+            extension in PY_SRC_EXTENSIONS+PY_BIN_EXTENSIONS)
+
+def is_src_filename(filename):
+    if not isinstance(filename, basestring): return False
+    if not os.path.exists(filename): return False
+    return os.path.splitext(filename)[1] in PY_SRC_EXTENSIONS
+    
+def is_package_dir(dirname):
+    """
+    Return true if the given directory is a valid package directory
+    (i.e., it names a directory that contains a valid __init__ file,
+    and its name is a valid identifier).
+    """
+    # Make sure it's a directory name.
+    if not isinstance(dirname, basestring):
+        return False
+    if not os.path.isdir(dirname):
+        return False
+    dirname = os.path.abspath(dirname)
+    # Make sure it's a valid identifier.  (Special case for
+    # "foo/", where os.path.split -> ("foo", "").)
+    (parent, dir) = os.path.split(dirname)
+    if dir == '': (parent, dir) = os.path.split(parent)
+    
+    # The following constraint was removed because of sourceforge
+    # bug #1787028 -- in some cases (eg eggs), it's too strict.
+    #if not re.match('\w+$', dir):
+    #    return False
+    
+    for name in os.listdir(dirname):
+        filename = os.path.join(dirname, name)
+        if name.startswith('__init__.') and is_module_file(filename):
+            return True
+    else:
+        return False
+
+def is_pyname(name):
+    return re.match(r"\w+(\.\w+)*$", name)
+
+def py_src_filename(filename):
+    basefile, extension = os.path.splitext(filename)
+    if extension in PY_SRC_EXTENSIONS:
+        return filename
+    else:
+        for ext in PY_SRC_EXTENSIONS:
+            if os.path.isfile('%s%s' % (basefile, ext)):
+                return '%s%s' % (basefile, ext)
+        else:
+            raise ValueError('Could not find a corresponding '
+                             'Python source file for %r.' % filename)
+
+def munge_script_name(filename):
+    name = os.path.split(filename)[1]
+    name = re.sub(r'\W', '_', name)
+    return 'script-'+name
+
+######################################################################
+## Text Processing
+######################################################################
+
+def decode_with_backslashreplace(s):
+    r"""
+    Convert the given 8-bit string into unicode, treating any
+    character c such that ord(c)<128 as an ascii character, and
+    converting any c such that ord(c)>128 into a backslashed escape
+    sequence.
+
+        >>> decode_with_backslashreplace('abc\xff\xe8')
+        u'abc\\xff\\xe8'
+    """
+    # s.encode('string-escape') is not appropriate here, since it
+    # also adds backslashes to some ascii chars (eg \ and ').
+    assert isinstance(s, str)
+    return (s
+            .decode('latin1')
+            .encode('ascii', 'backslashreplace')
+            .decode('ascii'))
+
+def wordwrap(str, indent=0, right=75, startindex=0, splitchars=''):
+    """
+    Word-wrap the given string.  I.e., add newlines to the string such
+    that any lines that are longer than C{right} are broken into
+    shorter lines (at the first whitespace sequence that occurs before
+    index C{right}).  If the given string contains newlines, they will
+    I{not} be removed.  Any lines that begin with whitespace will not
+    be wordwrapped.
+
+    @param indent: If specified, then indent each line by this number
+        of spaces.
+    @type indent: C{int}
+    @param right: The right margin for word wrapping.  Lines that are
+        longer than C{right} will be broken at the first whitespace
+        sequence before the right margin.
+    @type right: C{int}
+    @param startindex: If specified, then assume that the first line
+        is already preceeded by C{startindex} characters.
+    @type startindex: C{int}
+    @param splitchars: A list of non-whitespace characters which can
+        be used to split a line.  (E.g., use '/\\' to allow path names
+        to be split over multiple lines.)
+    @rtype: C{str}
+    """
+    if splitchars:
+        chunks = re.split(r'( +|\n|[^ \n%s]*[%s])' %
+                          (re.escape(splitchars), re.escape(splitchars)),
+                          str.expandtabs())
+    else:
+        chunks = re.split(r'( +|\n)', str.expandtabs())
+    result = [' '*(indent-startindex)]
+    charindex = max(indent, startindex)
+    for chunknum, chunk in enumerate(chunks):
+        if (charindex+len(chunk) > right and charindex > 0) or chunk == '\n':
+            result.append('\n' + ' '*indent)
+            charindex = indent
+            if chunk[:1] not in ('\n', ' '):
+                result.append(chunk)
+                charindex += len(chunk)
+        else:
+            result.append(chunk)
+            charindex += len(chunk)
+    return ''.join(result).rstrip()+'\n'
+
+def plaintext_to_html(s):
+    """
+    @return: An HTML string that encodes the given plaintext string.
+    In particular, special characters (such as C{'<'} and C{'&'})
+    are escaped.
+    @rtype: C{string}
+    """
+    s = s.replace('&', '&amp;').replace('"', '&quot;')
+    s = s.replace('<', '&lt;').replace('>', '&gt;')
+    return s
+        
+def plaintext_to_latex(str, nbsp=0, breakany=0):
+    """
+    @return: A LaTeX string that encodes the given plaintext string.
+    In particular, special characters (such as C{'$'} and C{'_'})
+    are escaped, and tabs are expanded.
+    @rtype: C{string}
+    @param breakany: Insert hyphenation marks, so that LaTeX can
+    break the resulting string at any point.  This is useful for
+    small boxes (e.g., the type box in the variable list table).
+    @param nbsp: Replace every space with a non-breaking space
+    (C{'~'}).
+    """
+    # These get converted to hyphenation points later
+    if breakany: str = re.sub('(.)', '\\1\1', str)
+
+    # These get converted to \textbackslash later.
+    str = str.replace('\\', '\0')
+
+    # Expand tabs
+    str = str.expandtabs()
+
+    # These elements need to be backslashed.
+    str = re.sub(r'([#$&%_\${}])', r'\\\1', str)
+
+    # These elements have special names.
+    str = str.replace('|', '{\\textbar}')
+    str = str.replace('<', '{\\textless}')
+    str = str.replace('>', '{\\textgreater}')
+    str = str.replace('^', '{\\textasciicircum}')
+    str = str.replace('~', '{\\textasciitilde}')
+    str = str.replace('\0', r'{\textbackslash}')
+
+    # replace spaces with non-breaking spaces
+    if nbsp: str = str.replace(' ', '~')
+
+    # Convert \1's to hyphenation points.
+    if breakany: str = str.replace('\1', r'\-')
+    
+    return str
+
+class RunSubprocessError(OSError):
+    def __init__(self, cmd, out, err):
+        OSError.__init__(self, '%s failed' % cmd[0])
+        self.out = out
+        self.err = err
+
+def run_subprocess(cmd, data=None):
+    """
+    Execute the command C{cmd} in a subprocess.
+    
+    @param cmd: The command to execute, specified as a list
+        of string.
+    @param data: A string containing data to send to the
+        subprocess.
+    @return: A tuple C{(out, err)}.
+    @raise OSError: If there is any problem executing the
+        command, or if its exitval is not 0.
+    """
+    if isinstance(cmd, basestring):
+        cmd = cmd.split()
+
+    # Under Python 2.4+, use subprocess
+    try:
+        from subprocess import Popen, PIPE
+        pipe = Popen(cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)
+        out, err = pipe.communicate(data)
+        if hasattr(pipe, 'returncode'):
+            if pipe.returncode == 0:
+                return out, err
+            else:
+                raise RunSubprocessError(cmd, out, err)
+        else:
+            # Assume that there was an error iff anything was written
+            # to the child's stderr.
+            if err == '':
+                return out, err
+            else:
+                raise RunSubprocessError(cmd, out, err)
+    except ImportError:
+        pass
+
+    # Under Python 2.3 or earlier, on unix, use popen2.Popen3 so we
+    # can access the return value.
+    import popen2
+    if hasattr(popen2, 'Popen3'):
+        pipe = popen2.Popen3(' '.join(cmd), True)
+        to_child = pipe.tochild
+        from_child = pipe.fromchild
+        child_err = pipe.childerr
+        if data:
+            to_child.write(data)
+        to_child.close()
+        out = err = ''
+        while pipe.poll() is None:
+            out += from_child.read()
+            err += child_err.read()
+        out += from_child.read()
+        err += child_err.read()
+        if pipe.wait() == 0:
+            return out, err
+        else:
+            raise RunSubprocessError(cmd, out, err)
+
+    # Under Python 2.3 or earlier, on non-unix, use os.popen3
+    else:
+        to_child, from_child, child_err = os.popen3(' '.join(cmd), 'b')
+        if data:
+            try:
+                to_child.write(data)
+            # Guard for a broken pipe error
+            except IOError, e:
+                raise OSError(e)
+        to_child.close()
+        out = from_child.read()
+        err = child_err.read()
+        # Assume that there was an error iff anything was written
+        # to the child's stderr.
+        if err == '':
+            return out, err
+        else:
+            raise RunSubprocessError(cmd, out, err)

data/tools/logilab/logilab/__init__.py

@@ -0,0 +1,5 @@
+"""generated file, don't modify or your data will be lost"""
+try:
+    __import__('pkg_resources').declare_namespace(__name__)
+except ImportError:
+    pass