DOC: update docs in enhancedperf.rst

TST: addtional tests for multiple assignment, targets
ENH: add target to Scope, use instead of resolvers

Author: jreback

doc/source/enhancingperf.rst

@@ -441,18 +441,27 @@ The ``DataFrame.eval`` method (Experimental)
 In addition to the top level :func:`~pandas.eval` function you can also
 evaluate an expression in the "context" of a ``DataFrame``.
 
-
 .. ipython:: python
 
    df = DataFrame(randn(5, 2), columns=['a', 'b'])
    df.eval('a + b')
 
-
 Any expression that is a valid :func:`~pandas.eval` expression is also a valid
 ``DataFrame.eval`` expression, with the added benefit that *you don't have to
 prefix the name of the* ``DataFrame`` *to the column you're interested in
 evaluating*.
 
+In addition, you can perform in-line assignment of columns within an expression.
+This can allow for *formulaic evaluation*. Only a signle assignement is permitted.
+It can be a new column name or an existing column name. It must be a string-like.
+
+.. ipython:: python
+
+   df = DataFrame(dict(a = range(5), b = range(5,10)))
+   df.eval('c=a+b')
+   df.eval('d=a+b+c')
+   df.eval('a=1')
+   df
 
 Local Variables
 ~~~~~~~~~~~~~~~

pandas/computation/eval.py

@@ -113,7 +113,8 @@ def _convert_expression(expr):
 
 
 def eval(expr, parser='pandas', engine='numexpr', truediv=True,
-         local_dict=None, global_dict=None, resolvers=None, level=2):
+         local_dict=None, global_dict=None, resolvers=None, level=2,
+         target=None):
     """Evaluate a Python expression as a string using various backends.
 
     The following arithmetic operations are supported: ``+``, ``-``, ``*``,
@@ -169,6 +170,8 @@ def eval(expr, parser='pandas', engine='numexpr', truediv=True,
     level : int, optional
         The number of prior stack frames to traverse and add to the current
         scope. Most users will **not** need to change this parameter.
+    target : a target object for assignment, optional, default is None
+        essentially this is a passed in resolver
 
     Returns
     -------
@@ -194,7 +197,7 @@ def eval(expr, parser='pandas', engine='numexpr', truediv=True,
 
     # get our (possibly passed-in) scope
     env = _ensure_scope(global_dict=global_dict, local_dict=local_dict,
-                        resolvers=resolvers, level=level)
+                        resolvers=resolvers, level=level, target=target)
 
     parsed_expr = Expr(expr, engine=engine, parser=parser, env=env,
                        truediv=truediv)
@@ -205,8 +208,8 @@ def eval(expr, parser='pandas', engine='numexpr', truediv=True,
     ret = eng_inst.evaluate()
 
     # assign if needed
-    if parsed_expr.assignee is not None and parsed_expr.assigner is not None:
-        parsed_expr.assignee[parsed_expr.assigner] = ret
+    if env.target is not None and parsed_expr.assigner is not None:
+        env.target[parsed_expr.assigner] = ret
         return None
 
     return ret

pandas/computation/expr.py

@@ -25,10 +25,10 @@
 
 
 def _ensure_scope(level=2, global_dict=None, local_dict=None, resolvers=None,
-                  **kwargs):
+                  target=None, **kwargs):
     """Ensure that we are grabbing the correct scope."""
     return Scope(gbls=global_dict, lcls=local_dict, level=level,
-                 resolvers=resolvers)
+                 resolvers=resolvers, target=target)
 
 
 def _check_disjoint_resolver_names(resolver_keys, local_keys, global_keys):
@@ -89,20 +89,23 @@ class Scope(StringMixin):
     resolver_keys : frozenset
     """
     __slots__ = ('globals', 'locals', 'resolvers', '_global_resolvers',
-                 'resolver_keys', '_resolver', 'level', 'ntemps')
+                 'resolver_keys', '_resolver', 'level', 'ntemps', 'target')
 
-    def __init__(self, gbls=None, lcls=None, level=1, resolvers=None):
+    def __init__(self, gbls=None, lcls=None, level=1, resolvers=None, target=None):
         self.level = level
         self.resolvers = tuple(resolvers or [])
         self.globals = dict()
         self.locals = dict()
+        self.target = target
         self.ntemps = 1  # number of temporary variables in this scope
 
         if isinstance(lcls, Scope):
             ld, lcls = lcls, dict()
             self.locals.update(ld.locals.copy())
             self.globals.update(ld.globals.copy())
             self.resolvers += ld.resolvers
+            if ld.target is not None:
+                self.target = ld.target
             self.update(ld.level)
 
         frame = sys._getframe(level)
@@ -131,9 +134,10 @@ def __init__(self, gbls=None, lcls=None, level=1, resolvers=None):
 
     def __unicode__(self):
         return com.pprint_thing("locals: {0}\nglobals: {0}\nresolvers: "
-                                "{0}".format(list(self.locals.keys()),
-                                             list(self.globals.keys()),
-                                             list(self.resolver_keys)))
+                                "{0}\ntarget: {0}".format(list(self.locals.keys()),
+                                                          list(self.globals.keys()),
+                                                          list(self.resolver_keys),
+                                                          self.target))
 
     def __getitem__(self, key):
         return self.resolve(key, globally=False)
@@ -418,7 +422,6 @@ def __init__(self, env, engine, parser, preparser=_preparse):
         self.engine = engine
         self.parser = parser
         self.preparser = preparser
-        self.assignee = None
         self.assigner = None
 
     def visit(self, node, **kwargs):
@@ -583,7 +586,7 @@ def visit_Assign(self, node, **kwargs):
 
         c = a + b
 
-        set the assignee at the top level, must be a Name node which
+        set the assigner at the top level, must be a Name node which
         might or might not exist in the resolvers
 
         """
@@ -592,10 +595,8 @@ def visit_Assign(self, node, **kwargs):
             raise SyntaxError('can only assign a single expression')
         if not isinstance(node.targets[0], ast.Name):
             raise SyntaxError('left hand side of an assignment must be a single name')
-
-        # we have no one to assign to
-        if not len(self.env.resolvers):
-            raise NotImplementedError
+        if self.env.target is None:
+            raise ValueError('cannot assign without a target object')
 
         try:
             assigner = self.visit(node.targets[0], **kwargs)
@@ -605,10 +606,6 @@ def visit_Assign(self, node, **kwargs):
         self.assigner = getattr(assigner,'name',assigner)
         if self.assigner is None:
             raise SyntaxError('left hand side of an assignment must be a single resolvable name')
-        try:
-            self.assignee = self.env.resolvers[0]
-        except:
-            raise ValueError('cannot create an assignee for this expression')
 
         return self.visit(node.value, **kwargs)
 
@@ -749,10 +746,6 @@ def __init__(self, expr, engine='numexpr', parser='pandas', env=None,
     def assigner(self):
         return getattr(self._visitor,'assigner',None)
 
-    @property
-    def assignee(self):
-        return getattr(self._visitor,'assignee',None)
-
     def __call__(self):
         self.env.locals['truediv'] = self.truediv
         return self.terms(self.env)

pandas/computation/tests/test_eval.py

@@ -1152,10 +1152,11 @@ def test_assignment_fails(self):
         df = DataFrame(np.random.randn(5, 3), columns=list('abc'))
         df2 = DataFrame(np.random.randn(5, 3))
         expr1 = 'df = df2'
-        self.assertRaises(NotImplementedError, self.eval, expr1,
+        self.assertRaises(ValueError, self.eval, expr1,
                           local_dict={'df': df, 'df2': df2})
 
     def test_assignment_column(self):
+        skip_if_no_ne('numexpr')
         df = DataFrame(np.random.randn(5, 2), columns=list('ab'))
         orig_df = df.copy()
 
@@ -1181,9 +1182,13 @@ def test_assignment_column(self):
         assert_frame_equal(df,expected)
 
         # with a local name overlap
-        a = 1
-        df = orig_df.copy()
-        df.eval('a = 1 + b')
+        def f():
+            df = orig_df.copy()
+            a = 1
+            df.eval('a = 1 + b')
+            return df
+
+        df = f()
         expected = orig_df.copy()
         expected['a'] = 1 + expected['b']
         assert_frame_equal(df,expected)
@@ -1194,6 +1199,18 @@ def f():
             df.eval('a=a+b')
         self.assertRaises(NameResolutionError, f)
 
+        # multiple assignment
+        df = orig_df.copy()
+        df.eval('c = a + b')
+        self.assertRaises(SyntaxError, df.eval, 'c = a = b')
+
+        # explicit targets
+        df = orig_df.copy()
+        self.eval('c = df.a + df.b', local_dict={'df' : df}, target=df)
+        expected = orig_df.copy()
+        expected['c'] = expected['a'] + expected['b']
+        assert_frame_equal(df,expected)
+
     def test_basic_period_index_boolean_expression(self):
         df = mkdf(2, 2, data_gen_f=f, c_idx_type='p', r_idx_type='i')
 

pandas/core/frame.py

@@ -1797,12 +1797,14 @@ def eval(self, expr, **kwargs):
         >>> from pandas import DataFrame
         >>> df = DataFrame(randn(10, 2), columns=list('ab'))
         >>> df.eval('a + b')
+        >>> df.eval('c=a + b')
         """
         resolvers = kwargs.pop('resolvers', None)
         if resolvers is None:
             index_resolvers = self._get_resolvers()
             resolvers = [self, index_resolvers]
         kwargs['local_dict'] = _ensure_scope(resolvers=resolvers, **kwargs)
+        kwargs['target'] = self
         return _eval(expr, **kwargs)
 
     def _slice(self, slobj, axis=0, raise_on_error=False, typ=None):