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