release/scripts/bpymodules/BPyTextPlugin.py

   1 import bpy, sys, os
   2 import __builtin__, tokenize
   3 from Blender.sys import time
   4 from tokenize import generate_tokens, TokenError, \
   5                 COMMENT, DEDENT, INDENT, NAME, NEWLINE, NL, STRING
   6
   7 class ScriptDesc():
   8         """Describes a script through lists of further descriptor objects (classes,
   9         defs, vars) and dictionaries to built-in types (imports). If a script has
  10         not been fully parsed, its incomplete flag will be set. The time of the last
  11         parse is held by the time field and the name of the text object from which
  12         it was parsed, the name field.
  13         """
  14
  15         def __init__(self, name, imports, classes, defs, vars, incomplete=False):
  16                 self.name = name
  17                 self.imports = imports
  18                 self.classes = classes
  19                 self.defs = defs
  20                 self.vars = vars
  21                 self.incomplete = incomplete
  22                 self.time = 0
  23
  24         def set_time(self):
  25                 self.time = time()
  26
  27 class ClassDesc():
  28         """Describes a class through lists of further descriptor objects (defs and
  29         vars). The name of the class is held by the name field and the line on
  30         which it is defined is held in lineno.
  31         """
  32
  33         def __init__(self, name, defs, vars, lineno):
  34                 self.name = name
  35                 self.defs = defs
  36                 self.vars = vars
  37                 self.lineno = lineno
  38
  39 class FunctionDesc():
  40         """Describes a function through its name and list of parameters (name,
  41         params) and the line on which it is defined (lineno).
  42         """
  43
  44         def __init__(self, name, params, lineno):
  45                 self.name = name
  46                 self.params = params
  47                 self.lineno = lineno
  48
  49 class VarDesc():
  50         """Describes a variable through its name and type (if ascertainable) and the
  51         line on which it is defined (lineno). If no type can be determined, type
  52         will equal None.
  53         """
  54
  55         def __init__(self, name, type, lineno):
  56                 self.name = name
  57                 self.type = type # None for unknown (supports: dict/list/str)
  58                 self.lineno = lineno
  59
  60 # Context types
  61 CTX_UNSET = -1
  62 CTX_NORMAL = 0
  63 CTX_SINGLE_QUOTE = 1
  64 CTX_DOUBLE_QUOTE = 2
  65 CTX_COMMENT = 3
  66
  67 # Special time period constants
  68 TP_AUTO = -1
  69
  70 # Python keywords
  71 KEYWORDS = ['and', 'del', 'from', 'not', 'while', 'as', 'elif', 'global',
  72                         'or', 'with', 'assert', 'else', 'if', 'pass', 'yield',
  73                         'break', 'except', 'import', 'print', 'class', 'exec', 'in',
  74                         'raise', 'continue', 'finally', 'is', 'return', 'def', 'for',
  75                         'lambda', 'try' ]
  76
  77 # Module file extensions
  78 MODULE_EXTS = ['.py', '.pyc', '.pyo', '.pyw', '.pyd']
  79
  80 ModuleType = type(__builtin__)
  81 NoneScriptDesc = ScriptDesc('', dict(), dict(), dict(), dict(), True)
  82
  83 _modules = {}
  84 _modules_updated = 0
  85 _parse_cache = dict()
  86
  87 def _load_module_names():
  88         """Searches the sys.path for module files and lists them, along with
  89         sys.builtin_module_names, in the global dict _modules.
  90         """
  91
  92         global _modules
  93
  94         for n in sys.builtin_module_names:
  95                 _modules[n] = None
  96         for p in sys.path:
  97                 if p == '': p = os.curdir
  98                 if not os.path.isdir(p): continue
  99                 for f in os.listdir(p):
 100                         for ext in MODULE_EXTS:
 101                                 if f.endswith(ext):
 102                                         _modules[f[:-len(ext)]] = None
 103                                         break
 104
 105 _load_module_names()
 106
 107
 108 def get_cached_descriptor(txt, period=TP_AUTO):
 109         """Returns the cached ScriptDesc for the specified Text object 'txt'. If the
 110         script has not been parsed in the last 'period' seconds it will be reparsed
 111         to obtain this descriptor.
 112
 113         Specifying TP_AUTO for the period (default) will choose a period based on the
 114         size of the Text object. Larger texts are parsed less often.
 115         """
 116
 117         global _parse_cache
 118
 119         if period == TP_AUTO:
 120                 m = txt.nlines
 121                 r = 1
 122                 while True:
 123                         m = m >> 2
 124                         if not m: break
 125                         r = r << 1
 126                 period = r
 127
 128         parse = True
 129         key = hash(txt)
 130         if _parse_cache.has_key(key):
 131                 desc = _parse_cache[key]
 132                 if desc.time >= time() - period:
 133                         parse = desc.incomplete
 134
 135         if parse:
 136                 desc = parse_text(txt)
 137
 138         return desc
 139
 140 def parse_text(txt):
 141         """Parses an entire script's text and returns a ScriptDesc instance
 142         containing information about the script.
 143
 144         If the text is not a valid Python script (for example if brackets are left
 145         open), parsing may fail to complete. However, if this occurs, no exception
 146         is thrown. Instead the returned ScriptDesc instance will have its incomplete
 147         flag set and information processed up to this point will still be accessible.
 148         """
 149
 150         txt.reset()
 151         tokens = generate_tokens(txt.readline) # Throws TokenError
 152
 153         curl, cursor = txt.getCursorPos()
 154         linen = curl + 1 # Token line numbers are one-based
 155
 156         imports = dict()
 157         imp_step = 0
 158
 159         classes = dict()
 160         cls_step = 0
 161
 162         defs = dict()
 163         def_step = 0
 164
 165         vars = dict()
 166         var1_step = 0
 167         var2_step = 0
 168         var3_step = 0
 169         var_accum = dict()
 170         var_forflag = False
 171
 172         indent = 0
 173         prev_type = -1
 174         prev_string = ''
 175         incomplete = False
 176
 177         while True:
 178                 try:
 179                         type, string, start, end, line = tokens.next()
 180                 except StopIteration:
 181                         break
 182                 except TokenError, IndentationError:
 183                         incomplete = True
 184                         break
 185
 186                 # Skip all comments and line joining characters
 187                 if type == COMMENT or type == NL:
 188                         continue
 189
 190                 #################
 191                 ## Indentation ##
 192                 #################
 193
 194                 if type == INDENT:
 195                         indent += 1
 196                 elif type == DEDENT:
 197                         indent -= 1
 198
 199                 #########################
 200                 ## Module importing... ##
 201                 #########################
 202
 203                 imp_store = False
 204
 205                 # Default, look for 'from' or 'import' to start
 206                 if imp_step == 0:
 207                         if string == 'from':
 208                                 imp_tmp = []
 209                                 imp_step = 1
 210                         elif string == 'import':
 211                                 imp_from = None
 212                                 imp_tmp = []
 213                                 imp_step = 2
 214
 215                 # Found a 'from', create imp_from in form '???.???...'
 216                 elif imp_step == 1:
 217                         if string == 'import':
 218                                 imp_from = '.'.join(imp_tmp)
 219                                 imp_tmp = []
 220                                 imp_step = 2
 221                         elif type == NAME:
 222                                 imp_tmp.append(string)
 223                         elif string != '.':
 224                                 imp_step = 0 # Invalid syntax
 225
 226                 # Found 'import', imp_from is populated or None, create imp_name
 227                 elif imp_step == 2:
 228                         if string == 'as':
 229                                 imp_name = '.'.join(imp_tmp)
 230                                 imp_step = 3
 231                         elif type == NAME or string == '*':
 232                                 imp_tmp.append(string)
 233                         elif string != '.':
 234                                 imp_name = '.'.join(imp_tmp)
 235                                 imp_symb = imp_name
 236                                 imp_store = True
 237
 238                 # Found 'as', change imp_symb to this value and go back to step 2
 239                 elif imp_step == 3:
 240                         if type == NAME:
 241                                 imp_symb = string
 242                         else:
 243                                 imp_store = True
 244
 245                 # Both imp_name and imp_symb have now been populated so we can import
 246                 if imp_store:
 247
 248                         # Handle special case of 'import *'
 249                         if imp_name == '*':
 250                                 parent = get_module(imp_from)
 251                                 imports.update(parent.__dict__)
 252
 253                         else:
 254                                 # Try importing the name as a module
 255                                 try:
 256                                         if imp_from:
 257                                                 module = get_module(imp_from +'.'+ imp_name)
 258                                         else:
 259                                                 module = get_module(imp_name)
 260                                 except (ImportError, ValueError, AttributeError, TypeError):
 261                                         # Try importing name as an attribute of the parent
 262                                         try:
 263                                                 module = __import__(imp_from, globals(), locals(), [imp_name])
 264                                                 imports[imp_symb] = getattr(module, imp_name)
 265                                         except (ImportError, ValueError, AttributeError, TypeError):
 266                                                 pass
 267                                 else:
 268                                         imports[imp_symb] = module
 269
 270                         # More to import from the same module?
 271                         if string == ',':
 272                                 imp_tmp = []
 273                                 imp_step = 2
 274                         else:
 275                                 imp_step = 0
 276
 277                 ###################
 278                 ## Class parsing ##
 279                 ###################
 280
 281                 # If we are inside a class then def and variable parsing should be done
 282                 # for the class. Otherwise the definitions are considered global
 283
 284                 # Look for 'class'
 285                 if cls_step == 0:
 286                         if string == 'class':
 287                                 cls_name = None
 288                                 cls_lineno = start[0]
 289                                 cls_indent = indent
 290                                 cls_step = 1
 291
 292                 # Found 'class', look for cls_name followed by '('
 293                 elif cls_step == 1:
 294                         if not cls_name:
 295                                 if type == NAME:
 296                                         cls_name = string
 297                                         cls_sline = False
 298                                         cls_defs = dict()
 299                                         cls_vars = dict()
 300                         elif string == ':':
 301                                 cls_step = 2
 302
 303                 # Found 'class' name ... ':', now check if it's a single line statement
 304                 elif cls_step == 2:
 305                         if type == NEWLINE:
 306                                 cls_sline = False
 307                                 cls_step = 3
 308                         else:
 309                                 cls_sline = True
 310                                 cls_step = 3
 311
 312                 elif cls_step == 3:
 313                         if cls_sline:
 314                                 if type == NEWLINE:
 315                                         classes[cls_name] = ClassDesc(cls_name, cls_defs, cls_vars, cls_lineno)
 316                                         cls_step = 0
 317                         else:
 318                                 if type == DEDENT and indent <= cls_indent:
 319                                         classes[cls_name] = ClassDesc(cls_name, cls_defs, cls_vars, cls_lineno)
 320                                         cls_step = 0
 321
 322                 #################
 323                 ## Def parsing ##
 324                 #################
 325
 326                 # Look for 'def'
 327                 if def_step == 0:
 328                         if string == 'def':
 329                                 def_name = None
 330                                 def_lineno = start[0]
 331                                 def_step = 1
 332
 333                 # Found 'def', look for def_name followed by '('
 334                 elif def_step == 1:
 335                         if type == NAME:
 336                                 def_name = string
 337                                 def_params = []
 338                         elif def_name and string == '(':
 339                                 def_step = 2
 340
 341                 # Found 'def' name '(', now identify the parameters upto ')'
 342                 # TODO: Handle ellipsis '...'
 343                 elif def_step == 2:
 344                         if type == NAME:
 345                                 def_params.append(string)
 346                         elif string == ')':
 347                                 if cls_step > 0: # Parsing a class
 348                                         cls_defs[def_name] = FunctionDesc(def_name, def_params, def_lineno)
 349                                 else:
 350                                         defs[def_name] = FunctionDesc(def_name, def_params, def_lineno)
 351                                 def_step = 0
 352
 353                 ##########################
 354                 ## Variable assignation ##
 355                 ##########################
 356
 357                 if cls_step > 0: # Parsing a class
 358                         # Look for 'self.???'
 359                         if var1_step == 0:
 360                                 if string == 'self':
 361                                         var1_step = 1
 362                         elif var1_step == 1:
 363                                 if string == '.':
 364                                         var_name = None
 365                                         var1_step = 2
 366                                 else:
 367                                         var1_step = 0
 368                         elif var1_step == 2:
 369                                 if type == NAME:
 370                                         var_name = string
 371                                         if cls_vars.has_key(var_name):
 372                                                 var_step = 0
 373                                         else:
 374                                                 var1_step = 3
 375                         elif var1_step == 3:
 376                                 if string == '=':
 377                                         var1_step = 4
 378                         elif var1_step == 4:
 379                                 var_type = None
 380                                 if string == '[':
 381                                         close = line.find(']', end[1])
 382                                         var_type = list
 383                                 elif type == STRING:
 384                                         close = end[1]
 385                                         var_type = str
 386                                 elif string == '(':
 387                                         close = line.find(')', end[1])
 388                                         var_type = tuple
 389                                 elif string == '{':
 390                                         close = line.find('}', end[1])
 391                                         var_type = dict
 392                                 elif string == 'dict':
 393                                         close = line.find(')', end[1])
 394                                         var_type = dict
 395                                 if var_type and close+1 < len(line):
 396                                         if line[close+1] != ' ' and line[close+1] != '\t':
 397                                                 var_type = None
 398                                 cls_vars[var_name] = VarDesc(var_name, var_type, start[0])
 399                                 var1_step = 0
 400
 401                 elif def_step > 0: # Parsing a def
 402                         # Look for 'global ???[,???]'
 403                         if var2_step == 0:
 404                                 if string == 'global':
 405                                         var2_step = 1
 406                         elif var2_step == 1:
 407                                 if type == NAME:
 408                                         vars[string] = True
 409                                 elif string != ',' and type != NL:
 410                                         var2_step == 0
 411
 412                 else: # In global scope
 413                         if var3_step == 0:
 414                                 # Look for names
 415                                 if string == 'for':
 416                                         var_accum = dict()
 417                                         var_forflag = True
 418                                 elif string == '=' or (var_forflag and string == 'in'):
 419                                         var_forflag = False
 420                                         var3_step = 1
 421                                 elif type == NAME:
 422                                         if prev_string != '.' and not vars.has_key(string):
 423                                                 var_accum[string] = VarDesc(string, None, start[0])
 424                                 elif not string in [',', '(', ')', '[', ']']:
 425                                         var_accum = dict()
 426                                         var_forflag = False
 427                         elif var3_step == 1:
 428                                 if len(var_accum) != 1:
 429                                         var_type = None
 430                                         vars.update(var_accum)
 431                                 else:
 432                                         var_name = var_accum.keys()[0]
 433                                         var_type = None
 434                                         if string == '[': var_type = list
 435                                         elif type == STRING: var_type = str
 436                                         elif string == '(': var_type = tuple
 437                                         elif string == '{': var_type = dict
 438                                         vars[var_name] = VarDesc(var_name, var_type, start[0])
 439                                 var3_step = 0
 440
 441                 #######################
 442                 ## General utilities ##
 443                 #######################
 444
 445                 prev_type = type
 446                 prev_string = string
 447
 448         desc = ScriptDesc(txt.name, imports, classes, defs, vars, incomplete)
 449         desc.set_time()
 450
 451         global _parse_cache
 452         _parse_cache[hash(txt)] = desc
 453         return desc
 454
 455 def get_modules(since=1):
 456         """Returns the set of built-in modules and any modules that have been
 457         imported into the system upto 'since' seconds ago.
 458         """
 459
 460         global _modules, _modules_updated
 461
 462         t = time()
 463         if _modules_updated < t - since:
 464                 _modules.update(sys.modules)
 465                 _modules_updated = t
 466         return _modules.keys()
 467
 468 def suggest_cmp(x, y):
 469         """Use this method when sorting a list of suggestions.
 470         """
 471
 472         return cmp(x[0].upper(), y[0].upper())
 473
 474 def get_module(name):
 475         """Returns the module specified by its name. The module itself is imported
 476         by this method and, as such, any initialization code will be executed.
 477         """
 478
 479         mod = __import__(name)
 480         components = name.split('.')
 481         for comp in components[1:]:
 482                 mod = getattr(mod, comp)
 483         return mod
 484
 485 def type_char(v):
 486         """Returns the character used to signify the type of a variable. Use this
 487         method to identify the type character for an item in a suggestion list.
 488
 489         The following values are returned:
 490           'm' if the parameter is a module
 491           'f' if the parameter is callable
 492           'v' if the parameter is variable or otherwise indeterminable
 493
 494         """
 495
 496         if isinstance(v, ModuleType):
 497                 return 'm'
 498         elif callable(v):
 499                 return 'f'
 500         else:
 501                 return 'v'
 502
 503 def get_context(txt):
 504         """Establishes the context of the cursor in the given Blender Text object
 505
 506         Returns one of:
 507           CTX_NORMAL - Cursor is in a normal context
 508           CTX_SINGLE_QUOTE - Cursor is inside a single quoted string
 509           CTX_DOUBLE_QUOTE - Cursor is inside a double quoted string
 510           CTX_COMMENT - Cursor is inside a comment
 511
 512         """
 513
 514         l, cursor = txt.getCursorPos()
 515         lines = txt.asLines(0, l+1)
 516
 517         # FIXME: This method is too slow in large files for it to be called as often
 518         # as it is. So for lines below the 1000th line we do this... (quorn)
 519         if l > 1000: return CTX_NORMAL
 520
 521         # Detect context (in string or comment)
 522         in_str = CTX_NORMAL
 523         for line in lines:
 524                 if l == 0:
 525                         end = cursor
 526                 else:
 527                         end = len(line)
 528                         l -= 1
 529
 530                 # Comments end at new lines
 531                 if in_str == CTX_COMMENT:
 532                         in_str = CTX_NORMAL
 533
 534                 for i in range(end):
 535                         if in_str == 0:
 536                                 if line[i] == "'": in_str = CTX_SINGLE_QUOTE
 537                                 elif line[i] == '"': in_str = CTX_DOUBLE_QUOTE
 538                                 elif line[i] == '#': in_str = CTX_COMMENT
 539                         else:
 540                                 if in_str == CTX_SINGLE_QUOTE:
 541                                         if line[i] == "'":
 542                                                 in_str = CTX_NORMAL
 543                                                 # In again if ' escaped, out again if \ escaped, and so on
 544                                                 for a in range(i-1, -1, -1):
 545                                                         if line[a] == '\\': in_str = 1-in_str
 546                                                         else: break
 547                                 elif in_str == CTX_DOUBLE_QUOTE:
 548                                         if line[i] == '"':
 549                                                 in_str = CTX_NORMAL
 550                                                 # In again if " escaped, out again if \ escaped, and so on
 551                                                 for a in range(i-1, -1, -1):
 552                                                         if line[i-a] == '\\': in_str = 2-in_str
 553                                                         else: break
 554
 555         return in_str
 556
 557 def current_line(txt):
 558         """Extracts the Python script line at the cursor in the Blender Text object
 559         provided and cursor position within this line as the tuple pair (line,
 560         cursor).
 561         """
 562
 563         lineindex, cursor = txt.getCursorPos()
 564         lines = txt.asLines()
 565         line = lines[lineindex]
 566
 567         # Join previous lines to this line if spanning
 568         i = lineindex - 1
 569         while i > 0:
 570                 earlier = lines[i].rstrip()
 571                 if earlier.endswith('\\'):
 572                         line = earlier[:-1] + ' ' + line
 573                         cursor += len(earlier)
 574                 i -= 1
 575
 576         # Join later lines while there is an explicit joining character
 577         i = lineindex
 578         while i < len(lines)-1 and lines[i].rstrip().endswith('\\'):
 579                 later = lines[i+1].strip()
 580                 line = line + ' ' + later[:-1]
 581                 i += 1
 582
 583         return line, cursor
 584
 585 def get_targets(line, cursor):
 586         """Parses a period separated string of valid names preceding the cursor and
 587         returns them as a list in the same order.
 588         """
 589
 590         targets = []
 591         i = cursor - 1
 592         while i >= 0 and (line[i].isalnum() or line[i] == '_' or line[i] == '.'):
 593                 i -= 1
 594
 595         pre = line[i+1:cursor]
 596         return pre.split('.')
 597
 598 def get_defs(txt):
 599         """Returns a dictionary which maps definition names in the source code to
 600         a list of their parameter names.
 601
 602         The line 'def doit(one, two, three): print one' for example, results in the
 603         mapping 'doit' : [ 'one', 'two', 'three' ]
 604         """
 605
 606         return get_cached_descriptor(txt).defs
 607
 608 def get_vars(txt):
 609         """Returns a dictionary of variable names found in the specified Text
 610         object. This method locates all names followed directly by an equal sign:
 611         'a = ???' or indirectly as part of a tuple/list assignment or inside a
 612         'for ??? in ???:' block.
 613         """
 614
 615         return get_cached_descriptor(txt).vars
 616
 617 def get_imports(txt):
 618         """Returns a dictionary which maps symbol names in the source code to their
 619         respective modules.
 620
 621         The line 'from Blender import Text as BText' for example, results in the
 622         mapping 'BText' : <module 'Blender.Text' (built-in)>
 623
 624         Note that this method imports the modules to provide this mapping as as such
 625         will execute any initilization code found within.
 626         """
 627
 628         return get_cached_descriptor(txt).imports
 629
 630 def get_builtins():
 631         """Returns a dictionary of built-in modules, functions and variables."""
 632
 633         return __builtin__.__dict__
 634
 635
 636 #################################
 637 ## Debugging utility functions ##
 638 #################################
 639
 640 def print_cache_for(txt, period=sys.maxint):
 641         """Prints out the data cached for a given Text object. If no period is
 642         given the text will not be reparsed and the cached version will be returned.
 643         Otherwise if the period has expired the text will be reparsed.
 644         """
 645
 646         desc = get_cached_descriptor(txt, period)
 647         print '================================================'
 648         print 'Name:', desc.name, '('+str(hash(txt))+')'
 649         print '------------------------------------------------'
 650         print 'Defs:'
 651         for name, ddesc in desc.defs.items():
 652                 print ' ', name, ddesc.params, ddesc.lineno
 653         print '------------------------------------------------'
 654         print 'Vars:'
 655         for name, vdesc in desc.vars.items():
 656                 print ' ', name, vdesc.type, vdesc.lineno
 657         print '------------------------------------------------'
 658         print 'Imports:'
 659         for name, item in desc.imports.items():
 660                 print ' ', name.ljust(15), item
 661         print '------------------------------------------------'
 662         print 'Classes:'
 663         for clsnme, clsdsc in desc.classes.items():
 664                 print '  *********************************'
 665                 print '  Name:', clsnme
 666                 print '  ---------------------------------'
 667                 print '  Defs:'
 668                 for name, ddesc in clsdsc.defs.items():
 669                         print '   ', name, ddesc.params, ddesc.lineno
 670                 print '  ---------------------------------'
 671                 print '  Vars:'
 672                 for name, vdesc in clsdsc.vars.items():
 673                         print '   ', name, vdesc.type, vdesc.lineno
 674                 print '  *********************************'
 675         print '================================================'