Skip to content

Commit a2a78d3

Browse files
mutricylLaurent Mutricy
and
Laurent Mutricy
authored
updating df.query and df.eval docstrings. resolves #16283 (#58749)
* updating df.query and df.eval docstrings. resolves #16283 * typo * adding 1 example * changing wording following example added * updating 'C C' to 'C&C' for eval * updating 'C C' to 'C&C' for query --------- Co-authored-by: Laurent Mutricy <[email protected]>
1 parent f95c3a0 commit a2a78d3

File tree

1 file changed

+73
-36
lines changed

1 file changed

+73
-36
lines changed

pandas/core/frame.py

+73-36
Original file line numberDiff line numberDiff line change
@@ -4577,36 +4577,44 @@ def query(self, expr: str, *, inplace: bool = False, **kwargs) -> DataFrame | No
45774577
Examples
45784578
--------
45794579
>>> df = pd.DataFrame(
4580-
... {"A": range(1, 6), "B": range(10, 0, -2), "C C": range(10, 5, -1)}
4580+
... {"A": range(1, 6), "B": range(10, 0, -2), "C&C": range(10, 5, -1)}
45814581
... )
45824582
>>> df
4583-
A B C C
4583+
A B C&C
45844584
0 1 10 10
45854585
1 2 8 9
45864586
2 3 6 8
45874587
3 4 4 7
45884588
4 5 2 6
45894589
>>> df.query("A > B")
4590-
A B C C
4590+
A B C&C
45914591
4 5 2 6
45924592
45934593
The previous expression is equivalent to
45944594
45954595
>>> df[df.A > df.B]
4596-
A B C C
4596+
A B C&C
45974597
4 5 2 6
45984598
45994599
For columns with spaces in their name, you can use backtick quoting.
46004600
4601-
>>> df.query("B == `C C`")
4602-
A B C C
4601+
>>> df.query("B == `C&C`")
4602+
A B C&C
46034603
0 1 10 10
46044604
46054605
The previous expression is equivalent to
46064606
4607-
>>> df[df.B == df["C C"]]
4608-
A B C C
4607+
>>> df[df.B == df["C&C"]]
4608+
A B C&C
46094609
0 1 10 10
4610+
4611+
Using local variable:
4612+
4613+
>>> local_var = 2
4614+
>>> df.query("A <= @local_var")
4615+
A B C&C
4616+
0 1 10 10
4617+
1 2 8 9
46104618
"""
46114619
inplace = validate_bool_kwarg(inplace, "inplace")
46124620
if not isinstance(expr, str):
@@ -4647,6 +4655,13 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
46474655
----------
46484656
expr : str
46494657
The expression string to evaluate.
4658+
4659+
You can refer to variables
4660+
in the environment by prefixing them with an '@' character like
4661+
``@a + b``.
4662+
4663+
You can refer to column names that are not valid Python variable
4664+
names by surrounding them with backticks `````.
46504665
inplace : bool, default False
46514666
If the expression contains an assignment, whether to perform the
46524667
operation inplace and mutate the existing DataFrame. Otherwise,
@@ -4678,14 +4693,16 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
46784693
46794694
Examples
46804695
--------
4681-
>>> df = pd.DataFrame({"A": range(1, 6), "B": range(10, 0, -2)})
4696+
>>> df = pd.DataFrame(
4697+
... {"A": range(1, 6), "B": range(10, 0, -2), "C&C": range(10, 5, -1)}
4698+
... )
46824699
>>> df
4683-
A B
4684-
0 1 10
4685-
1 2 8
4686-
2 3 6
4687-
3 4 4
4688-
4 5 2
4700+
A B C&C
4701+
0 1 10 10
4702+
1 2 8 9
4703+
2 3 6 8
4704+
3 4 4 7
4705+
4 5 2 6
46894706
>>> df.eval("A + B")
46904707
0 11
46914708
1 10
@@ -4697,35 +4714,55 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
46974714
Assignment is allowed though by default the original DataFrame is not
46984715
modified.
46994716
4700-
>>> df.eval("C = A + B")
4701-
A B C
4702-
0 1 10 11
4703-
1 2 8 10
4704-
2 3 6 9
4705-
3 4 4 8
4706-
4 5 2 7
4717+
>>> df.eval("D = A + B")
4718+
A B C&C D
4719+
0 1 10 10 11
4720+
1 2 8 9 10
4721+
2 3 6 8 9
4722+
3 4 4 7 8
4723+
4 5 2 6 7
47074724
>>> df
4708-
A B
4709-
0 1 10
4710-
1 2 8
4711-
2 3 6
4712-
3 4 4
4713-
4 5 2
4725+
A B C&C
4726+
0 1 10 10
4727+
1 2 8 9
4728+
2 3 6 8
4729+
3 4 4 7
4730+
4 5 2 6
47144731
47154732
Multiple columns can be assigned to using multi-line expressions:
47164733
47174734
>>> df.eval(
47184735
... '''
4719-
... C = A + B
4720-
... D = A - B
4736+
... D = A + B
4737+
... E = A - B
47214738
... '''
47224739
... )
4723-
A B C D
4724-
0 1 10 11 -9
4725-
1 2 8 10 -6
4726-
2 3 6 9 -3
4727-
3 4 4 8 0
4728-
4 5 2 7 3
4740+
A B C&C D E
4741+
0 1 10 10 11 -9
4742+
1 2 8 9 10 -6
4743+
2 3 6 8 9 -3
4744+
3 4 4 7 8 0
4745+
4 5 2 6 7 3
4746+
4747+
For columns with spaces in their name, you can use backtick quoting.
4748+
4749+
>>> df.eval("B * `C&C`")
4750+
0 100
4751+
1 72
4752+
2 48
4753+
3 28
4754+
4 12
4755+
4756+
Local variables shall be explicitly referenced using ``@``
4757+
character in front of the name:
4758+
4759+
>>> local_var = 2
4760+
>>> df.eval("@local_var * A")
4761+
0 2
4762+
1 4
4763+
2 6
4764+
3 8
4765+
4 10
47294766
"""
47304767
from pandas.core.computation.eval import eval as _eval
47314768

0 commit comments

Comments
 (0)