gimp.PDB wrapper

import re
import textwrap
from gimpfu import _obj_mapping, gimp

BASE_DOC_TEMPLATE = "%s\n\n%s"
PARAM_DOC_TEMPLATE = "\n\nParameters\n----------\n%s"
RUNMODE_DOC = """run_mode : int, optional
    the run mode, RUN_INTERACTIVE or RUN_NONINTERACTIVE\n"""
RETURN_DOC_TEMPLATE = "\nReturns\n-------\n%s"

# Used to make sure that each line isn't too wide, break_on_hyphens is disabled
# because it can split constants within the parameters description
textwrapper = textwrap.TextWrapper(64, break_on_hyphens=False)

# Regular expression used to check if a parameter is really a boolean rather
# than an integer. This takes into account different types of seperators,
# brackets/parens, ordering, as well as specifying the integer value.
bool_re = re.compile(" [\({]? ?"
                     "((?P<ft>TRUE( \(1\))?)|(FALSE( \(0\))?))"
                     "((, )|( or )|/)"
                     "(?(ft)FALSE( \(0\))?|TRUE( \(1\))?)"
                     " ?[\)}]?")

PROC_PROPERTIES = ("nparams", "return_vals", "params", "proc_author",
                   "proc_blurb", "proc_copyright", "proc_date", "proc_help",
                   "proc_name", "proc_type", "return_vals")


class PDBWrapper(object):
    def query(self, *args, **kwargs):
        gimp.pdb.query(*args, **kwargs)

    def __getattr__(self, name):
        proc_name = name.replace("-", "_")
        procedure = getattr(gimp.pdb, proc_name)

        def proc_func(*args, **kwargs):
            procedure(*args, **kwargs)

        proc_func.__name__ = proc_name
        proc_func.__doc__ = self._proc_help(procedure)
        proc_func.__module__ = None
        for prop in PROC_PROPERTIES:
            setattr(proc_func, prop, getattr(procedure, prop))
        return proc_func

    @staticmethod
    def _proc_help(proc):
        """ Returns a docstring for a gimp procedure. """
        proc_help = textwrapper.fill(proc.proc_help)
        proc_blurb = textwrapper.fill(proc.proc_blurb)
        base_doc = BASE_DOC_TEMPLATE % (proc_blurb, proc_help)
        param_doc = PDBWrapper._format_params(proc.params, PARAM_DOC_TEMPLATE)
        return_doc = PDBWrapper._format_params(proc.return_vals,
                                               RETURN_DOC_TEMPLATE)

        return (base_doc + param_doc + return_doc).rstrip()

    @staticmethod
    def _format_params(params, template):
        if len(params) == 0:
            return ""

        param_docs = []
        # pygimp will accept the run_mode as a keyword argument, so there must
        # be a check to see if a procedure has one.
        if params[0][1] == "run-mode":
            has_run_mode = True
            params = params[1:]
        else:
            has_run_mode = False

        # Setup indentation for the parameter descriptions
        textwrapper.initial_indent = "    "
        textwrapper.subsequent_indent = "    "

        for param_type, param_name, param_desc in params:
            if param_desc is None:
                param_desc = ""
            param_items = [param_name.replace("-", "_"), "\n"]
            # The type information and description will only be added to the
            # documentation if they are both valid and useful.
            if param_type in _obj_mapping:
                type_name = " : " + _obj_mapping[param_type].__name__
                match = bool_re.search(param_desc)
                if type_name == " : int" and match is not None:
                    type_name = ": bool"
                    # Remove the boolean notation from the description
                    param_desc = bool_re.sub("", param_desc)
                param_items.insert(1, type_name)
            if param_desc != "":
                param_desc = textwrapper.fill(param_desc) + "\n"
                param_items.append(param_desc)
            param_docs.append("".join(param_items))

        doc = template % ("".join(param_docs))

        # Restore the indentation just to be safe, even if it isn't used again.
        textwrapper.initial_indent = ""
        textwrapper.subsequent_indent = ""

        if has_run_mode:
            doc += RUNMODE_DOC
        return doc