]> git.madduck.net Git - etc/vim.git/blob - src/black/mode.py

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

a57fa373568dcb0c8ede83db0a87486b2cf3e33f
[etc/vim.git] / 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 dataclasses import dataclass, field
8 from enum import Enum, auto
9 from hashlib import sha256
10 from operator import attrgetter
11 from typing import Dict, Final, Set
12 from warnings import warn
13
14 from black.const import DEFAULT_LINE_LENGTH
15
16
17 class TargetVersion(Enum):
18     PY33 = 3
19     PY34 = 4
20     PY35 = 5
21     PY36 = 6
22     PY37 = 7
23     PY38 = 8
24     PY39 = 9
25     PY310 = 10
26     PY311 = 11
27     PY312 = 12
28
29
30 class Feature(Enum):
31     F_STRINGS = 2
32     NUMERIC_UNDERSCORES = 3
33     TRAILING_COMMA_IN_CALL = 4
34     TRAILING_COMMA_IN_DEF = 5
35     # The following two feature-flags are mutually exclusive, and exactly one should be
36     # set for every version of python.
37     ASYNC_IDENTIFIERS = 6
38     ASYNC_KEYWORDS = 7
39     ASSIGNMENT_EXPRESSIONS = 8
40     POS_ONLY_ARGUMENTS = 9
41     RELAXED_DECORATORS = 10
42     PATTERN_MATCHING = 11
43     UNPACKING_ON_FLOW = 12
44     ANN_ASSIGN_EXTENDED_RHS = 13
45     EXCEPT_STAR = 14
46     VARIADIC_GENERICS = 15
47     DEBUG_F_STRINGS = 16
48     PARENTHESIZED_CONTEXT_MANAGERS = 17
49     TYPE_PARAMS = 18
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.DEBUG_F_STRINGS,
83         Feature.NUMERIC_UNDERSCORES,
84         Feature.TRAILING_COMMA_IN_CALL,
85         Feature.TRAILING_COMMA_IN_DEF,
86         Feature.ASYNC_KEYWORDS,
87         Feature.FUTURE_ANNOTATIONS,
88         Feature.ASSIGNMENT_EXPRESSIONS,
89         Feature.POS_ONLY_ARGUMENTS,
90         Feature.UNPACKING_ON_FLOW,
91         Feature.ANN_ASSIGN_EXTENDED_RHS,
92     },
93     TargetVersion.PY39: {
94         Feature.F_STRINGS,
95         Feature.DEBUG_F_STRINGS,
96         Feature.NUMERIC_UNDERSCORES,
97         Feature.TRAILING_COMMA_IN_CALL,
98         Feature.TRAILING_COMMA_IN_DEF,
99         Feature.ASYNC_KEYWORDS,
100         Feature.FUTURE_ANNOTATIONS,
101         Feature.ASSIGNMENT_EXPRESSIONS,
102         Feature.RELAXED_DECORATORS,
103         Feature.POS_ONLY_ARGUMENTS,
104         Feature.UNPACKING_ON_FLOW,
105         Feature.ANN_ASSIGN_EXTENDED_RHS,
106         Feature.PARENTHESIZED_CONTEXT_MANAGERS,
107     },
108     TargetVersion.PY310: {
109         Feature.F_STRINGS,
110         Feature.DEBUG_F_STRINGS,
111         Feature.NUMERIC_UNDERSCORES,
112         Feature.TRAILING_COMMA_IN_CALL,
113         Feature.TRAILING_COMMA_IN_DEF,
114         Feature.ASYNC_KEYWORDS,
115         Feature.FUTURE_ANNOTATIONS,
116         Feature.ASSIGNMENT_EXPRESSIONS,
117         Feature.RELAXED_DECORATORS,
118         Feature.POS_ONLY_ARGUMENTS,
119         Feature.UNPACKING_ON_FLOW,
120         Feature.ANN_ASSIGN_EXTENDED_RHS,
121         Feature.PARENTHESIZED_CONTEXT_MANAGERS,
122         Feature.PATTERN_MATCHING,
123     },
124     TargetVersion.PY311: {
125         Feature.F_STRINGS,
126         Feature.DEBUG_F_STRINGS,
127         Feature.NUMERIC_UNDERSCORES,
128         Feature.TRAILING_COMMA_IN_CALL,
129         Feature.TRAILING_COMMA_IN_DEF,
130         Feature.ASYNC_KEYWORDS,
131         Feature.FUTURE_ANNOTATIONS,
132         Feature.ASSIGNMENT_EXPRESSIONS,
133         Feature.RELAXED_DECORATORS,
134         Feature.POS_ONLY_ARGUMENTS,
135         Feature.UNPACKING_ON_FLOW,
136         Feature.ANN_ASSIGN_EXTENDED_RHS,
137         Feature.PARENTHESIZED_CONTEXT_MANAGERS,
138         Feature.PATTERN_MATCHING,
139         Feature.EXCEPT_STAR,
140         Feature.VARIADIC_GENERICS,
141     },
142     TargetVersion.PY312: {
143         Feature.F_STRINGS,
144         Feature.DEBUG_F_STRINGS,
145         Feature.NUMERIC_UNDERSCORES,
146         Feature.TRAILING_COMMA_IN_CALL,
147         Feature.TRAILING_COMMA_IN_DEF,
148         Feature.ASYNC_KEYWORDS,
149         Feature.FUTURE_ANNOTATIONS,
150         Feature.ASSIGNMENT_EXPRESSIONS,
151         Feature.RELAXED_DECORATORS,
152         Feature.POS_ONLY_ARGUMENTS,
153         Feature.UNPACKING_ON_FLOW,
154         Feature.ANN_ASSIGN_EXTENDED_RHS,
155         Feature.PARENTHESIZED_CONTEXT_MANAGERS,
156         Feature.PATTERN_MATCHING,
157         Feature.EXCEPT_STAR,
158         Feature.VARIADIC_GENERICS,
159         Feature.TYPE_PARAMS,
160     },
161 }
162
163
164 def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
165     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
166
167
168 class Preview(Enum):
169     """Individual preview style features."""
170
171     add_trailing_comma_consistently = auto()
172     blank_line_after_nested_stub_class = auto()
173     blank_line_between_nested_and_def_stub_file = auto()
174     hex_codes_in_unicode_sequences = auto()
175     improved_async_statements_handling = auto()
176     multiline_string_handling = auto()
177     no_blank_line_before_class_docstring = auto()
178     prefer_splitting_right_hand_side_of_assignments = auto()
179     # NOTE: string_processing requires wrap_long_dict_values_in_parens
180     # for https://github.com/psf/black/issues/3117 to be fixed.
181     string_processing = auto()
182     parenthesize_conditional_expressions = auto()
183     parenthesize_long_type_hints = auto()
184     respect_magic_trailing_comma_in_return_type = auto()
185     skip_magic_trailing_comma_in_subscript = auto()
186     wrap_long_dict_values_in_parens = auto()
187     wrap_multiple_context_managers_in_parens = auto()
188     dummy_implementations = auto()
189     walrus_subscript = auto()
190     module_docstring_newlines = auto()
191     fix_power_op_line_length = auto()
192
193
194 class Deprecated(UserWarning):
195     """Visible deprecation warning."""
196
197
198 @dataclass
199 class Mode:
200     target_versions: Set[TargetVersion] = field(default_factory=set)
201     line_length: int = DEFAULT_LINE_LENGTH
202     string_normalization: bool = True
203     is_pyi: bool = False
204     is_ipynb: bool = False
205     skip_source_first_line: bool = False
206     magic_trailing_comma: bool = True
207     experimental_string_processing: bool = False
208     python_cell_magics: Set[str] = field(default_factory=set)
209     preview: bool = False
210
211     def __post_init__(self) -> None:
212         if self.experimental_string_processing:
213             warn(
214                 "`experimental string processing` has been included in `preview`"
215                 " and deprecated. Use `preview` instead.",
216                 Deprecated,
217             )
218
219     def __contains__(self, feature: Preview) -> bool:
220         """
221         Provide `Preview.FEATURE in Mode` syntax that mirrors the ``preview`` flag.
222
223         The argument is not checked and features are not differentiated.
224         They only exist to make development easier by clarifying intent.
225         """
226         if feature is Preview.string_processing:
227             return self.preview or self.experimental_string_processing
228         return self.preview
229
230     def get_cache_key(self) -> str:
231         if self.target_versions:
232             version_str = ",".join(
233                 str(version.value)
234                 for version in sorted(self.target_versions, key=attrgetter("value"))
235             )
236         else:
237             version_str = "-"
238         parts = [
239             version_str,
240             str(self.line_length),
241             str(int(self.string_normalization)),
242             str(int(self.is_pyi)),
243             str(int(self.is_ipynb)),
244             str(int(self.skip_source_first_line)),
245             str(int(self.magic_trailing_comma)),
246             str(int(self.experimental_string_processing)),
247             str(int(self.preview)),
248             sha256((",".join(sorted(self.python_cell_magics))).encode()).hexdigest(),
249         ]
250         return ".".join(parts)