Improve tests and docs, also resolve linting

docs/the_black_code_style/current_style.md

@@ -285,10 +285,24 @@ multiple lines. This is so that _Black_ is compliant with the recent changes in
 style guide, which emphasizes that this approach improves readability.
 
 Almost all operators will be surrounded by single spaces, the only exceptions are unary
-operators (`+`, `-`, and `~`), and power operators when both operands are simple.
-For power ops, an operand is considered simple if it's only a NAME, numeric
-CONSTANT, or attribute access (chained attribute access is allowed), with or without a
-preceding unary operator.
+operators (`+`, `-`, and `~`), and power operators when both operands are simple. For
+powers, an operand is considered simple if it's only a NAME, numeric CONSTANT, or
+attribute access (chained attribute access is allowed), with or without a preceding
+unary operator.
+
+```python
+# For example, these won't be surrounded by whitespace
+a = x**y
+b = config.base**5.2
+c = config.base**runtime.config.exponent
+d = 2**5
+e = 2**~5
+
+# ... but these will be surrounded by whitespace
+f = 2 ** get_exponent()
+g = get_x() ** get_y()
+h = config['base'] ** 2
+```
 
 ### Slices
 

src/black/linegen.py

@@ -21,13 +21,8 @@
 from black.numerics import normalize_numeric_literal
 from black.strings import get_string_prefix, fix_docstring
 from black.strings import normalize_string_prefix, normalize_string_quotes
-from black.trans import Transformer, CannotTransform, StringMerger
-from black.trans import (
-    StringSplitter,
-    StringParenWrapper,
-    StringParenStripper,
-    hug_power_op,
-)
+from black.trans import Transformer, CannotTransform, StringMerger, StringSplitter
+from black.trans import StringParenWrapper, StringParenStripper, hug_power_op
 from black.mode import Mode, Feature, Preview
 
 from blib2to3.pytree import Node, Leaf
@@ -343,9 +338,9 @@ def transform_line(
     ):
         # Only apply basic string preprocessing, since lines shouldn't be split here.
         if Preview.string_processing in mode:
-            transformers = [string_merge, string_paren_strip, hug_power_op]
+            transformers = [string_merge, string_paren_strip]
         else:
-            transformers = [hug_power_op]
+            transformers = []
     elif line.is_def:
         transformers = [left_hand_split]
     else:
@@ -395,7 +390,6 @@ def _rhs(
                     standalone_comment_split,
                     string_paren_wrap,
                     rhs,
-                    hug_power_op,
                 ]
             else:
                 transformers = [
@@ -404,18 +398,15 @@ def _rhs(
                     string_split,
                     string_paren_wrap,
                     rhs,
-                    hug_power_op,
                 ]
         else:
             if line.inside_brackets:
-                transformers = [
-                    delimiter_split,
-                    standalone_comment_split,
-                    rhs,
-                    hug_power_op,
-                ]
+                transformers = [delimiter_split, standalone_comment_split, rhs]
             else:
-                transformers = [rhs, hug_power_op]
+                transformers = [rhs]
+    # It's always safe to attempt hugging of power operations and pretty much every line
+    # could match.
+    transformers.append(hug_power_op)
 
     for transform in transformers:
         # We are accumulating lines in `result` because we might want to abort

src/black/trans.py

@@ -82,7 +82,7 @@ def hug_power_op(line: Line, features: Collection[Feature]) -> Iterator[Line]:
         raise CannotTransform("No doublestar token was found in the line.")
 
     def is_simple_lookup(index: int, step: Literal[1, -1]) -> bool:
-        # Brackets and parenthesises indicate calls, subscripts, etc. ...
+        # Brackets and parentheses indicate calls, subscripts, etc. ...
         # basically stuff that doesn't count as "simple". Only a NAME lookup
         # or dotted lookup (eg. NAME.NAME) is OK.
         if step == -1:

tests/data/power_op_spacing.py

@@ -28,6 +28,25 @@ def function_dont_replace_spaces():
 o = settings(max_examples=10**6)
 p = {(k, k**2): v**2 for k, v in pairs}
 q = [10**i for i in range(6)]
+r = x**y
+
+a = 5.0**~4.0
+b = 5.0 ** f()
+c = -(5.0**2.0)
+d = 5.0 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5.0
+g = a.b**c.d
+h = 5.0 ** funcs.f()
+i = funcs.f() ** 5.0
+j = super().name ** 5.0
+k = [(2.0**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2.0**63.0], [1.0, 2**63.0])]
+n = count <= 10**5.0
+o = settings(max_examples=10**6.0)
+p = {(k, k**2): v**2.0 for k, v in pairs}
+q = [10.5**i for i in range(6)]
 
 
 # output
@@ -63,3 +82,22 @@ def function_dont_replace_spaces():
 o = settings(max_examples=10**6)
 p = {(k, k**2): v**2 for k, v in pairs}
 q = [10**i for i in range(6)]
+r = x**y
+
+a = 5.0**~4.0
+b = 5.0 ** f()
+c = -(5.0**2.0)
+d = 5.0 ** f["hi"]
+e = lazy(lambda **kwargs: 5)
+f = f() ** 5.0
+g = a.b**c.d
+h = 5.0 ** funcs.f()
+i = funcs.f() ** 5.0
+j = super().name ** 5.0
+k = [(2.0**idx, value) for idx, value in pairs]
+l = mod.weights_[0] == pytest.approx(0.95**100, abs=0.001)
+m = [([2.0**63.0], [1.0, 2**63.0])]
+n = count <= 10**5.0
+o = settings(max_examples=10**6.0)
+p = {(k, k**2): v**2.0 for k, v in pairs}
+q = [10.5**i for i in range(6)]