root/branches/mk/cheesecake/codeparser.py

import os
import re

from model import System, Module, Class, Function, parseFile, processModuleAst

def use_reST(text):
    """Return True if text includes reST and False otherwise.

    See http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
    for reference.

    >>> use_reST("String with *emphasis*.")
    True
    >>> use_reST("*Multi-word emphasis.*")
    True
    >>> use_reST("How about testing **strong string**?")
    True
    >>> use_reST("Some *noisy!* punctuation")
    True
    >>> use_reST("**characters?**, in the way.")
    True
    >>> use_reST("Don\'t forget ``inline literals``.")
    True
    >>> use_reST("This is reST (hyperlink_).")
    True
    >>> use_reST("This is (`quite long hyperlink`_).")
    True
    >>> use_reST("* Bullet\\n* List\\n")
    True
    >>> use_reST(":Field: list\\n:indeed: it is\\n")
    True

    >>> use_reST("Plain string.")
    False
    >>> use_reST("Do some math: 2 * 2a* 2 = 8a")
    False
    >>> use_reST("Not*really*strong.")
    False
    >>> use_reST("Interpreted `text` is widely used as quotes, so exclude it.")
    False
    >>> use_reST("Not a :field:.")
    False
    """
    def compile(pattern, user_map=None):
        """Compile a regex pattern using default or user mapping.
        """

        # Word in reST can also contain hyphens and punctuation characters.
        mapping = {'ALPHA': r'[-.,?!\w]', 'WORD': r'[-.,?!\s\w]',
                           'START': r'(^|\s)', 'END': r'([.,?!\s]|$)'}

        if user_map:
            mapping = mapping.copy()
            mapping.update(user_map)

        def sub(text, mapping):
            for From, To in mapping.iteritems():
                text = text.replace(From, To)
            return text

        return re.compile(sub(pattern, mapping), re.LOCALE | re.VERBOSE)

    def inline_markup(start, end=None, mapping=None):
        if not end:
            end = start
        return compile(r'''(START  %(start)s  ALPHA  %(end)s  END) |
                           (START  %(start)s  ALPHA  WORD*  ALPHA  %(end)s  END)'''\
                       % {'start': start, 'end': end}, mapping)

    def line_markup(start, end=None):
        return inline_markup(start, end, mapping={'ALPHA': r'[-.,?!\s\w]',
                                                  'START': r'(\n|^)[\ \t]*',
                                                  'END': r''})

    emphasis_pattern = inline_markup(r'\*')
    strong_pattern = inline_markup(r'\*\*')
    inline_pattern = inline_markup(r'``')
    hyperlink_pattern = inline_markup(r'\(', r'_\)',
                                      {'ALPHA': r'\w', 'WORD': r'[-.\w]'})
    long_hyperlink_pattern = inline_markup(r'\(`', r'`_\)')
    field_pattern = line_markup(r':')
    bullet_pattern = line_markup(r'\*', r'')

    rest_patterns = [strong_pattern,
                     emphasis_pattern,
                     inline_pattern,
                     hyperlink_pattern,
                     long_hyperlink_pattern,
                     field_pattern,
                     bullet_pattern]

    for pattern in rest_patterns:
        if re.search(pattern, text):
            return True

    return False


class CodeParser(object):
    """Information about the structure of a Python module.

    * Collects modules, classes, methods, functions and associated docstrings
    * Based on mwh's docextractor.model module
    """
    def __init__(self, pyfile, log=None):
        if log:
            self.log = log.codeparser
        else:
            import logger
            self.log = logger.default.codeparser
        self.modules = []
        self.classes = []
        self.methods = []
        self.method_func = []
        self.functions = []
        self.docstrings = [] # objects that have docstrings
        self.rest_docstrings = [] # objects that have docstrings with reST

        (path, filename) = os.path.split(pyfile)
        (module, ext) = os.path.splitext(filename)
        self.log("Inspecting file: " + pyfile)

        self.system = System()
        try:
            processModuleAst(parseFile(pyfile), module, self.system)
        except:
            return

        for obj in self.system.orderedallobjects:
            fullname = obj.fullName()
            if isinstance(obj, Module):
                self.modules.append(fullname)
            if isinstance(obj, Class):
                self.classes.append(fullname)
            if isinstance(obj, Function):
                self.method_func.append(fullname)
            if isinstance(obj.docstring, str) and obj.docstring.strip():
                self.docstrings.append(fullname)
                if use_reST(obj.docstring):
                    self.rest_docstrings.append(fullname)

        for method_or_func in self.method_func:
            method_found = 0
            for cls in self.classes:
                if method_or_func.startswith(cls):
                    self.methods.append(method_or_func)
                    method_found = 1
                    break
            if not method_found:
                self.functions.append(method_or_func)
                
        self.log("modules: " + ",".join(self.modules))
        self.log("classes: " + ",".join(self.classes))
        self.log("methods: " + ",".join(self.methods))
        self.log("functions: " + ",".join(self.functions))

    def object_count(self):
        """Return number of objects found in this module.

        Objects include:
        * module
        * classes
        * methods
        * functions
        """
        module_count = len(self.modules)
        cls_count = len(self.classes)
        method_count = len(self.methods)
        func_count = len(self.functions)
        return module_count + cls_count + method_count + func_count

    def docstring_count(self):
        """Return number of docstrings found in this module
        """
        return len(self.docstrings)

    def rest_docstring_count(self):
        """Return number of reST docstrings found in this module
        """
        return len(self.rest_docstrings)

    def functions_called(self):
        """
        Return list of functions called by functions/methods
        defined in this module
        """
        return self.system.func_called.keys()