NotImplementedError + doc string

Author: topper-123

pandas/core/indexing.py

@@ -1474,6 +1474,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
@@ -1553,6 +1559,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
@@ -1867,7 +1888,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]]