codelaw-rules-python 0.2.0__py3-none-any.whl

codelaw_rules_python/presets/py/recommended.toml

@@ -0,0 +1,99 @@
+description = "Ruff 0.17.1's long-standing default (E4, E7, E9, F) plus flake8-bugbear (B), isort's import order (I001) and sorted __all__ (RUF022), reimplemented"
+
+[rules]
+"py/abstract-base-class-without-abstract-method" = "error"
+"py/all-sorted" = "error"
+"py/ambiguous-class-name" = "error"
+"py/ambiguous-function-name" = "error"
+"py/ambiguous-variable-name" = "error"
+"py/assert-false" = "error"
+"py/assert-raises-exception" = "error"
+"py/assert-tuple" = "error"
+"py/assignment-to-os-environ" = "error"
+"py/batched-without-explicit-strict" = "error"
+"py/break-outside-loop" = "error"
+"py/cached-instance-method" = "error"
+"py/continue-outside-loop" = "error"
+"py/default-except-not-last" = "error"
+"py/duplicate-dict-key" = "error"
+"py/duplicate-dict-key-variable" = "error"
+"py/duplicate-handler-exception" = "error"
+"py/duplicate-set-value" = "error"
+"py/duplicate-try-block-exception" = "error"
+"py/empty-method-without-abstract-decorator" = "error"
+"py/except-with-empty-tuple" = "error"
+"py/except-with-non-exception-classes" = "error"
+"py/f-string-docstring" = "error"
+"py/f-string-missing-placeholders" = "error"
+"py/format-invalid" = "error"
+"py/format-missing-argument" = "error"
+"py/format-mixed-numbering" = "error"
+"py/format-unused-named-argument" = "error"
+"py/format-unused-positional-argument" = "error"
+"py/forward-annotation-syntax-error" = "error"
+"py/function-call-in-default-argument" = "error"
+"py/function-uses-loop-variable" = "error"
+"py/getattr-with-constant" = "error"
+"py/if-tuple" = "error"
+"py/import-shadowed-by-loop-var" = "error"
+"py/invalid-print-syntax" = "error"
+"py/is-literal" = "error"
+"py/jump-statement-in-finally" = "error"
+"py/lambda-assignment" = "error"
+"py/late-future-import" = "error"
+"py/loop-variable-overrides-iterator" = "error"
+"py/map-without-explicit-strict" = "error"
+"py/module-import-not-at-top" = "error"
+"py/multiple-imports-on-one-line" = "error"
+"py/multiple-starred-expressions" = "error"
+"py/mutable-contextvar-default" = "error"
+"py/nested-star-import" = "error"
+"py/no-bare-except" = "error"
+"py/no-explicit-stacklevel" = "error"
+"py/no-mutable-default" = "error"
+"py/no-star-import" = "error"
+"py/none-comparison" = "error"
+"py/not-in-test" = "error"
+"py/not-is-test" = "error"
+"py/percent-format-count-mismatch" = "error"
+"py/percent-format-expected-mapping" = "error"
+"py/percent-format-expected-sequence" = "error"
+"py/percent-format-invalid" = "error"
+"py/percent-format-missing-argument" = "error"
+"py/percent-format-mixed-placeholders" = "error"
+"py/percent-format-star-requires-sequence" = "error"
+"py/percent-format-unsupported-character" = "error"
+"py/percent-format-unused-named-argument" = "error"
+"py/raise-literal" = "error"
+"py/raise-not-implemented" = "error"
+"py/raise-without-from-inside-except" = "error"
+"py/re-sub-positional-args" = "error"
+"py/redefined-while-unused" = "error"
+"py/redundant-tuple-in-exception-handler" = "error"
+"py/return-outside-function" = "error"
+"py/reuse-of-groupby-generator" = "error"
+"py/setattr-with-constant" = "error"
+"py/star-arg-unpacking-after-keyword-arg" = "error"
+"py/star-import-usage" = "error"
+"py/static-key-dict-comprehension" = "error"
+"py/strip-with-multi-characters" = "error"
+"py/too-many-expressions-in-star-assignment" = "error"
+"py/true-false-comparison" = "error"
+"py/type-comparison" = "error"
+"py/unary-prefix-increment" = "error"
+"py/undefined-export" = "error"
+"py/undefined-future-feature" = "error"
+"py/undefined-local" = "error"
+"py/undefined-name" = "error"
+"py/unintentional-type-annotation" = "error"
+"py/unreliable-callable-check" = "error"
+"py/unsorted-imports" = "error"
+"py/unused-annotation" = "error"
+"py/unused-import" = "error"
+"py/unused-loop-control-variable" = "error"
+"py/unused-variable" = "error"
+"py/useless-comparison" = "error"
+"py/useless-contextlib-suppress" = "error"
+"py/useless-expression" = "error"
+"py/yield-outside-function" = "error"
+"py/zip-without-explicit-strict" = "error"

codelaw_rules_python/rules/graph/no-unused-exports.md

@@ -0,0 +1,69 @@
+---
+id: graph/no-unused-exports
+title: Exported symbols must be used somewhere
+languages: [python]
+scope: project
+severity: error
+fix: suggest
+fix_reason: "Static analysis can't rule out reflective or external use, so removal needs a human or agent to accept the diff."
+stability: preview
+ported_from: [vulture/unused-function]
+since: 0.1.0
+---
+
+Every name a module exports is imported by another module, is reachable from an entry point, or is marked `# codelaw: keep`.
+
+**Why:** a module-level function or class nothing imports is dead code that still looks like API. A module with `__all__` exports what it lists; without one, a public name counts only when its own module doesn't use it either.
+
+```codelaw
+graph:
+  symbol:
+    exported: true
+    kind: [function, class, variable, type, interface, enum]
+  unless:
+    - reachable_from: entry
+    - tagged: [public, keep]
+  when:
+    external_references: 0
+  certainty_from: module.dynamic
+message: "`$SYMBOL` is exported but never used outside `$FILE`"
+fix:
+  - when: { local_references: ">0" }
+    do: [strip-export-keyword]
+  - else:
+    do: [remove-declaration]
+```
+
+## How to fix
+
+1. Run `codelaw graph why-unused <symbol>` (`<file>#<export>` or `<module>:<name>`) to see each entry, keep and import clause.
+2. If something outside the repo uses it, add the file to `[graph] entry` or `[graph] keep`, add its decorator to `[graph] registrars`, or tag it `/** @public */` / `# codelaw: keep`.
+3. Otherwise delete the declaration (and its `__all__` or `export { … }` entry), or drop `export` if its own file still uses it.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py files
+# app/dates.py
+def format_date(d):
+    return d.isoformat()
+def parse_date(s):
+    return s
+# app/main.py
+from app.dates import format_date
+print(format_date(None))
+```
+
+#### Do
+
+```py files
+# app/dates.py
+def format_date(d):
+    return d.isoformat()
+# app/main.py
+from app.dates import format_date
+print(format_date(None))
+```

codelaw_rules_python/rules/py/abstract-base-class-without-abstract-method.md

@@ -0,0 +1,50 @@
+---
+id: py/abstract-base-class-without-abstract-method
+title: "An abstract base class has an abstract method"
+languages: [python]
+fix: manual
+fix_reason: "which methods subclasses must provide is a design decision"
+stability: preview
+ported_from: [ruff/B024]
+since: 0.1.0
+---
+
+A class that inherits only from `ABC` (or uses `ABCMeta`) declares at least one `@abstractmethod`.
+
+**Why:** Without one, nothing stops the base class being instantiated, and readers can't tell what subclasses must provide.
+
+```codelaw
+native: py/abstract-base-class-without-abstract-method
+```
+
+## How to fix
+
+1. Mark the methods subclasses must override with `@abstractmethod`, or
+2. drop `ABC` if the class isn't meant to be abstract.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+from abc import ABC
+
+
+class Shape(ABC):
+    def area(self):
+        return 0
+```
+
+#### Do
+
+```py
+from abc import ABC, abstractmethod
+
+
+class Shape(ABC):
+    @abstractmethod
+    def area(self):
+        return 0
+```

codelaw_rules_python/rules/py/all-sorted.cases.md

@@ -0,0 +1,74 @@
+# py/all-sorted — cases
+
+### case: multi-line list
+
+```py
+__all__ = [
+    "b",
+    "a",
+]
+```
+
+```expect
+1:11 py/all-sorted
+```
+
+```fixed
+__all__ = [
+    "a",
+    "b",
+]
+```
+
+### case: several items per line
+
+```py
+__all__ = ["b", "a",
+           "c"]
+```
+
+```expect
+1:11 py/all-sorted
+```
+
+```fixed
+__all__ = ["a",
+           "b",
+           "c"]
+```
+
+### case: case-sensitive within a group
+
+```py
+__all__ = ["LWPCookieJar", "LoadError"]
+```
+
+```expect
+(none)
+```
+
+### case: augmented and bare tuples
+
+```py
+__all__ = "b", "a"
+if x:
+    __all__ += ["d", "c"]
+```
+
+```expect
+1:11 py/all-sorted
+3:16 py/all-sorted
+```
+
+### case: comments block the fix
+
+```py
+__all__ = [
+    "b",  # keep
+    "a",
+]
+```
+
+```expect
+1:11 py/all-sorted
+```

codelaw_rules_python/rules/py/all-sorted.md

@@ -0,0 +1,33 @@
+---
+id: py/all-sorted
+title: "`__all__` is sorted"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/RUF022]
+since: 0.1.0
+---
+
+A module's `__all__` lists its names in isort's order: CONSTANTS, then Classes, then other names, each group in natural order.
+
+**Why:** A sorted `__all__` is easy to scan and to keep in sync with the module.
+
+```codelaw
+native: py/all-sorted
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+__all__ = ["save", "Loader", "load", "VERSION"]
+```
+
+#### Do
+
+```py
+__all__ = ["VERSION", "Loader", "load", "save"]
+```

codelaw_rules_python/rules/py/ambiguous-class-name.md

@@ -0,0 +1,41 @@
+---
+id: py/ambiguous-class-name
+title: "No classes named `l`, `O` or `I`"
+languages: [python]
+fix: manual
+fix_reason: "the new name is the author's choice, and other modules may use the old one"
+stability: preview
+ported_from: [ruff/E742]
+since: 0.1.0
+---
+
+Classes aren't named `l`, `O` or `I`.
+
+**Why:** In many fonts they are indistinguishable from `1` and `0`.
+
+```codelaw
+native: py/ambiguous-class-name
+```
+
+## How to fix
+
+1. Rename the class.
+2. Update its uses, here and in modules that import it.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+class I:
+    pass
+```
+
+#### Do
+
+```py
+class Item:
+    pass
+```

codelaw_rules_python/rules/py/ambiguous-function-name.md

@@ -0,0 +1,41 @@
+---
+id: py/ambiguous-function-name
+title: "No functions named `l`, `O` or `I`"
+languages: [python]
+fix: manual
+fix_reason: "the new name is the author's choice, and other modules may use the old one"
+stability: preview
+ported_from: [ruff/E743]
+since: 0.1.0
+---
+
+Functions aren't named `l`, `O` or `I`.
+
+**Why:** In many fonts they are indistinguishable from `1` and `0`.
+
+```codelaw
+native: py/ambiguous-function-name
+```
+
+## How to fix
+
+1. Rename the function.
+2. Update its callers, here and in modules that import it.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def O():
+    return 0
+```
+
+#### Do
+
+```py
+def origin():
+    return 0
+```

codelaw_rules_python/rules/py/ambiguous-variable-name.cases.md

@@ -0,0 +1,47 @@
+# py/ambiguous-variable-name — cases
+
+### case: lambda parameters are not checked
+
+```py
+f = lambda l: l
+```
+
+```expect
+(none)
+```
+
+### case: loop and with targets
+
+```py
+for l in items:
+    pass
+with open(p) as I:
+    pass
+```
+
+```expect
+1:5 py/ambiguous-variable-name
+3:17 py/ambiguous-variable-name
+```
+
+### case: import alias
+
+```py
+import numpy as l
+```
+
+```expect
+1:17 py/ambiguous-variable-name
+```
+
+### case: augmented assignment
+
+```py
+def f(l):
+    l -= 1
+```
+
+```expect
+1:7 py/ambiguous-variable-name
+2:5 py/ambiguous-variable-name
+```

codelaw_rules_python/rules/py/ambiguous-variable-name.md

@@ -0,0 +1,39 @@
+---
+id: py/ambiguous-variable-name
+title: "No variables named `l`, `O` or `I`"
+languages: [python]
+fix: manual
+fix_reason: "the new name is the author's choice"
+stability: preview
+ported_from: [ruff/E741]
+since: 0.1.0
+---
+
+Variables, parameters and import aliases aren't named `l`, `O` or `I`.
+
+**Why:** In many fonts they are indistinguishable from `1` and `0`.
+
+```codelaw
+native: py/ambiguous-variable-name
+```
+
+## How to fix
+
+1. Rename the variable to a descriptive name.
+2. Update its uses.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+l = len(items)
+```
+
+#### Do
+
+```py
+length = len(items)
+```

codelaw_rules_python/rules/py/assert-false.md

@@ -0,0 +1,34 @@
+---
+id: py/assert-false
+title: "Don't `assert False`"
+languages: [python]
+fix: suggest
+fix_reason: "the check now also runs under `python -O`, where the assert was skipped"
+stability: preview
+ported_from: [ruff/B011]
+since: 0.1.0
+---
+
+Code that must never be reached raises `AssertionError` instead of using `assert False`.
+
+**Why:** `python -O` removes asserts, so the check silently disappears.
+
+```codelaw
+native: py/assert-false
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+assert False, "unreachable"
+```
+
+#### Do
+
+```py
+raise AssertionError("unreachable")
+```

codelaw_rules_python/rules/py/assert-raises-exception.md

@@ -0,0 +1,51 @@
+---
+id: py/assert-raises-exception
+title: "Tests don't expect a bare `Exception`"
+languages: [python]
+fix: manual
+fix_reason: "the exception the test expects has to be named by its author"
+stability: preview
+ported_from: [ruff/B017]
+since: 0.1.0
+---
+
+`assertRaises(Exception)` and `pytest.raises(Exception)` (without `match=`) aren't used as context managers.
+
+**Why:** They pass for any error at all, including a typo in the code under test.
+
+```codelaw
+native: py/assert-raises-exception
+```
+
+## How to fix
+
+1. Name the specific exception the code should raise.
+2. With `pytest.raises`, add `match=` if the class can't be narrowed.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import unittest
+
+
+class TestParse(unittest.TestCase):
+    def test_bad_input(self):
+        with self.assertRaises(Exception):
+            parse("x")
+```
+
+#### Do
+
+```py
+import unittest
+
+
+class TestParse(unittest.TestCase):
+    def test_bad_input(self):
+        with self.assertRaises(ValueError):
+            parse("x")
+```

codelaw_rules_python/rules/py/assert-tuple.md

@@ -0,0 +1,38 @@
+---
+id: py/assert-tuple
+title: "`assert` doesn't test a tuple"
+languages: [python]
+fix: manual
+fix_reason: "removing the parentheses turns a no-op into a check that can now fail"
+stability: preview
+ported_from: [ruff/F631]
+since: 0.1.0
+---
+
+An `assert` tests a condition, not a parenthesised `(condition, message)` tuple.
+
+**Why:** A non-empty tuple is always true, so the assert can never fail.
+
+```codelaw
+native: py/assert-tuple
+```
+
+## How to fix
+
+1. Remove the parentheses so the message becomes the assert's second operand.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+assert (count > 0, "count must be positive")
+```
+
+#### Do
+
+```py
+assert count > 0, "count must be positive"
+```

codelaw_rules_python/rules/py/assignment-to-os-environ.md

@@ -0,0 +1,43 @@
+---
+id: py/assignment-to-os-environ
+title: "Don't assign to `os.environ`"
+languages: [python]
+fix: manual
+fix_reason: "whether to clear the environment first or only update it needs a person"
+stability: preview
+ported_from: [ruff/B003]
+since: 0.1.0
+---
+
+Code changes the environment through `os.environ`'s items, never by assigning a new object to `os.environ`.
+
+**Why:** Assigning replaces Python's mapping but not the process environment, so child processes don't see the change.
+
+```codelaw
+native: py/assignment-to-os-environ
+```
+
+## How to fix
+
+1. Update `os.environ` item by item (`os.environ[key] = value`), clearing it first if that was meant.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import os
+
+os.environ = {"PATH": "/bin"}
+```
+
+#### Do
+
+```py
+import os
+
+os.environ.clear()
+os.environ["PATH"] = "/bin"
+```