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