python-checks 0.10.0__py3-none-any.whl → 0.11.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.
@@ -114,6 +114,9 @@ class Directory(CheckSettings):
114
114
  `operation` — the shape of an operation, if operations are kept here.
115
115
  `orm` — what the directory is to an ORM model: its home or where it is built.
116
116
  `base` — the base class by which a model is recognised in the models' home.
117
+ `optional` — the directory may not exist yet: the block says where code
118
+ goes, not where it already is, and `doctor` does not ask the tree for it.
119
+ The rules judge it as soon as a file turns up there.
117
120
  """
118
121
 
119
122
  only: tuple[Kind, ...] = ()
@@ -125,6 +128,7 @@ class Directory(CheckSettings):
125
128
  operation: Operation | None = None
126
129
  orm: Orm | None = None
127
130
  base: str | None = None
131
+ optional: bool = False
128
132
 
129
133
  @property
130
134
  def restricted(self) -> bool:
@@ -0,0 +1,442 @@
1
+ """Who calls a function: what `--fix` must rewrite before a parameter becomes named.
2
+
3
+ A `*` in a signature turns every positional call into a type error, and the
4
+ calls live in other modules, in tests, behind an import alias. The rule finds
5
+ them in two steps. A plain walk over the tree collects every place the name
6
+ is written — cheap and complete, but blind to whose name it is. jedi then
7
+ says, for each place, whose it is: ours, someone else's (`dict.get`), or
8
+ nobody knows. "Nobody knows" stops the fix: a call that cannot be told apart
9
+ is a call that could be broken, and a fix that cannot repair every caller is
10
+ not applied at all.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import ast
16
+ import os
17
+ import subprocess
18
+ from collections import defaultdict
19
+ from dataclasses import dataclass, replace
20
+ from pathlib import Path
21
+ from typing import TYPE_CHECKING, Final, Protocol, cast
22
+
23
+ import jedi # pyright: ignore[reportMissingTypeStubs] - jedi ships no stubs; `Found` types what is read
24
+
25
+ from py_checks.checks._names import names as named
26
+ from py_checks.checks.signatures._functions import receiver
27
+ from py_checks.checks.signatures._stops import stops
28
+ from py_checks.checks.signatures._targets import following, project_modules, relative, violated
29
+ from py_checks.core import Edit, Patch, Repair, column
30
+
31
+ if TYPE_CHECKING:
32
+ from collections.abc import Iterable, Iterator, Sequence
33
+
34
+ from py_checks.checks.signatures._targets import Module, Star, Target
35
+ from py_checks.core import Violation
36
+
37
+
38
+ VENV: Final = ".venv"
39
+
40
+
41
+ VIRTUAL_ENV: Final = "VIRTUAL_ENV"
42
+
43
+ # Only what is committed: an untracked `.venv` without a `.gitignore` is still
44
+ # one's own, made on this machine.
45
+ COMMITTED: Final = ("git", "ls-files", "--cached", "--")
46
+
47
+
48
+ CLASSMETHOD: Final = "classmethod"
49
+
50
+
51
+ class Found(Protocol):
52
+ """What the fix reads of a jedi definition: the file and the line it is in."""
53
+
54
+ @property
55
+ def module_path(self) -> Path | None: ...
56
+
57
+ @property
58
+ def line(self) -> int | None: ...
59
+
60
+
61
+ @dataclass(frozen=True, slots=True)
62
+ class Site:
63
+ """A place a target's name is written: a call or a mention."""
64
+
65
+ path: Path
66
+ node: ast.Name | ast.Attribute
67
+ call: ast.Call | None
68
+ name: str
69
+
70
+
71
+ def callers(
72
+ *,
73
+ violations: Sequence[Violation],
74
+ root: Path,
75
+ source: Path,
76
+ star: Star,
77
+ ) -> Repair:
78
+ """The fix for every violation whose callers can all be found, and the rest left."""
79
+ modules = project_modules(root=root)
80
+ fixed, left = violated(
81
+ violations=violations,
82
+ modules=modules,
83
+ )
84
+ followers, unmatched = following(
85
+ targets=fixed,
86
+ modules=modules,
87
+ source=source,
88
+ star=star,
89
+ root=root,
90
+ )
91
+ targets = [*fixed, *followers]
92
+ # The definition's own reason first: "called through its class" says more
93
+ # about a constructor than any double of the same name does.
94
+ stopped = stops(
95
+ targets=targets,
96
+ modules=modules,
97
+ root=root,
98
+ )
99
+ for family, reason in unmatched.items():
100
+ stopped.setdefault(family, reason)
101
+ edits = _calls(
102
+ targets=targets,
103
+ modules=modules,
104
+ project=_project(
105
+ root=root,
106
+ source=source,
107
+ ),
108
+ stopped=stopped,
109
+ root=root,
110
+ )
111
+ return _repair(
112
+ targets=targets,
113
+ edits=edits,
114
+ stopped=stopped,
115
+ left=left,
116
+ )
117
+
118
+
119
+ def _repair(
120
+ *,
121
+ targets: Sequence[Target],
122
+ edits: dict[tuple[str, ...], list[Patch]],
123
+ stopped: dict[tuple[str, ...], str],
124
+ left: list[Violation],
125
+ ) -> Repair:
126
+ """One patch set per family, shared by its members: they stand or fall together."""
127
+ members: dict[tuple[str, ...], list[Target]] = defaultdict(list)
128
+ for target in targets:
129
+ members[target.family].append(target)
130
+ repair = Repair(
131
+ patches={},
132
+ left=list(left),
133
+ )
134
+ for family, group in members.items():
135
+ violated = [target.violation for target in group if target.violation is not None]
136
+ if family in stopped:
137
+ repair.left.extend(
138
+ replace(
139
+ violation,
140
+ message=f"{violation.message}; not fixed: {stopped[family]}",
141
+ )
142
+ for violation in violated
143
+ )
144
+ continue
145
+ shared = (
146
+ *(
147
+ Patch(
148
+ path=target.path,
149
+ edit=target.edit,
150
+ )
151
+ for target in group
152
+ ),
153
+ *edits.get(family, ()),
154
+ )
155
+ repair.patches.update((violation, shared) for violation in violated)
156
+ return repair
157
+
158
+
159
+ def _project(
160
+ *,
161
+ root: Path,
162
+ source: Path,
163
+ ) -> jedi.Project:
164
+ """jedi over the project, in the project's own environment when there is one.
165
+
166
+ A hook runs in an environment of its own, where neither the project nor
167
+ its libraries are installed: without the project's `.venv` a library call
168
+ resolves to nothing and stops the fix of every function sharing its name.
169
+ """
170
+ environment = _environment(root=root)
171
+ return jedi.Project(
172
+ path=root,
173
+ environment_path=environment,
174
+ added_sys_path=(str(source),),
175
+ )
176
+
177
+
178
+ def _environment(*, root: Path) -> str | None:
179
+ """The interpreter jedi starts: the project's `.venv`, when git vouches for it.
180
+
181
+ jedi runs that interpreter to learn its paths, so the fix runs whatever
182
+ lies at `.venv/bin/python`. A `.venv` of one's own is not in git's index;
183
+ one that came with the repository — or with an archive git cannot speak
184
+ for — is someone else's program, and the fix stays in its own environment:
185
+ fewer calls resolved, nothing run.
186
+ """
187
+ venv = root / VENV
188
+ if venv.is_dir() and _local(root=root):
189
+ return str(venv)
190
+ return os.environ.get(VIRTUAL_ENV) or None
191
+
192
+
193
+ def _local(*, root: Path) -> bool:
194
+ """Whether git confirms nothing under `.venv` is committed; no answer is a no."""
195
+ try:
196
+ listed = subprocess.run( # noqa: S603 — a fixed list of arguments, no shell
197
+ [*COMMITTED, VENV],
198
+ cwd=root,
199
+ capture_output=True,
200
+ check=True,
201
+ )
202
+ except OSError, subprocess.CalledProcessError:
203
+ return False
204
+ return not listed.stdout.strip()
205
+
206
+
207
+ def _calls(
208
+ *,
209
+ targets: Sequence[Target],
210
+ modules: Sequence[Module],
211
+ project: jedi.Project,
212
+ stopped: dict[tuple[str, ...], str],
213
+ root: Path,
214
+ ) -> dict[tuple[str, ...], list[Patch]]:
215
+ """The call edits of every family; a family that meets a doubtful place is stopped."""
216
+ index = {(target.path, target.definition.node.lineno): target for target in targets}
217
+ # A stopped family needs no more reasons: its places are not worth a lookup.
218
+ wanted = {target.name for target in targets if target.family not in stopped}
219
+ edits: dict[tuple[str, ...], list[Patch]] = defaultdict(list)
220
+ for module in modules:
221
+ sites = list(
222
+ _sites(
223
+ module=module,
224
+ wanted=wanted,
225
+ )
226
+ )
227
+ if not sites:
228
+ continue
229
+ script = jedi.Script(
230
+ code=module.text,
231
+ path=module.path,
232
+ project=project,
233
+ )
234
+ lines = module.text.splitlines()
235
+ for site in sites:
236
+ _place(
237
+ site=site,
238
+ found=_resolved(
239
+ site=site,
240
+ script=script,
241
+ lines=lines,
242
+ index=index,
243
+ ),
244
+ lines=lines,
245
+ targets=targets,
246
+ edits=edits,
247
+ stopped=stopped,
248
+ where=relative(
249
+ path=site.path,
250
+ line=site.node.lineno,
251
+ root=root,
252
+ ),
253
+ )
254
+ return edits
255
+
256
+
257
+ def _resolved(
258
+ *,
259
+ site: Site,
260
+ script: jedi.Script,
261
+ lines: Sequence[str],
262
+ index: dict[tuple[Path, int], Target],
263
+ ) -> list[Target] | None:
264
+ """The targets this place names; `None` when nobody knows whose name it is.
265
+
266
+ An empty list is someone else's name: `dict.get`, a library, a function of
267
+ the project the fix does not change. A place that names a target and
268
+ something else at once — a union type — is as good as unknown.
269
+ """
270
+ line, offset = _point(node=site.node)
271
+ found = _goto(
272
+ script=script,
273
+ line=line,
274
+ column=column(
275
+ line=lines[line - 1],
276
+ offset=offset,
277
+ )
278
+ - 1,
279
+ )
280
+ if not found:
281
+ return None
282
+ hits = [
283
+ index.get((Path(one.module_path).resolve(), one.line))
284
+ for one in found
285
+ if one.module_path is not None and one.line is not None
286
+ ]
287
+ mine = [hit for hit in hits if hit is not None]
288
+ if mine and len(mine) < len(found):
289
+ return None
290
+ return mine
291
+
292
+
293
+ def _goto(
294
+ *,
295
+ script: jedi.Script,
296
+ line: int,
297
+ column: int,
298
+ ) -> list[Found]:
299
+ """Where jedi says the name at this point is defined; jedi ships no type hints."""
300
+ found = script.goto( # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
301
+ line,
302
+ column,
303
+ follow_imports=True,
304
+ )
305
+ return cast("list[Found]", found)
306
+
307
+
308
+ def _place(
309
+ *,
310
+ site: Site,
311
+ found: list[Target] | None,
312
+ lines: Sequence[str],
313
+ targets: Sequence[Target],
314
+ edits: dict[tuple[str, ...], list[Patch]],
315
+ stopped: dict[tuple[str, ...], str],
316
+ where: str,
317
+ ) -> None:
318
+ """Record what one place means for the families its name could belong to."""
319
+ if found is None:
320
+ for target in targets:
321
+ if target.name == site.name:
322
+ stopped.setdefault(target.family, f"{where} cannot be resolved")
323
+ return
324
+ for target in found:
325
+ reason, made = _rewritten(
326
+ site=site,
327
+ target=target,
328
+ lines=lines,
329
+ )
330
+ if reason is not None:
331
+ stopped.setdefault(target.family, f"{where} {reason}")
332
+ else:
333
+ edits[target.family].extend(made)
334
+
335
+
336
+ def _rewritten(
337
+ *,
338
+ site: Site,
339
+ target: Target,
340
+ lines: Sequence[str],
341
+ ) -> tuple[str | None, list[Patch]]:
342
+ """The call with its positional arguments named, or why it cannot be."""
343
+ call = site.call
344
+ if call is None:
345
+ return "passes it as a value", []
346
+ if any(isinstance(argument, ast.Starred) for argument in call.args):
347
+ return "unpacks arguments into it", []
348
+ if _through_class(
349
+ site=site,
350
+ target=target,
351
+ ):
352
+ return "calls it through the class, receiver included", []
353
+ moved = call.args[target.kept :]
354
+ if len(moved) > len(target.names):
355
+ return "passes more arguments than it takes", []
356
+ return None, [
357
+ Patch(
358
+ path=site.path,
359
+ edit=Edit(
360
+ line=argument.lineno,
361
+ column=(
362
+ at := column(
363
+ line=lines[argument.lineno - 1],
364
+ offset=argument.col_offset,
365
+ )
366
+ ),
367
+ end_line=argument.lineno,
368
+ end_column=at,
369
+ text=f"{parameter}=",
370
+ ),
371
+ )
372
+ for argument, parameter in zip(moved, target.names, strict=False)
373
+ ]
374
+
375
+
376
+ def _through_class(
377
+ *,
378
+ site: Site,
379
+ target: Target,
380
+ ) -> bool:
381
+ """`Repo.get(repo, key)`: the receiver is the first positional argument."""
382
+ if not isinstance(site.node, ast.Attribute) or not isinstance(site.node.value, ast.Name):
383
+ return False
384
+ plain = target.definition.method and receiver(definition=target.definition) == 1
385
+ if not plain or CLASSMETHOD in set(named(nodes=target.definition.node.decorator_list)):
386
+ return False
387
+ return site.node.value.id[:1].isupper()
388
+
389
+
390
+ def _sites(
391
+ *,
392
+ module: Module,
393
+ wanted: set[str],
394
+ ) -> Iterator[Site]:
395
+ """Every place in the module where one of the wanted names is written.
396
+
397
+ `from orders import price as quote` makes `quote` a place of `price`.
398
+ """
399
+ if module.tree is None:
400
+ return
401
+ aliases = dict(
402
+ _aliases(
403
+ tree=module.tree,
404
+ wanted=wanted,
405
+ )
406
+ )
407
+ callees = {id(node.func): node for node in ast.walk(module.tree) if isinstance(node, ast.Call)}
408
+ for node in ast.walk(module.tree):
409
+ match node:
410
+ case ast.Name(id=name) if name in wanted or name in aliases:
411
+ spelled = aliases.get(name, name)
412
+ case ast.Attribute(attr=name) if name in wanted:
413
+ spelled = name
414
+ case _:
415
+ continue
416
+ yield Site(
417
+ path=module.path,
418
+ node=node,
419
+ call=callees.get(id(node)),
420
+ name=spelled,
421
+ )
422
+
423
+
424
+ def _aliases(
425
+ *,
426
+ tree: ast.Module,
427
+ wanted: set[str],
428
+ ) -> Iterable[tuple[str, str]]:
429
+ for node in ast.walk(tree):
430
+ if isinstance(node, ast.ImportFrom):
431
+ for alias in node.names:
432
+ if alias.asname and alias.name in wanted:
433
+ yield alias.asname, alias.name
434
+
435
+
436
+ def _point(*, node: ast.Name | ast.Attribute) -> tuple[int, int]:
437
+ """Where the name itself starts: for `repo.get`, the `get`, not the `repo`."""
438
+ if isinstance(node, ast.Name):
439
+ return node.lineno, node.col_offset
440
+ end_line = node.end_lineno or node.lineno
441
+ end = node.end_col_offset or 0
442
+ return end_line, end - len(node.attr.encode("utf-8"))
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import TYPE_CHECKING, ClassVar, Final
6
6
 
7
+ from py_checks.checks.signatures._callers import callers
7
8
  from py_checks.checks.signatures._functions import (
8
9
  Definition,
9
10
  definitions,
@@ -15,10 +16,12 @@ from py_checks.config import CheckSettings
15
16
  from py_checks.core import Edit, Scope, Violation, column
16
17
 
17
18
  if TYPE_CHECKING:
18
- from collections.abc import Iterator
19
+ import ast
20
+ from collections.abc import Iterator, Sequence
21
+ from pathlib import Path
19
22
 
20
23
  from py_checks.checks.signatures._functions import Function
21
- from py_checks.core import ParsedFile
24
+ from py_checks.core import ParsedFile, Repair
22
25
 
23
26
  CODE: Final = "keyword-only-arguments"
24
27
 
@@ -99,6 +102,21 @@ class KeywordOnlyArguments:
99
102
  end_line=end_line,
100
103
  )
101
104
 
105
+ def repair(
106
+ self,
107
+ *,
108
+ violations: Sequence[Violation],
109
+ root: Path,
110
+ source: Path,
111
+ ) -> Repair:
112
+ """`--fix` names the arguments at every call, or changes nothing."""
113
+ return callers(
114
+ violations=violations,
115
+ root=root,
116
+ source=source,
117
+ star=self._star,
118
+ )
119
+
102
120
  @staticmethod
103
121
  def _interpreter_dunder(*, name: str) -> bool:
104
122
  own = name.rsplit(".", maxsplit=1)[-1]
@@ -128,23 +146,102 @@ class KeywordOnlyArguments:
128
146
  """The edit: a `*` before the first argument that is now positional.
129
147
 
130
148
  Not for every case. With `*args` a second star does not fit in the
131
- signature, and with `/` the arguments are positional because the
132
- author asked for it, and overruling the author is not an autofix's
133
- place.
149
+ signature. Arguments before `/` are positional because the author
150
+ asked for it, and overruling the author is not an autofix's place: the
151
+ star goes after `/`.
134
152
  """
135
- node = definition.node
136
- if node.args.vararg is not None or node.args.posonlyargs:
153
+ arguments = definition.node.args
154
+ if arguments.vararg is not None:
155
+ return None
156
+ skip = max(receiver(definition=definition) - len(arguments.posonlyargs), 0)
157
+ if len(arguments.args) <= skip:
137
158
  return None
138
- first = node.args.args[receiver(definition=definition)]
139
- line = first.lineno
140
- at = column(
141
- line=file.lines[line - 1],
142
- offset=first.col_offset,
159
+ start = _position(
160
+ file=file,
161
+ node=arguments.args[skip],
143
162
  )
163
+ if arguments.kwonlyargs:
164
+ return _moved(
165
+ file=file,
166
+ arguments=arguments,
167
+ start=start,
168
+ )
144
169
  return Edit(
145
- line=line,
146
- column=at,
147
- end_line=line,
148
- end_column=at,
170
+ line=start[0],
171
+ column=start[1],
172
+ end_line=start[0],
173
+ end_column=start[1],
149
174
  text="*, ",
150
175
  )
176
+
177
+
178
+ def _moved(
179
+ *,
180
+ file: ParsedFile,
181
+ arguments: ast.arguments,
182
+ start: tuple[int, int],
183
+ ) -> Edit:
184
+ """The bare `*` the signature already has, moved to the front: two do not compile."""
185
+ last = _position(
186
+ file=file,
187
+ node=(arguments.defaults or arguments.args)[-1],
188
+ end=True,
189
+ )
190
+ end = _position(
191
+ file=file,
192
+ node=arguments.kwonlyargs[0],
193
+ )
194
+ between = _between(
195
+ file=file,
196
+ start=last,
197
+ end=end,
198
+ )
199
+ star = between.index("*")
200
+ return Edit(
201
+ line=start[0],
202
+ column=start[1],
203
+ end_line=end[0],
204
+ end_column=end[1],
205
+ # The star travels with what follows it, so a signature written one
206
+ # argument per line keeps that shape.
207
+ text=(
208
+ between[star:]
209
+ + _between(
210
+ file=file,
211
+ start=start,
212
+ end=last,
213
+ )
214
+ + between[:star]
215
+ ),
216
+ )
217
+
218
+
219
+ def _position(
220
+ *,
221
+ file: ParsedFile,
222
+ node: ast.expr | ast.arg,
223
+ end: bool = False,
224
+ ) -> tuple[int, int]:
225
+ """Where the node starts or ends, as an edit counts it: line and column from 1."""
226
+ line = node.end_lineno if end else node.lineno
227
+ offset = node.end_col_offset if end else node.col_offset
228
+ if line is None or offset is None:
229
+ message = "a parsed node always has a position"
230
+ raise AssertionError(message)
231
+ return line, column(
232
+ line=file.lines[line - 1],
233
+ offset=offset,
234
+ )
235
+
236
+
237
+ def _between(
238
+ *,
239
+ file: ParsedFile,
240
+ start: tuple[int, int],
241
+ end: tuple[int, int],
242
+ ) -> str:
243
+ """The source text between two positions, line breaks as written."""
244
+ lines = file.text.splitlines(keepends=True)[start[0] - 1 : end[0]]
245
+ if len(lines) == 1:
246
+ return lines[0][start[1] - 1 : end[1] - 1]
247
+ return lines[0][start[1] - 1 :] + "".join(lines[1:-1]) + lines[-1][: end[1] - 1]