NotImplementedError + doc string

Author: topper-123

doc/source/user_guide/indexing.rst

@@ -576,23 +576,24 @@ row/columns axis labels that match a regular expression pattern.
 
 .. ipython:: python
 
-    df = pd.DataFrame(1, index=["A", "AB", "BC"], columns=["BC", "AB", "A"])
-    df
+    df_re = pd.DataFrame(1, index=["A", "AB", "BC"], columns=["BC", "AB", "A"])
+    df_re
 
-    df.loc(regex=True)["B", "B"]
-    df.loc(axis=1, regex=True)["B"]
+    df_re.loc(regex=True)["B", "B"]
+    df_re.loc(axis=1, regex=True)["B"]
 
 The regex matching will only work when looking up single strings, not list of strings etc.
 
 .. ipython:: python
 
-    df.loc(regex=True)[["A"], "A"]
+    df_re.loc(regex=True)[["A"], "A"]
 
 *Notice*: Is is currently not possible to set values for a given regular expression.
 
 .. ipython:: python
+    :okexcept:
 
-    df.loc(regex=True)["B", "B"] = [[1, 2], [3, 4]]
+    df_re.loc(regex=True)["B", "B"] = [[1, 2], [3, 4]]
 
 
 .. _indexing.deprecate_ix:

doc/source/whatsnew/v0.25.0.rst

@@ -207,6 +207,7 @@ The regex matching will only work when looking up single strings, not list of st
 Is is currently not possible to set values for a given regular expression.
 
 .. ipython:: python
+    :okexcept:
 
     df.loc(regex=True)["B", "B"] = [[1, 2], [3, 4]]
 

pandas/core/indexing.py

@@ -1,3 +1,4 @@
+import re
 import textwrap
 from typing import Tuple
 import warnings
@@ -1471,6 +1472,12 @@ class _LocIndexer(_LocationIndexer):
     - A ``callable`` function with one argument (the calling Series or
       DataFrame) and that returns valid output for indexing (one of the above)
 
+    ``.loc`` can be called before selecting using parameters:
+
+    - ``axis``, to select by a single axis on a DataFrame, e.g. ``.loc(axis=1)['a']``.
+    - ``regex``, to let strings be interpreted as regex patterns, e.g.
+      ``.loc(regex=True)[:, '^col_']``
+
     See more at :ref:`Selection by Label <indexing.label>`
 
     Raises
@@ -1550,6 +1557,21 @@ class _LocIndexer(_LocationIndexer):
                 max_speed  shield
     sidewinder          7       8
 
+    The axis may be preselected
+
+    >>> df.loc(axis=1)["max_speed"]
+    cobra         1
+    viper         4
+    sidewinder    7
+    Name: max_speed, dtype: int64
+
+    Single strings are considered regex patterns if ``regex=True``
+
+    >>> df.loc(regex=True)["r$", "d$"]
+                max_speed  shield
+    viper               4       5
+    sidewinder          7       8
+
     **Setting values**
 
     Set value for all items matching the list of labels
@@ -1768,7 +1790,6 @@ def _get_partial_string_timestamp_match_key(self, key, labels):
         return key
 
     def _get_regex_mappings(self, key, axis=None):
-        import re
 
         if axis is None:
             axis = self.axis or 0
@@ -1849,7 +1870,7 @@ def _getitem_axis(self, key, axis: int):
                 indexer[axis] = locs
                 return self.obj.iloc[tuple(indexer)]
 
-        if self.regex and isinstance(key, str):
+        if self.regex and isinstance(key, (str, bytes)):
             return self._getitem_regex(key, axis=axis)
 
         # fall thru to straight lookup
@@ -1861,7 +1882,7 @@ def _getitem_lower_dim(self, section, key):
 
     def __setitem__(self, key, value):
         if self.regex:
-            raise TypeError("Inserting with regex not supported")
+            raise NotImplementedError("Inserting with regex has not been implemented")
         return super().__setitem__(key, value)
 
 

pandas/tests/indexing/test_loc.py

@@ -69,7 +69,8 @@ def test_regex_inserting(self):
 
         df = pd.DataFrame(1, index=idx, columns=cols)
 
-        with pytest.raises(TypeError, match="Inserting with regex not supported"):
+        msg = "Inserting with regex has not been implemented"
+        with pytest.raises(NotImplementedError, match=msg):
             df.loc(regex=True)["B", "B"] = [[2, 2], [2, 2]]