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 import sys
   8 from dataclasses import dataclass, field
   9 from enum import Enum, auto
  10 from hashlib import sha256
  11 from operator import attrgetter
  12 from typing import Dict, Set
  13 from warnings import warn
  14
  15 if sys.version_info < (3, 8):
  16     from typing_extensions import Final
  17 else:
  18     from typing import Final
  19
  20 from black.const import DEFAULT_LINE_LENGTH
  21
  22
  23 class TargetVersion(Enum):
  24     PY33 = 3
  25     PY34 = 4
  26     PY35 = 5
  27     PY36 = 6
  28     PY37 = 7
  29     PY38 = 8
  30     PY39 = 9
  31     PY310 = 10
  32     PY311 = 11
  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     EXCEPT_STAR = 14
  51     VARIADIC_GENERICS = 15
  52     DEBUG_F_STRINGS = 16
  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.DEBUG_F_STRINGS,
  86         Feature.NUMERIC_UNDERSCORES,
  87         Feature.TRAILING_COMMA_IN_CALL,
  88         Feature.TRAILING_COMMA_IN_DEF,
  89         Feature.ASYNC_KEYWORDS,
  90         Feature.FUTURE_ANNOTATIONS,
  91         Feature.ASSIGNMENT_EXPRESSIONS,
  92         Feature.POS_ONLY_ARGUMENTS,
  93         Feature.UNPACKING_ON_FLOW,
  94         Feature.ANN_ASSIGN_EXTENDED_RHS,
  95     },
  96     TargetVersion.PY39: {
  97         Feature.F_STRINGS,
  98         Feature.DEBUG_F_STRINGS,
  99         Feature.NUMERIC_UNDERSCORES,
 100         Feature.TRAILING_COMMA_IN_CALL,
 101         Feature.TRAILING_COMMA_IN_DEF,
 102         Feature.ASYNC_KEYWORDS,
 103         Feature.FUTURE_ANNOTATIONS,
 104         Feature.ASSIGNMENT_EXPRESSIONS,
 105         Feature.RELAXED_DECORATORS,
 106         Feature.POS_ONLY_ARGUMENTS,
 107         Feature.UNPACKING_ON_FLOW,
 108         Feature.ANN_ASSIGN_EXTENDED_RHS,
 109     },
 110     TargetVersion.PY310: {
 111         Feature.F_STRINGS,
 112         Feature.DEBUG_F_STRINGS,
 113         Feature.NUMERIC_UNDERSCORES,
 114         Feature.TRAILING_COMMA_IN_CALL,
 115         Feature.TRAILING_COMMA_IN_DEF,
 116         Feature.ASYNC_KEYWORDS,
 117         Feature.FUTURE_ANNOTATIONS,
 118         Feature.ASSIGNMENT_EXPRESSIONS,
 119         Feature.RELAXED_DECORATORS,
 120         Feature.POS_ONLY_ARGUMENTS,
 121         Feature.UNPACKING_ON_FLOW,
 122         Feature.ANN_ASSIGN_EXTENDED_RHS,
 123         Feature.PATTERN_MATCHING,
 124     },
 125     TargetVersion.PY311: {
 126         Feature.F_STRINGS,
 127         Feature.DEBUG_F_STRINGS,
 128         Feature.NUMERIC_UNDERSCORES,
 129         Feature.TRAILING_COMMA_IN_CALL,
 130         Feature.TRAILING_COMMA_IN_DEF,
 131         Feature.ASYNC_KEYWORDS,
 132         Feature.FUTURE_ANNOTATIONS,
 133         Feature.ASSIGNMENT_EXPRESSIONS,
 134         Feature.RELAXED_DECORATORS,
 135         Feature.POS_ONLY_ARGUMENTS,
 136         Feature.UNPACKING_ON_FLOW,
 137         Feature.ANN_ASSIGN_EXTENDED_RHS,
 138         Feature.PATTERN_MATCHING,
 139         Feature.EXCEPT_STAR,
 140         Feature.VARIADIC_GENERICS,
 141     },
 142 }
 143
 144
 145 def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
 146     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
 147
 148
 149 class Preview(Enum):
 150     """Individual preview style features."""
 151
 152     annotation_parens = auto()
 153     empty_lines_before_class_or_def_with_leading_comments = auto()
 154     handle_trailing_commas_in_head = auto()
 155     long_docstring_quotes_on_newline = auto()
 156     normalize_docstring_quotes_and_prefixes_properly = auto()
 157     one_element_subscript = auto()
 158     prefer_splitting_right_hand_side_of_assignments = auto()
 159     remove_block_trailing_newline = auto()
 160     remove_redundant_parens = auto()
 161     # NOTE: string_processing requires wrap_long_dict_values_in_parens
 162     # for https://github.com/psf/black/issues/3117 to be fixed.
 163     string_processing = auto()
 164     skip_magic_trailing_comma_in_subscript = auto()
 165     wrap_long_dict_values_in_parens = auto()
 166
 167
 168 class Deprecated(UserWarning):
 169     """Visible deprecation warning."""
 170
 171
 172 @dataclass
 173 class Mode:
 174     target_versions: Set[TargetVersion] = field(default_factory=set)
 175     line_length: int = DEFAULT_LINE_LENGTH
 176     string_normalization: bool = True
 177     is_pyi: bool = False
 178     is_ipynb: bool = False
 179     skip_source_first_line: bool = False
 180     magic_trailing_comma: bool = True
 181     experimental_string_processing: bool = False
 182     python_cell_magics: Set[str] = field(default_factory=set)
 183     preview: bool = False
 184
 185     def __post_init__(self) -> None:
 186         if self.experimental_string_processing:
 187             warn(
 188                 (
 189                     "`experimental string processing` has been included in `preview`"
 190                     " and deprecated. Use `preview` instead."
 191                 ),
 192                 Deprecated,
 193             )
 194
 195     def __contains__(self, feature: Preview) -> bool:
 196         """
 197         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
 198
 199         The argument is not checked and features are not differentiated.
 200         They only exist to make development easier by clarifying intent.
 201         """
 202         if feature is Preview.string_processing:
 203             return self.preview or self.experimental_string_processing
 204         return self.preview
 205
 206     def get_cache_key(self) -> str:
 207         if self.target_versions:
 208             version_str = ",".join(
 209                 str(version.value)
 210                 for version in sorted(self.target_versions, key=attrgetter("value"))
 211             )
 212         else:
 213             version_str = "-"
 214         parts = [
 215             version_str,
 216             str(self.line_length),
 217             str(int(self.string_normalization)),
 218             str(int(self.is_pyi)),
 219             str(int(self.is_ipynb)),
 220             str(int(self.skip_source_first_line)),
 221             str(int(self.magic_trailing_comma)),
 222             str(int(self.experimental_string_processing)),
 223             str(int(self.preview)),
 224             sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
 225         ]
 226         return ".".join(parts)