parsing.py documentation and todos

parsing.py

@@ -21,12 +21,12 @@ A Scope has
  - subscopes (Scope, Class, Function, Flow)
  - statements (Statement)
 
-All those classes are being generated by PyFuzzyParser, which takes python text
-as input.
+All these objects have `Name`s. `Call` and `Array` are used as detail objects
+of a statement.
 
-Ignored statements:
- - print (no use for it, just slows down)
- - exec (dangerous - not controllable)
+All those classes are being generated by PyFuzzyParser, which takes python text
+as input and ignores just all the non-python stuff. Basically you could feed it
+a perl script, and it should still work (which means throw no error.
 """
 from _compatibility import (next, literal_eval, tokenize_func, BytesIO,
                             property, is_py3k, Python3Method)
@@ -705,7 +705,6 @@ class Statement(Simple):
                         c_type = Call.NUMBER
 
                 if is_chain:
-                    #print 'chain', self, tok, result
                     call = Call(tok, c_type, start_pos, parent=result)
                     result = result.set_next_chain_call(call)
                     is_chain = False
@@ -801,13 +800,13 @@ class Param(Statement):
 
 class Call(object):
     """
-    TODO doc
+    `Call` contains a call, e.g. `foo.bar` and owns the executions of those
+    calls, which are `Array`s.
     """
     NAME = 1
     NUMBER = 2
     STRING = 3
 
-    """ The statement object of functions, to  """
     def __init__(self, name, type, start_pos, parent_stmt=None, parent=None):
         self.name = name
         # parent is not the oposite of next. The parent of c: a = [b.c] would
@@ -836,7 +835,6 @@ class Call(object):
     def set_next_chain_call(self, call):
         """ Adds another part of the statement"""
         self.next = call
-        #print '\n\npar', call.parent(), self.parent(), type(call), type(self)
         call.parent = self.parent
         return call
 
@@ -876,7 +874,7 @@ class Array(Call):
     """
     Describes the different python types for an array, but also empty
     statements. In the Python syntax definitions this type is named 'atom'.
-    http://docs.python.org/release/3.0.1/reference/grammar.html
+    http://docs.python.org/py3k/reference/grammar.html
     Array saves sub-arrays as well as normal operators and calls to methods.
 
     :param array_type: The type of an array, which can be one of the constants\
@@ -1010,7 +1008,6 @@ class ListComprehension(object):
                 (self.__class__.__name__, self.get_code())
 
     def get_code(self):
-        """ TODO return a valid representation """
         statements = self.stmt, self.middle, self.input
         code = [s.get_code().replace('\n', '') for s in statements]
         return "%s for %s in %s" % tuple(code)
@@ -1242,8 +1239,6 @@ class PyFuzzyParser(object):
         :type pre_used_token: set
         :return: Statement + last parsed token.
         :rtype: (Statement, str)
-
-        TODO improve abort criterion of not closing parentheses
         """
 
         string = ''
@@ -1288,7 +1283,6 @@ class PyFuzzyParser(object):
                     string += ".".join(n.names)
                 continue
             elif token_type == tokenize.NAME:
-                #print 'is_name', tok
                 if tok in ['return', 'yield', 'del', 'raise', 'assert']:
                     if len(tok_list) > 1:
                         # this happens, when a statement has opening brackets,
@@ -1311,7 +1305,7 @@ class PyFuzzyParser(object):
                     middle, tok = self._parse_statement(added_breaks=['in'])
                     if tok != 'in' or middle is None:
                         if middle is None:
-                            level -=1
+                            level -= 1
                         debug.warning('list comprehension formatting @%s' %
                                                             self.start_pos[0])
                         continue
@@ -1354,11 +1348,6 @@ class PyFuzzyParser(object):
                         string = ''
                     string += tok.get_code()
                     continue
-                elif tok in ['print', 'exec']:
-                    # TODO they should be reinstated, since the goal of the
-                    # parser is a different one.
-                    # delete those statements, just let the rest stand there
-                    set_string = ''
                 else:
                     n, token_type, tok = self._parsedotname(self.current)
                     tok_list.pop()  # removed last entry, because we add Name
@@ -1371,7 +1360,6 @@ class PyFuzzyParser(object):
                     if string and re.match(r'[\w\d\'"]', string[-1]):
                         string += ' '
                     string += ".".join(n.names)
-                    #print 'parse_stmt', tok, tokenize.tok_name[token_type]
                     continue
             elif '=' in tok and not tok in ['>=', '<=', '==', '!=']:
                 # there has been an assignement -> change vars