brash 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
brash/__init__.py ADDED
@@ -0,0 +1,82 @@
1
+ """brash: codemods that hold a Python codebase to its conventions, applied to files or checked against them.
2
+
3
+ `brash PATHS` rewrites the Python under the paths with every codemod there is, brash's own in `registry.CODEMODS`
4
+ and those the project registers in its `pyproject.toml`, and `--check` changes nothing: it prints the diff each
5
+ would make and fails when there is one, which is how a lint holds a repository to them. A codemod is a
6
+ `libcst.codemod` command, so it keeps every comment and blank line it does not touch. The README says how to add one.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from pathlib import Path
12
+ from typing import TYPE_CHECKING
13
+
14
+ import click
15
+
16
+ from brash import registry, run
17
+
18
+ if TYPE_CHECKING:
19
+ from collections.abc import Iterable
20
+
21
+ from brash.command import Command
22
+
23
+
24
+ @click.command()
25
+ @click.argument("paths", nargs=-1, type=click.Path(exists=True, path_type=Path))
26
+ @click.option("--check", is_flag=True, help="Change nothing: print the diff, and fail when there is one.")
27
+ @click.option(
28
+ "--only",
29
+ "names",
30
+ multiple=True,
31
+ metavar="NAME",
32
+ help="Run this codemod alone; give it again for each. By default, all of them.",
33
+ )
34
+ @click.option("--list", "listing", is_flag=True, help="List the codemods and exit.")
35
+ def main(*, paths: tuple[Path, ...], check: bool, names: tuple[str, ...], listing: bool) -> None:
36
+ """Rewrite the Python under PATHS, files or directories, with every codemod."""
37
+ codemods = _registered(names)
38
+ if listing:
39
+ for name, codemod in codemods.items():
40
+ click.echo(f"{name} {codemod.DESCRIPTION}")
41
+ return
42
+ if not paths:
43
+ raise click.UsageError("Give the files or directories to rewrite.")
44
+ rewrites = run.rewrite_all(paths, [name for name in codemods if not names or name in names], codemods)
45
+ failed = [rewrite for rewrite in rewrites if rewrite.error is not None]
46
+ changed = [rewrite for rewrite in rewrites if rewrite.changed]
47
+ for rewrite in failed:
48
+ click.echo(f"{rewrite.path}: {rewrite.error}", err=True)
49
+ for rewrite in changed:
50
+ if check:
51
+ click.echo(rewrite.diff(), nl=False)
52
+ else:
53
+ rewrite.path.write_text(rewrite.after, encoding="utf-8")
54
+ click.echo(f"Rewrote {rewrite.path}")
55
+ if failed:
56
+ raise click.ClickException(f"{_files(len(failed))} could not be rewritten")
57
+ if check and changed:
58
+ raise click.ClickException(f"{_files(len(changed))} would be rewritten; run `brash` without `--check`")
59
+
60
+
61
+ def _registered(names: Iterable[str]) -> dict[str, type[Command]]:
62
+ """Every codemod this run has, brash's own and the project's, once `--only` is known to name some of them.
63
+
64
+ Returns:
65
+ Each codemod by name, in the order they run on a file.
66
+
67
+ Raises:
68
+ click.ClickException: When the project registers a codemod that cannot be loaded.
69
+ click.BadParameter: When `--only` names no codemod.
70
+ """
71
+ try:
72
+ codemods = registry.registered(Path.cwd())
73
+ except registry.RegistryError as e:
74
+ raise click.ClickException(str(e)) from e
75
+ for name in names:
76
+ if name not in codemods:
77
+ raise click.BadParameter(f"{name!r} is not one of {', '.join(map(repr, codemods))}.", param_hint="'--only'")
78
+ return codemods
79
+
80
+
81
+ def _files(count: int) -> str:
82
+ return "1 file" if count == 1 else f"{count} files"
brash/command.py ADDED
@@ -0,0 +1,35 @@
1
+ """What every codemod is: a `libcst.codemod` command that can say cheaply when a file is not its concern."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from libcst.codemod import VisitorBasedCodemodCommand
6
+
7
+
8
+ class Command(VisitorBasedCodemodCommand):
9
+ """A codemod: its `visit_` and `leave_` methods rewrite a module, or `transform_module_impl` does it whole.
10
+
11
+ Parsing a module with libcst and visiting it takes a few hundred times as long as reading it, and the lint runs
12
+ every codemod over every file. So a codemod that can tell from a module's text that it has nothing to do there
13
+ says so in `wants`, and the file is never parsed.
14
+ """
15
+
16
+ @classmethod
17
+ def covers(cls, filename: str | None) -> bool: # noqa: ARG003
18
+ """Whether the codemod holds a file at this path to it at all, before its text is read for `wants`.
19
+
20
+ Args:
21
+ filename: The file's path, or None for text with no file, which every codemod covers.
22
+
23
+ Returns:
24
+ True unless the file is outside what the codemod is for. Always True here.
25
+ """
26
+ return True
27
+
28
+ @classmethod
29
+ def wants(cls, source: str) -> bool: # noqa: ARG003
30
+ """Whether the codemod might change a module with this text.
31
+
32
+ Returns:
33
+ True unless it is sure to leave the module as it is. Always True here.
34
+ """
35
+ return True
brash/doc_comments.py ADDED
@@ -0,0 +1,173 @@
1
+ """Write the comment above a constant or a field as a Sphinx doc comment, `#:`, which editors and tools attach to it.
2
+
3
+ The comment is the block of whole-line comments directly above the name, with no blank line between:
4
+
5
+ # How many times a run is resumed before it is given up.
6
+ MAX_RESUMES: Final = 3
7
+
8
+ becomes
9
+
10
+ #: How many times a run is resumed before it is given up.
11
+ MAX_RESUMES: Final = 3
12
+
13
+ The names are a module's constants and type aliases, among its own statements, and the fields of a `@dataclass`, a
14
+ `NamedTuple`, or an enum, its members among them.
15
+
16
+ It leaves alone:
17
+
18
+ - a field of any other class. A pydantic model's description is the docstring below the field, or its `Field`, and
19
+ never a comment, so a `#` above one is a note kept out of the schema on purpose;
20
+ - a comment above anything else: a function, a statement inside one, an import, a lowercase module object such as a
21
+ logger;
22
+ - a block with a `#:` line in it already, a directive to a tool (`# noqa`, `# type:`, `# fmt:`), or a section's
23
+ banner (`# ---- Limits ----`);
24
+ - a comment a blank line separates from the name.
25
+
26
+ A comment is not syntax, so which lines to rewrite is decided from the stdlib's syntax tree and the module's text, and
27
+ a module with none is never parsed by libcst (`Command.wants`).
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import ast
33
+ import re
34
+ from typing import TYPE_CHECKING, Final, override
35
+
36
+ import libcst as cst
37
+
38
+ from brash.command import Command
39
+ from brash.final_constants import last_name
40
+
41
+ if TYPE_CHECKING:
42
+ from collections.abc import Iterator, Sequence
43
+
44
+ #: A module's name that is no lowercase object: a constant, `LIMIT`, or a type alias or type variable, `Outcome`.
45
+ NAMED: Final = re.compile(r"_*[A-Z]\w*")
46
+ #: The base classes that make a class an enum, by their last names.
47
+ ENUMS: Final = frozenset({"Enum", "Flag", "IntEnum", "IntFlag", "ReprEnum", "StrEnum"})
48
+ #: A comment line that keeps its whole block as it is: a doc comment already, a shebang, or a directive to a tool.
49
+ _KEPT: Final = re.compile(
50
+ r"#(?:[:!]|\s*(?:noqa|type|pyrefly|pyright|mypy|fmt|ruff|isort|pragma|pylint|coding)\b\s*:|\s*noqa\b)",
51
+ )
52
+ #: A section's banner: a comment that opens or closes with a rule, such as `# ---- Limits ----` or `# ====`.
53
+ _BANNER: Final = re.compile(r"#\s*(?:[-=#*~_]{3,}.*|.*[-=#*~_]{3,}\s*$)")
54
+
55
+
56
+ class DocComments(Command):
57
+ """Write the comment above a constant or a field as a doc comment, `#:`."""
58
+
59
+ DESCRIPTION = "Write the comment above a constant, a dataclass or NamedTuple field, or an enum member as `#:`."
60
+
61
+ @classmethod
62
+ @override
63
+ def wants(cls, source: str) -> bool:
64
+ """Whether a module with this text has a comment to rewrite.
65
+
66
+ Returns:
67
+ True when it has one, or does not parse, which is then libcst's to report.
68
+ """
69
+ try:
70
+ return bool(comments(source))
71
+ except SyntaxError:
72
+ return True
73
+
74
+ @override
75
+ def transform_module_impl(self, tree: cst.Module) -> cst.Module:
76
+ """Rewrite the module's comments above its constants and fields.
77
+
78
+ Returns:
79
+ The module rewritten, or as it was when it has no such comment.
80
+ """
81
+ source = tree.code
82
+ rewrite = comments(source)
83
+ if not rewrite:
84
+ return tree
85
+ lines = source.split("\n")
86
+ for index in rewrite:
87
+ lines[index] = lines[index].replace("#", "#:", 1)
88
+ return cst.parse_module("\n".join(lines), tree.config_for_parsing)
89
+
90
+
91
+ def comments(source: str) -> frozenset[int]:
92
+ """The comment lines of a module to rewrite as doc comments, from its text.
93
+
94
+ Returns:
95
+ The lines, as indexes into the text split at each newline.
96
+
97
+ Raises:
98
+ SyntaxError: When the text is not Python.
99
+ """
100
+ lines = source.split("\n")
101
+ found: set[int] = set()
102
+ for body, fields in _bodies(ast.parse(source)):
103
+ above = 0
104
+ for statement in body:
105
+ if _named(statement, fields=fields):
106
+ found.update(_block(lines, statement, above))
107
+ above = statement.end_lineno or statement.lineno
108
+ return frozenset(found)
109
+
110
+
111
+ def _bodies(module: ast.Module) -> Iterator[tuple[Sequence[ast.stmt], bool]]:
112
+ """The bodies whose names take a doc comment: the module's own, and each class's whose assignments are fields.
113
+
114
+ Yields:
115
+ A body's statements, and whether they are a class's.
116
+ """
117
+ yield module.body, False
118
+ for node in ast.walk(module):
119
+ if isinstance(node, ast.ClassDef) and _has_fields(node):
120
+ yield node.body, True
121
+
122
+
123
+ def _has_fields(node: ast.ClassDef) -> bool:
124
+ """Whether a class statement says its assignments are fields: a `@dataclass`, a `NamedTuple`, or an enum.
125
+
126
+ Returns:
127
+ True for one of those; False for any other class, a pydantic model among them.
128
+ """
129
+ decorators = (d.func if isinstance(d, ast.Call) else d for d in node.decorator_list)
130
+ return any(last_name(decorator) == "dataclass" for decorator in decorators) or any(
131
+ last_name(base) in ENUMS | {"NamedTuple"} for base in node.bases
132
+ )
133
+
134
+
135
+ def _named(statement: ast.stmt, *, fields: bool) -> bool:
136
+ """Whether a statement binds a name that takes a doc comment.
137
+
138
+ Args:
139
+ statement: A statement of a module's or a class's body.
140
+ fields: Whether the body is a class's, where every name is a field; a module's lowercase name is an object.
141
+
142
+ Returns:
143
+ True for an assignment to one such name, annotated or not, and for a `type` statement.
144
+ """
145
+ match statement:
146
+ case ast.TypeAlias():
147
+ return True
148
+ case ast.Assign(targets=[ast.Name(id=name)]) | ast.AnnAssign(target=ast.Name(id=name)):
149
+ return fields or NAMED.fullmatch(name) is not None
150
+ case _:
151
+ return False
152
+
153
+
154
+ def _block(lines: Sequence[str], statement: ast.stmt, above: int) -> Sequence[int]:
155
+ """The comment block directly above a statement, when it is one to rewrite.
156
+
157
+ Args:
158
+ lines: The module's lines.
159
+ statement: The statement the block is above.
160
+ above: The number of the last line of the statement before it, which the block cannot reach into.
161
+
162
+ Returns:
163
+ The block's lines, as indexes into `lines`; none when a line of it keeps the block as it is.
164
+ """
165
+ block: list[int] = []
166
+ index = statement.lineno - 2
167
+ while index >= above and (comment := lines[index].lstrip()).startswith("#"):
168
+ # A comment indented otherwise belongs to the block it closes, not to this name.
169
+ if len(lines[index]) - len(comment) != statement.col_offset or _KEPT.match(comment) or _BANNER.match(comment):
170
+ return ()
171
+ block.append(index)
172
+ index -= 1
173
+ return block
@@ -0,0 +1,226 @@
1
+ """Annotate every module constant `Final`, so the type checker refuses a second assignment to it.
2
+
3
+ A module constant is a name in `UPPER_CASE` bound once, by an assignment among the module's own statements:
4
+ `LIMIT = 3` becomes `LIMIT: Final = 3`, which keeps the type the checker inferred, and `NAMES: Sequence[str] = ()`
5
+ becomes `NAMES: Final[Sequence[str]] = ()`.
6
+
7
+ It leaves alone what is not a constant, or cannot be `Final`:
8
+
9
+ - a lowercase name, which is how a module spells an object with state of its own (`_log`, `router`);
10
+ - a name the module binds again, by a second assignment, `+=`, `del`, an import, a loop, or a function's `global`;
11
+ - an object made to hold state, whatever its name: a logger, a lock, a context variable (`STATEFUL`);
12
+ - what the type system reads as a declaration, not a value: a `TypeVar` and its kin, and an explicit `TypeAlias`;
13
+ - an assignment to several names at once, and one nested in an `if`, `try`, or `with`.
14
+
15
+ Which names are constants is decided from the stdlib's syntax tree, which is quick to build, so a module with none
16
+ left to annotate is never parsed by libcst (`Command.wants`).
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import ast
22
+ import re
23
+ from collections import Counter
24
+ from collections.abc import Set as AbstractSet
25
+ from typing import Final, override
26
+
27
+ import libcst as cst
28
+ from libcst.codemod.visitors import AddImportsVisitor
29
+
30
+ from brash.command import Command
31
+
32
+ #: A constant's name: upper case, digits, and underscores, after any leading underscores.
33
+ CONSTANT: Final = re.compile(r"_*[A-Z][A-Z0-9_]*")
34
+ #: The calls that make an object whose job is to hold state, by the last name of what is called.
35
+ STATEFUL: Final = frozenset(
36
+ {"BoundedSemaphore", "Condition", "ContextVar", "Event", "Lock", "RLock", "Semaphore", "getLogger", "local"},
37
+ )
38
+ #: The calls that declare a type, which a type checker reads only from a plain assignment.
39
+ DECLARES: Final = frozenset({"NewType", "ParamSpec", "TypeAliasType", "TypeVar", "TypeVarTuple", "namedtuple"})
40
+ #: The annotations a constant keeps as they are: already final, or a declaration of another kind.
41
+ _KEPT: Final = frozenset({"ClassVar", "Final", "TypeAlias"})
42
+
43
+
44
+ class FinalConstants(Command):
45
+ """Annotate every module constant `Final`."""
46
+
47
+ DESCRIPTION = "Annotate every UPPER_CASE module constant `Final`."
48
+
49
+ @classmethod
50
+ @override
51
+ def wants(cls, source: str) -> bool:
52
+ """Whether a module with this text has a constant to annotate.
53
+
54
+ Returns:
55
+ True when it has one, or does not parse, which is then libcst's to report.
56
+ """
57
+ try:
58
+ return bool(constants(source))
59
+ except SyntaxError:
60
+ return True
61
+
62
+ @override
63
+ def transform_module_impl(self, tree: cst.Module) -> cst.Module:
64
+ """Annotate the module's constants, and import `Final` when it annotated any.
65
+
66
+ Returns:
67
+ The module rewritten, or as it was when it has no constant to annotate.
68
+ """
69
+ names = constants(tree.code)
70
+ if not names:
71
+ return tree
72
+ body = [
73
+ statement.with_changes(body=[_final(small, names) for small in statement.body])
74
+ if isinstance(statement, cst.SimpleStatementLine)
75
+ else statement
76
+ for statement in tree.body
77
+ ]
78
+ AddImportsVisitor.add_needed_import(self.context, "typing", "Final")
79
+ return AddImportsVisitor(self.context).transform_module(tree.with_changes(body=body))
80
+
81
+
82
+ def constants(source: str) -> frozenset[str]:
83
+ """The names of a module's constants that are not `Final` yet, from its text.
84
+
85
+ Returns:
86
+ The names, each bound once in the module by the assignment to annotate.
87
+
88
+ Raises:
89
+ SyntaxError: When the text is not Python.
90
+ """
91
+ module = ast.parse(source)
92
+ bindings = Bindings()
93
+ bindings.visit(module)
94
+ return frozenset(
95
+ name for statement in module.body if (name := _candidate(statement)) is not None and bindings.counts[name] == 1
96
+ )
97
+
98
+
99
+ class Bindings(ast.NodeVisitor):
100
+ """Counts how often each name is bound in a module's own scope; a name deleted or declared `global` counts twice."""
101
+
102
+ def __init__(self) -> None:
103
+ """Start with no name bound."""
104
+ #: How often each name is bound.
105
+ self.counts: Counter[str] = Counter()
106
+ #: How many functions, classes, and lambdas enclose the node being visited: 0 in the module's own scope.
107
+ self._depth = 0
108
+
109
+ @override
110
+ def visit_Name(self, node: ast.Name) -> None:
111
+ if not self._depth and not isinstance(node.ctx, ast.Load):
112
+ self.counts[node.id] += 2 if isinstance(node.ctx, ast.Del) else 1
113
+
114
+ @override
115
+ def visit_Global(self, node: ast.Global) -> None:
116
+ self.counts.update(node.names * 2)
117
+
118
+ @override
119
+ def visit_alias(self, node: ast.alias) -> None:
120
+ self._bind(node.asname or node.name.partition(".")[0])
121
+
122
+ @override
123
+ def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
124
+ self._bind(node.name)
125
+ self.generic_visit(node)
126
+
127
+ @override
128
+ def visit_MatchAs(self, node: ast.MatchAs) -> None:
129
+ self._bind(node.name)
130
+ self.generic_visit(node)
131
+
132
+ @override
133
+ def visit_MatchStar(self, node: ast.MatchStar) -> None:
134
+ self._bind(node.name)
135
+
136
+ @override
137
+ def visit_MatchMapping(self, node: ast.MatchMapping) -> None:
138
+ self._bind(node.rest)
139
+ self.generic_visit(node)
140
+
141
+ @override
142
+ def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
143
+ self._scope(node, node.name)
144
+
145
+ @override
146
+ def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
147
+ self._scope(node, node.name)
148
+
149
+ @override
150
+ def visit_ClassDef(self, node: ast.ClassDef) -> None:
151
+ self._scope(node, node.name)
152
+
153
+ @override
154
+ def visit_Lambda(self, node: ast.Lambda) -> None:
155
+ self._scope(node, None)
156
+
157
+ def _scope(self, node: ast.AST, name: str | None) -> None:
158
+ """Visit a node that binds `name` where it stands and opens a scope of its own, where only `global` counts.
159
+
160
+ A comprehension is not one here: the name of a `:=` inside it is bound outside it, and counting its loop's
161
+ names too only leaves a constant unannotated.
162
+ """
163
+ self._bind(name)
164
+ self._depth += 1
165
+ self.generic_visit(node)
166
+ self._depth -= 1
167
+
168
+ def _bind(self, name: str | None) -> None:
169
+ if name is not None and not self._depth:
170
+ self.counts[name] += 1
171
+
172
+
173
+ def _candidate(statement: ast.stmt) -> str | None:
174
+ """The name a module's statement assigns, when it reads as a constant to annotate.
175
+
176
+ Returns:
177
+ The name, or None for any other statement.
178
+ """
179
+ match statement:
180
+ case ast.Assign(targets=[ast.Name(id=name)], value=value):
181
+ annotation = None
182
+ case ast.AnnAssign(target=ast.Name(id=name), annotation=annotation, value=ast.expr() as value):
183
+ pass
184
+ case _:
185
+ return None
186
+ if not CONSTANT.fullmatch(name):
187
+ return None
188
+ if isinstance(annotation, ast.Subscript):
189
+ annotation = annotation.value
190
+ if annotation is not None and last_name(annotation) in _KEPT:
191
+ return None
192
+ if isinstance(value, ast.Call) and last_name(value.func) in STATEFUL | DECLARES:
193
+ return None
194
+ return name
195
+
196
+
197
+ def last_name(expression: ast.expr) -> str | None:
198
+ """The last name of a dotted one: `getLogger` of `logging.getLogger`.
199
+
200
+ Returns:
201
+ The name, or None for an expression that is not a name.
202
+ """
203
+ match expression:
204
+ case ast.Name(id=name) | ast.Attribute(attr=name):
205
+ return name
206
+ case ast.Constant(value=str(text)):
207
+ # A quoted annotation, `"Final[int]"`.
208
+ return re.split(r"[\[\s]", text.strip(), maxsplit=1)[0].rpartition(".")[2]
209
+ case _:
210
+ return None
211
+
212
+
213
+ def _final(small: cst.BaseSmallStatement, names: AbstractSet[str]) -> cst.BaseSmallStatement:
214
+ """Annotate a statement `Final`, around the annotation it has, when it assigns one of `names`.
215
+
216
+ Returns:
217
+ The statement annotated, or as it was.
218
+ """
219
+ match small:
220
+ case cst.AnnAssign(target=cst.Name(value=name), annotation=annotation) if name in names:
221
+ wrapped = cst.Subscript(cst.Name("Final"), [cst.SubscriptElement(cst.Index(annotation.annotation))])
222
+ return small.with_changes(annotation=annotation.with_changes(annotation=wrapped))
223
+ case cst.Assign(targets=[cst.AssignTarget(target=cst.Name(value=name) as target)]) if name in names:
224
+ return cst.AnnAssign(target, cst.Annotation(cst.Name("Final")), small.value, semicolon=small.semicolon)
225
+ case _:
226
+ return small