Add function annotations and explained edge case in documentation

Author: hwalinga

pandas/core/computation/expr.py

@@ -7,7 +7,7 @@
 import itertools as it
 import token
 import tokenize
-from typing import Type
+from typing import Any, Generator, Tuple, Type
 
 import numpy as np
 
@@ -39,8 +39,10 @@
 
 import pandas.io.formats.printing as printing
 
+Tok = Tuple[int, str]
 
-def tokenize_backtick_quoted_string(token_generator):
+
+def tokenize_backtick_quoted_string(token_generator) -> Tok:
     """Creates a token from a backtick quoted string.
     Moves the token_generator forwards till right after the next backtick."""
     prev_toknum = token.OP  # This will trigger the first token to have no space
@@ -58,7 +60,7 @@ def tokenize_backtick_quoted_string(token_generator):
     return _BACKTICK_QUOTED_STRING, new_tokval
 
 
-def tokenize_string(source):
+def tokenize_string(source: str) -> Generator[Tok, None, None]:
     """
     Tokenize a Python source code string.
 

pandas/core/frame.py

@@ -3142,12 +3142,17 @@ def query(self, expr, inplace=False, **kwargs):
             names that start with a digit, or are a Python keyword. Basically
             when it is not valid Python identifier.
 
-            NB. You cannot use this if there are multiple invalid characters
-            next to each other, like `very*=invalid`.
-
             For example, if one of your columns is called ``a a`` and you want
             to sum it with ``b``, your query should be ```a a` + b``.
 
+            NB. A combination of an invalid character with a space, or
+            multiple spaces will collapse the space. The reason is that the
+            string will be parsed as Python code
+            and in Python ``a*b`` and ``a* b`` are equal.
+            So, if you want to refer to a column called ``"a* b"`` you
+            can use ```a*b```, but it is recommend in this case to change the
+            column name or use bracket notation, to prevent very opaque code.
+
         inplace : bool
             Whether the query should modify the data in place or return
             a modified copy.