Source code for script.task

"""
Get interface description of GRASS commands

Based on gui/wxpython/gui_modules/menuform.py

Usage:

::

    from grass.script import task as gtask
    gtask.command_info('r.info')

(C) 2011 by the GRASS Development Team
This program is free software under the GNU General Public
License (>=v2). Read the file COPYING that comes with GRASS
for details.

.. sectionauthor:: Martin Landa <landa.martin gmail.com>
"""
import re
import sys
import string

if sys.version_info.major == 3:
    unicode = str

try:
    import xml.etree.ElementTree as etree
except ImportError:
    import elementtree.ElementTree as etree # Python <= 2.4
from xml.parsers import expat  # TODO: works for any Python?
# Get the XML parsing exceptions to catch. The behavior chnaged with Python 2.7
# and ElementTree 1.3.
if hasattr(etree, 'ParseError'):
    ETREE_EXCEPTIONS = (etree.ParseError, expat.ExpatError)
else:
    ETREE_EXCEPTIONS = (expat.ExpatError)

from .utils import encode, decode, split
from .core import *


[docs]class grassTask: """This class holds the structures needed for filling by the parser Parameter blackList is a dictionary with fixed structure, eg. :: blackList = {'items' : {'d.legend' : { 'flags' : ['m'], 'params' : [] }}, 'enabled': True} :param str path: full path :param blackList: hide some options in the GUI (dictionary) """ def __init__(self, path=None, blackList=None): self.path = path self.name = _('unknown') self.params = list() self.description = '' self.label = '' self.flags = list() self.keywords = list() self.errorMsg = '' self.firstParam = None if blackList: self.blackList = blackList else: self.blackList = {'enabled': False, 'items': {}} if path is not None: try: processTask(tree=etree.fromstring(get_interface_description(path)), task=self) except ScriptError as e: self.errorMsg = e.value self.define_first()
[docs] def define_first(self): """Define first parameter :return: name of first parameter """ if len(self.params) > 0: self.firstParam = self.params[0]['name'] return self.firstParam
[docs] def get_error_msg(self): """Get error message ('' for no error) """ return self.errorMsg
[docs] def get_name(self): """Get task name """ if sys.platform == 'win32': name, ext = os.path.splitext(self.name) if ext in ('.py', '.sh'): return name else: return self.name return self.name
[docs] def get_description(self, full=True): """Get module's description :param bool full: True for label + desc """ if self.label: if full: return self.label + ' ' + self.description else: return self.label else: return self.description
[docs] def get_keywords(self): """Get module's keywords """ return self.keywords
[docs] def get_list_params(self, element='name'): """Get list of parameters :param str element: element name """ params = [] for p in self.params: params.append(p[element]) return params
[docs] def get_list_flags(self, element='name'): """Get list of flags :param str element: element name """ flags = [] for p in self.flags: flags.append(p[element]) return flags
[docs] def get_param(self, value, element='name', raiseError=True): """Find and return a param by name :param value: param's value :param str element: element name :param bool raiseError: True for raise on error """ for p in self.params: val = p.get(element, None) if val is None: continue if isinstance(val, (list, tuple)): if value in val: return p elif isinstance(val, (bytes, unicode)): if p[element][:len(value)] == value: return p else: if p[element] == value: return p if raiseError: raise ValueError(_("Parameter element '%(element)s' not found: '%(value)s'") % \ { 'element' : element, 'value' : value }) else: return None
[docs] def get_flag(self, aFlag): """Find and return a flag by name Raises ValueError when the flag is not found. :param str aFlag: name of the flag """ for f in self.flags: if f['name'] == aFlag: return f raise ValueError(_("Flag not found: %s") % aFlag)
[docs] def get_cmd_error(self): """Get error string produced by get_cmd(ignoreErrors = False) :return: list of errors """ errorList = list() # determine if suppress_required flag is given for f in self.flags: if f['value'] and f['suppress_required']: return errorList for p in self.params: if not p.get('value', '') and p.get('required', False): if not p.get('default', ''): desc = p.get('label', '') if not desc: desc = p['description'] errorList.append(_("Parameter '%(name)s' (%(desc)s) is missing.") % \ {'name': p['name'], 'desc': desc}) return errorList
[docs] def get_cmd(self, ignoreErrors=False, ignoreRequired=False, ignoreDefault=True): """Produce an array of command name and arguments for feeding into some execve-like command processor. :param bool ignoreErrors: True to return whatever has been built so far, even though it would not be a correct command for GRASS :param bool ignoreRequired: True to ignore required flags, otherwise '@<required@>' is shown :param bool ignoreDefault: True to ignore parameters with default values """ cmd = [self.get_name()] suppress_required = False for flag in self.flags: if flag['value']: if len(flag['name']) > 1: # e.g. overwrite cmd += ['--' + flag['name']] else: cmd += ['-' + flag['name']] if flag['suppress_required']: suppress_required = True for p in self.params: if p.get('value', '') == '' and p.get('required', False): if p.get('default', '') != '': cmd += ['%s=%s' % (p['name'], p['default'])] elif ignoreErrors and not suppress_required and not ignoreRequired: cmd += ['%s=%s' % (p['name'], _('<required>'))] elif p.get('value', '') == '' and p.get('default', '') != '' and not ignoreDefault: cmd += ['%s=%s' % (p['name'], p['default'])] elif p.get('value', '') != '' and \ (p['value'] != p.get('default', '') or not ignoreDefault): # output only values that have been set, and different from defaults cmd += ['%s=%s' % (p['name'], p['value'])] errList = self.get_cmd_error() if ignoreErrors is False and errList: raise ValueError('\n'.join(errList)) return cmd
[docs] def get_options(self): """Get options """ return {'flags': self.flags, 'params': self.params}
[docs] def has_required(self): """Check if command has at least one required parameter """ for p in self.params: if p.get('required', False): return True return False
[docs] def set_param(self, aParam, aValue, element='value'): """Set param value/values. """ try: param = self.get_param(aParam) except ValueError: return param[element] = aValue
[docs] def set_flag(self, aFlag, aValue, element='value'): """Enable / disable flag. """ try: param = self.get_flag(aFlag) except ValueError: return param[element] = aValue
[docs] def set_options(self, opts): """Set flags and parameters :param opts list of flags and parameters""" for opt in opts: if opt[0] == '-': # flag self.set_flag(opt.lstrip('-'), True) else: # parameter key, value = opt.split('=', 1) self.set_param(key, value)
[docs]class processTask: """A ElementTree handler for the --interface-description output, as defined in grass-interface.dtd. Extend or modify this and the DTD if the XML output of GRASS' parser is extended or modified. :param tree: root tree node :param task: grassTask instance or None :param blackList: list of flags/params to hide :return: grassTask instance """ def __init__(self, tree, task=None, blackList=None): if task: self.task = task else: self.task = grassTask() if blackList: self.task.blackList = blackList self.root = tree self._process_module() self._process_params() self._process_flags() self.task.define_first() def _process_module(self): """Process module description """ self.task.name = self.root.get('name', default='unknown') # keywords for keyword in self._get_node_text(self.root, 'keywords').split(','): self.task.keywords.append(keyword.strip()) self.task.label = self._get_node_text(self.root, 'label') self.task.description = self._get_node_text(self.root, 'description') def _process_params(self): """Process parameters """ for p in self.root.findall('parameter'): # gisprompt node_gisprompt = p.find('gisprompt') gisprompt = False age = element = prompt = None if node_gisprompt is not None: gisprompt = True age = node_gisprompt.get('age', '') element = node_gisprompt.get('element', '') prompt = node_gisprompt.get('prompt', '') # value(s) values = [] values_desc = [] node_values = p.find('values') if node_values is not None: for pv in node_values.findall('value'): values.append(self._get_node_text(pv, 'name')) desc = self._get_node_text(pv, 'description') if desc: values_desc.append(desc) # keydesc key_desc = [] node_key_desc = p.find('keydesc') if node_key_desc is not None: for ki in node_key_desc.findall('item'): key_desc.append(ki.text) if p.get('multiple', 'no') == 'yes': multiple = True else: multiple = False if p.get('required', 'no') == 'yes': required = True else: required = False if self.task.blackList['enabled'] and \ self.task.name in self.task.blackList['items'] and \ p.get('name') in self.task.blackList['items'][self.task.name].get('params', []): hidden = True else: hidden = False self.task.params.append( { "name" : p.get('name'), "type" : p.get('type'), "required" : required, "multiple" : multiple, "label" : self._get_node_text(p, 'label'), "description" : self._get_node_text(p, 'description'), 'gisprompt' : gisprompt, 'age' : age, 'element' : element, 'prompt' : prompt, "guisection" : self._get_node_text(p, 'guisection'), "guidependency" : self._get_node_text(p, 'guidependency'), "default" : self._get_node_text(p, 'default'), "values" : values, "values_desc" : values_desc, "value" : '', "key_desc" : key_desc, "hidden" : hidden }) def _process_flags(self): """Process flags """ for p in self.root.findall('flag'): if self.task.blackList['enabled'] and \ self.task.name in self.task.blackList['items'] and \ p.get('name') in self.task.blackList['items'][self.task.name].get('flags', []): hidden = True else: hidden = False if p.find('suppress_required') is not None: suppress_required = True else: suppress_required = False self.task.flags.append( { "name" : p.get('name'), "label" : self._get_node_text(p, 'label'), "description" : self._get_node_text(p, 'description'), "guisection" : self._get_node_text(p, 'guisection'), "suppress_required" : suppress_required, "value" : False, "hidden" : hidden } ) def _get_node_text(self, node, tag, default=''): """Get node text""" p = node.find(tag) if p is not None: res = ' '.join(p.text.split()) return res return default
[docs] def get_task(self): """Get grassTask instance""" return self.task
[docs]def convert_xml_to_utf8(xml_text): # enc = locale.getdefaultlocale()[1] # modify: fetch encoding from the interface description text(xml) # e.g. <?xml version="1.0" encoding="GBK"?> pattern = re.compile(b'<\?xml[^>]*\Wencoding="([^"]*)"[^>]*\?>') m = re.match(pattern, xml_text) if m is None: return xml_text.encode("utf-8") if xml_text else None # enc = m.groups()[0] # modify: change the encoding to "utf-8", for correct parsing xml_text_utf8 = xml_text.decode(enc.decode('ascii')).encode("utf-8") p = re.compile(b'encoding="' + enc + b'"', re.IGNORECASE) xml_text_utf8 = p.sub(b'encoding="utf-8"', xml_text_utf8) return xml_text_utf8
[docs]def get_interface_description(cmd): """Returns the XML description for the GRASS cmd (force text encoding to "utf-8"). The DTD must be located in $GISBASE/gui/xml/grass-interface.dtd, otherwise the parser will not succeed. :param cmd: command (name of GRASS module) """ try: p = Popen([cmd, '--interface-description'], stdout=PIPE, stderr=PIPE) cmdout, cmderr = p.communicate() # TODO: do it better (?) if not cmdout and sys.platform == 'win32': # we in fact expect pure module name (without extension) # so, lets remove extension if cmd.endswith('.py'): cmd = os.path.splitext(cmd)[0] if cmd == 'd.rast3d': sys.path.insert(0, os.path.join(os.getenv('GISBASE'), 'gui', 'scripts')) p = Popen([sys.executable, get_real_command(cmd), '--interface-description'], stdout=PIPE, stderr=PIPE) cmdout, cmderr = p.communicate() if cmd == 'd.rast3d': del sys.path[0] # remove gui/scripts from the path if p.returncode != 0: raise ScriptError(_("Unable to fetch interface description for command '<{cmd}>'." "\n\nDetails: <{det}>").format(cmd=cmd, det=decode(cmderr))) except OSError as e: raise ScriptError(_("Unable to fetch interface description for command '<{cmd}>'." "\n\nDetails: <{det}>").format(cmd=cmd, det=e)) desc = convert_xml_to_utf8(cmdout) desc = desc.replace(b'grass-interface.dtd', os.path.join(os.getenv('GISBASE'), 'gui', 'xml', 'grass-interface.dtd').encode('utf-8')) return desc
[docs]def parse_interface(name, parser=processTask, blackList=None): """Parse interface of given GRASS module The *name* is either GRASS module name (of a module on path) or a full or relative path to an executable. :param str name: name of GRASS module to be parsed :param parser: :param blackList: """ try: tree = etree.fromstring(get_interface_description(name)) except ETREE_EXCEPTIONS as error: raise ScriptError(_("Cannot parse interface description of" "<{name}> module: {error}").format(name=name, error=error)) task = parser(tree, blackList=blackList).get_task() # if name from interface is different than the originally # provided name, then the provided name is likely a full path needed # to actually run the module later # (processTask uses only the XML which does not contain the original # path used to execute the module) if task.name != name: task.path = name return task
[docs]def command_info(cmd): """Returns meta information for any GRASS command as dictionary with entries for description, keywords, usage, flags, and parameters, e.g. >>> command_info('g.tempfile') # doctest: +NORMALIZE_WHITESPACE {'keywords': ['general', 'support'], 'params': [{'gisprompt': False, 'multiple': False, 'name': 'pid', 'guidependency': '', 'default': '', 'age': None, 'required': True, 'value': '', 'label': '', 'guisection': '', 'key_desc': [], 'values': [], 'values_desc': [], 'prompt': None, 'hidden': False, 'element': None, 'type': 'integer', 'description': 'Process id to use when naming the tempfile'}], 'flags': [{'description': "Dry run - don't create a file, just prints it's file name", 'value': False, 'label': '', 'guisection': '', 'suppress_required': False, 'hidden': False, 'name': 'd'}, {'description': 'Print usage summary', 'value': False, 'label': '', 'guisection': '', 'suppress_required': False, 'hidden': False, 'name': 'help'}, {'description': 'Verbose module output', 'value': False, 'label': '', 'guisection': '', 'suppress_required': False, 'hidden': False, 'name': 'verbose'}, {'description': 'Quiet module output', 'value': False, 'label': '', 'guisection': '', 'suppress_required': False, 'hidden': False, 'name': 'quiet'}], 'description': "Creates a temporary file and prints it's file name.", 'usage': 'g.tempfile pid=integer [--help] [--verbose] [--quiet]'} >>> command_info('v.buffer') ['vector', 'geometry', 'buffer'] :param str cmd: the command to query """ task = parse_interface(cmd) cmdinfo = {} cmdinfo['description'] = task.get_description() cmdinfo['keywords'] = task.get_keywords() cmdinfo['flags'] = flags = task.get_options()['flags'] cmdinfo['params'] = params = task.get_options()['params'] usage = task.get_name() flags_short = list() flags_long = list() for f in flags: fname = f.get('name', 'unknown') if len(fname) > 1: flags_long.append(fname) else: flags_short.append(fname) if len(flags_short) > 1: usage += ' [-' + ''.join(flags_short) + ']' for p in params: ptype = ','.join(p.get('key_desc', [])) if not ptype: ptype = p.get('type', '') req = p.get('required', False) if not req: usage += ' [' else: usage += ' ' usage += p['name'] + '=' + ptype if p.get('multiple', False): usage += '[,' + ptype + ',...]' if not req: usage += ']' for key in flags_long: usage += ' [--' + key + ']' cmdinfo['usage'] = usage return cmdinfo
[docs]def cmdtuple_to_list(cmd): """Convert command tuple to list. :param tuple cmd: GRASS command to be converted :return: command in list """ cmdList = [] if not cmd: return cmdList cmdList.append(cmd[0]) if 'flags' in cmd[1]: for flag in cmd[1]['flags']: cmdList.append('-' + flag) for flag in ('help', 'verbose', 'quiet', 'overwrite'): if flag in cmd[1] and cmd[1][flag] is True: cmdList.append('--' + flag) for k, v in cmd[1].items(): if k in ('flags', 'help', 'verbose', 'quiet', 'overwrite'): continue if ' ' in v: v = '"%s"' % v cmdList.append('%s=%s' % (k, v)) return cmdList
[docs]def cmdlist_to_tuple(cmd): """Convert command list to tuple for run_command() and others :param list cmd: GRASS command to be converted :return: command as tuple """ if len(cmd) < 1: return None dcmd = {} for item in cmd[1:]: if '=' in item: # params key, value = item.split('=', 1) dcmd[str(key)] = value.replace('"', '') elif item[:2] == '--': # long flags flag = item[2:] if flag in ('help', 'verbose', 'quiet', 'overwrite'): dcmd[str(flag)] = True elif len(item) == 2 and item[0] == '-': # -> flags if 'flags' not in dcmd: dcmd['flags'] = '' dcmd['flags'] += item[1] else: # unnamed parameter module = parse_interface(cmd[0]) dcmd[module.define_first()] = item return (cmd[0], dcmd)
[docs]def cmdstring_to_tuple(cmd): """Convert command string to tuple for run_command() and others :param str cmd: command to be converted :return: command as tuple """ return cmdlist_to_tuple(split(cmd))