src/black/mode.py

   1 """Data structures configuring Black behavior.
   2
   3 Mostly around Python language feature support per version and Black configuration
   4 chosen by the user.
   5 """
   6
   7 from hashlib import sha256
   8 import sys
   9
  10 from dataclasses import dataclass, field
  11 from enum import Enum, auto
  12 from operator import attrgetter
  13 from typing import Dict, Set
  14 from warnings import warn
  15
  16 if sys.version_info < (3, 8):
  17     from typing_extensions import Final
  18 else:
  19     from typing import Final
  20
  21 from black.const import DEFAULT_LINE_LENGTH
  22
  23
  24 class TargetVersion(Enum):
  25     PY33 = 3
  26     PY34 = 4
  27     PY35 = 5
  28     PY36 = 6
  29     PY37 = 7
  30     PY38 = 8
  31     PY39 = 9
  32     PY310 = 10
  33
  34
  35 class Feature(Enum):
  36     F_STRINGS = 2
  37     NUMERIC_UNDERSCORES = 3
  38     TRAILING_COMMA_IN_CALL = 4
  39     TRAILING_COMMA_IN_DEF = 5
  40     # The following two feature-flags are mutually exclusive, and exactly one should be
  41     # set for every version of python.
  42     ASYNC_IDENTIFIERS = 6
  43     ASYNC_KEYWORDS = 7
  44     ASSIGNMENT_EXPRESSIONS = 8
  45     POS_ONLY_ARGUMENTS = 9
  46     RELAXED_DECORATORS = 10
  47     PATTERN_MATCHING = 11
  48     UNPACKING_ON_FLOW = 12
  49     ANN_ASSIGN_EXTENDED_RHS = 13
  50     FORCE_OPTIONAL_PARENTHESES = 50
  51
  52     # __future__ flags
  53     FUTURE_ANNOTATIONS = 51
  54
  55
  56 FUTURE_FLAG_TO_FEATURE: Final = {
  57     "annotations": Feature.FUTURE_ANNOTATIONS,
  58 }
  59
  60
  61 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
  62     TargetVersion.PY33: {Feature.ASYNC_IDENTIFIERS},
  63     TargetVersion.PY34: {Feature.ASYNC_IDENTIFIERS},
  64     TargetVersion.PY35: {Feature.TRAILING_COMMA_IN_CALL, Feature.ASYNC_IDENTIFIERS},
  65     TargetVersion.PY36: {
  66         Feature.F_STRINGS,
  67         Feature.NUMERIC_UNDERSCORES,
  68         Feature.TRAILING_COMMA_IN_CALL,
  69         Feature.TRAILING_COMMA_IN_DEF,
  70         Feature.ASYNC_IDENTIFIERS,
  71     },
  72     TargetVersion.PY37: {
  73         Feature.F_STRINGS,
  74         Feature.NUMERIC_UNDERSCORES,
  75         Feature.TRAILING_COMMA_IN_CALL,
  76         Feature.TRAILING_COMMA_IN_DEF,
  77         Feature.ASYNC_KEYWORDS,
  78         Feature.FUTURE_ANNOTATIONS,
  79     },
  80     TargetVersion.PY38: {
  81         Feature.F_STRINGS,
  82         Feature.NUMERIC_UNDERSCORES,
  83         Feature.TRAILING_COMMA_IN_CALL,
  84         Feature.TRAILING_COMMA_IN_DEF,
  85         Feature.ASYNC_KEYWORDS,
  86         Feature.FUTURE_ANNOTATIONS,
  87         Feature.ASSIGNMENT_EXPRESSIONS,
  88         Feature.POS_ONLY_ARGUMENTS,
  89         Feature.UNPACKING_ON_FLOW,
  90         Feature.ANN_ASSIGN_EXTENDED_RHS,
  91     },
  92     TargetVersion.PY39: {
  93         Feature.F_STRINGS,
  94         Feature.NUMERIC_UNDERSCORES,
  95         Feature.TRAILING_COMMA_IN_CALL,
  96         Feature.TRAILING_COMMA_IN_DEF,
  97         Feature.ASYNC_KEYWORDS,
  98         Feature.FUTURE_ANNOTATIONS,
  99         Feature.ASSIGNMENT_EXPRESSIONS,
 100         Feature.RELAXED_DECORATORS,
 101         Feature.POS_ONLY_ARGUMENTS,
 102         Feature.UNPACKING_ON_FLOW,
 103         Feature.ANN_ASSIGN_EXTENDED_RHS,
 104     },
 105     TargetVersion.PY310: {
 106         Feature.F_STRINGS,
 107         Feature.NUMERIC_UNDERSCORES,
 108         Feature.TRAILING_COMMA_IN_CALL,
 109         Feature.TRAILING_COMMA_IN_DEF,
 110         Feature.ASYNC_KEYWORDS,
 111         Feature.FUTURE_ANNOTATIONS,
 112         Feature.ASSIGNMENT_EXPRESSIONS,
 113         Feature.RELAXED_DECORATORS,
 114         Feature.POS_ONLY_ARGUMENTS,
 115         Feature.UNPACKING_ON_FLOW,
 116         Feature.ANN_ASSIGN_EXTENDED_RHS,
 117         Feature.PATTERN_MATCHING,
 118     },
 119 }
 120
 121
 122 def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
 123     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
 124
 125
 126 class Preview(Enum):
 127     """Individual preview style features."""
 128
 129     string_processing = auto()
 130     remove_redundant_parens = auto()
 131     one_element_subscript = auto()
 132     annotation_parens = auto()
 133
 134
 135 class Deprecated(UserWarning):
 136     """Visible deprecation warning."""
 137
 138
 139 @dataclass
 140 class Mode:
 141     target_versions: Set[TargetVersion] = field(default_factory=set)
 142     line_length: int = DEFAULT_LINE_LENGTH
 143     string_normalization: bool = True
 144     is_pyi: bool = False
 145     is_ipynb: bool = False
 146     magic_trailing_comma: bool = True
 147     experimental_string_processing: bool = False
 148     python_cell_magics: Set[str] = field(default_factory=set)
 149     preview: bool = False
 150
 151     def __post_init__(self) -> None:
 152         if self.experimental_string_processing:
 153             warn(
 154                 "`experimental string processing` has been included in `preview`"
 155                 " and deprecated. Use `preview` instead.",
 156                 Deprecated,
 157             )
 158
 159     def __contains__(self, feature: Preview) -> bool:
 160         """
 161         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
 162
 163         The argument is not checked and features are not differentiated.
 164         They only exist to make development easier by clarifying intent.
 165         """
 166         if feature is Preview.string_processing:
 167             return self.preview or self.experimental_string_processing
 168         return self.preview
 169
 170     def get_cache_key(self) -> str:
 171         if self.target_versions:
 172             version_str = ",".join(
 173                 str(version.value)
 174                 for version in sorted(self.target_versions, key=attrgetter("value"))
 175             )
 176         else:
 177             version_str = "-"
 178         parts = [
 179             version_str,
 180             str(self.line_length),
 181             str(int(self.string_normalization)),
 182             str(int(self.is_pyi)),
 183             str(int(self.is_ipynb)),
 184             str(int(self.magic_trailing_comma)),
 185             str(int(self.experimental_string_processing)),
 186             str(int(self.preview)),
 187             sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
 188         ]
 189         return ".".join(parts)