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

codelaw_rules_python/rules/py/batched-without-explicit-strict.md

@@ -0,0 +1,52 @@
+---
+id: py/batched-without-explicit-strict
+title: "`itertools.batched()` says `strict=`"
+languages: [python]
+fix: suggest
+fix_reason: "`strict=` exists only from Python 3.13, and codelaw cannot tell which Python the code runs on: on an older one the added keyword raises `TypeError`"
+stability: preview
+options:
+  target_version: { type: string, description: "the oldest Python the code supports; below 3.13 the rule is off" }
+ported_from: [ruff/B911]
+since: 0.1.0
+---
+
+`itertools.batched()` is called with `strict=True` or `strict=False`.
+
+**Why:** Without it, a short last batch passes silently. The keyword exists from Python 3.13.
+
+```codelaw
+native: py/batched-without-explicit-strict
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import itertools
+
+batches = itertools.batched(items, 2)
+```
+
+#### Do
+
+```py
+import itertools
+
+batches = itertools.batched(items, 2, strict=True)
+```
+
+#### Fixed
+
+```py
+import itertools
+
+batches = itertools.batched(items, 2, strict=False)
+```
+
+## Differences from the source
+
+Ruff reports this without a fix; codelaw suggests `strict=False`, which keeps today's behaviour. The fix is `suggest` (`codelaw fix --unsafe`), not `auto`: the `target_version` option may be unset, and on Python before 3.13 the keyword raises `TypeError`.

codelaw_rules_python/rules/py/break-outside-loop.md

@@ -0,0 +1,41 @@
+---
+id: py/break-outside-loop
+title: "`break` only inside a loop"
+languages: [python]
+fix: manual
+fix_reason: "what should happen instead (return, raise) is the author's choice"
+stability: preview
+ported_from: [ruff/F701]
+since: 0.1.0
+---
+
+`break` appears only inside the body of a `for` or `while` loop in the same function.
+
+**Why:** Outside a loop it is a `SyntaxError`.
+
+```codelaw
+native: py/break-outside-loop
+```
+
+## How to fix
+
+1. Use `return` to leave a function, or move the `break` into the loop.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def stop():
+    break
+```
+
+#### Do
+
+```py
+def stop(items):
+    for item in items:
+        break
+```

codelaw_rules_python/rules/py/cached-instance-method.md

@@ -0,0 +1,55 @@
+---
+id: py/cached-instance-method
+title: "No `lru_cache` on methods"
+languages: [python]
+fix: manual
+fix_reason: "where the cache should live is a design choice"
+stability: preview
+ported_from: [ruff/B019]
+since: 0.1.0
+---
+
+`functools.lru_cache` and `functools.cache` decorate functions and static methods, not instance methods.
+
+**Why:** The cache keeps a reference to every `self` it sees, so instances are never freed.
+
+```codelaw
+native: py/cached-instance-method
+```
+
+## How to fix
+
+1. Move the cached work into a module-level function or a `staticmethod`.
+2. Or keep a per-instance cache in an attribute.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import functools
+
+
+class Store:
+    @functools.lru_cache
+    def get(self, key):
+        return key.upper()
+```
+
+#### Do
+
+```py
+import functools
+
+
+@functools.lru_cache
+def normalise(key):
+    return key.upper()
+
+
+class Store:
+    def get(self, key):
+        return normalise(key)
+```

codelaw_rules_python/rules/py/continue-outside-loop.md

@@ -0,0 +1,41 @@
+---
+id: py/continue-outside-loop
+title: "`continue` only inside a loop"
+languages: [python]
+fix: manual
+fix_reason: "what should happen instead is the author's choice"
+stability: preview
+ported_from: [ruff/F702]
+since: 0.1.0
+---
+
+`continue` appears only inside the body of a `for` or `while` loop in the same function.
+
+**Why:** Outside a loop it is a `SyntaxError`.
+
+```codelaw
+native: py/continue-outside-loop
+```
+
+## How to fix
+
+1. Move the `continue` into the loop, or restructure the code.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def skip():
+    continue
+```
+
+#### Do
+
+```py
+def skip(items):
+    for item in items:
+        continue
+```

codelaw_rules_python/rules/py/default-except-not-last.md

@@ -0,0 +1,48 @@
+---
+id: py/default-except-not-last
+title: "A bare `except:` is the last handler"
+languages: [python]
+fix: manual
+fix_reason: "reordering handlers changes which one runs"
+stability: preview
+ported_from: [ruff/F707]
+since: 0.1.0
+---
+
+In a `try` statement, a bare `except:` comes after every other handler.
+
+**Why:** Handlers after a bare `except:` can never run, and Python rejects it as a `SyntaxError`.
+
+```codelaw
+native: py/default-except-not-last
+```
+
+## How to fix
+
+1. Move the bare `except:` to the end.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except:
+    log()
+except ValueError:
+    retry()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except ValueError:
+    retry()
+except:
+    log()
+```

codelaw_rules_python/rules/py/duplicate-dict-key-variable.md

@@ -0,0 +1,39 @@
+---
+id: py/duplicate-dict-key-variable
+title: "A dict literal doesn't repeat a variable key"
+languages: [python]
+fix: manual
+fix_reason: "which value should win can't be known from the code"
+stability: preview
+ported_from: [ruff/F602]
+since: 0.1.0
+---
+
+A dict literal uses the same variable as a key at most once.
+
+**Why:** Both entries have the same key at run time, so only the last value is kept.
+
+```codelaw
+native: py/duplicate-dict-key-variable
+```
+
+## How to fix
+
+1. Decide which entry is meant.
+2. Remove the other one, or use a different key.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+scores = {player: 1, player: 2}
+```
+
+#### Do
+
+```py
+scores = {player: 1, rival: 2}
+```

codelaw_rules_python/rules/py/duplicate-dict-key.md

@@ -0,0 +1,39 @@
+---
+id: py/duplicate-dict-key
+title: "A dict literal doesn't repeat a literal key"
+languages: [python]
+fix: manual
+fix_reason: "which value should win can't be known from the code"
+stability: preview
+ported_from: [ruff/F601]
+since: 0.1.0
+---
+
+A dict literal names each literal key (`"a"`, `1`, `True`) once.
+
+**Why:** Only the last value is kept, so the earlier one is silently lost.
+
+```codelaw
+native: py/duplicate-dict-key
+```
+
+## How to fix
+
+1. Decide which value the key should have.
+2. Remove the other entry, or give it its own key.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+colors = {"red": 1, "red": 2}
+```
+
+#### Do
+
+```py
+colors = {"red": 1, "blue": 2}
+```

codelaw_rules_python/rules/py/duplicate-handler-exception.md

@@ -0,0 +1,43 @@
+---
+id: py/duplicate-handler-exception
+title: "No exception listed twice in one handler"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/B014]
+since: 0.1.0
+---
+
+An `except` tuple names each exception once.
+
+**Why:** A repeated exception is redundant and often a typo for a different one.
+
+```codelaw
+native: py/duplicate-handler-exception
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except (ValueError, ValueError, TypeError):
+    retry()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except (ValueError, TypeError):
+    retry()
+```
+
+## Differences from the source
+
+Exceptions are compared by name as written; aliases such as `IOError` and `OSError` are not merged.

codelaw_rules_python/rules/py/duplicate-set-value.md

@@ -0,0 +1,33 @@
+---
+id: py/duplicate-set-value
+title: "No duplicate items in a set literal"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/B033]
+since: 0.1.0
+---
+
+A set literal lists each literal value once.
+
+**Why:** A repeated item is dropped silently and is often a typo for another value.
+
+```codelaw
+native: py/duplicate-set-value
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+colors = {"red", "green", "red"}
+```
+
+#### Do
+
+```py
+colors = {"red", "green"}
+```

codelaw_rules_python/rules/py/duplicate-try-block-exception.md

@@ -0,0 +1,47 @@
+---
+id: py/duplicate-try-block-exception
+title: "An exception is caught by one handler only"
+languages: [python]
+fix: manual
+fix_reason: "which handler's code is meant to run needs a person"
+stability: preview
+ported_from: [ruff/B025]
+since: 0.1.0
+---
+
+Within one `try` statement, each exception class appears in only one `except` clause.
+
+**Why:** Only the first matching handler runs, so the later one is dead code.
+
+```codelaw
+native: py/duplicate-try-block-exception
+```
+
+## How to fix
+
+1. Merge the handlers' code into the first one, or remove the dead one.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except ValueError:
+    retry()
+except ValueError:
+    log()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except ValueError:
+    retry()
+    log()
+```

codelaw_rules_python/rules/py/empty-method-without-abstract-decorator.md

@@ -0,0 +1,55 @@
+---
+id: py/empty-method-without-abstract-decorator
+title: "Empty methods in an abstract base class are abstract"
+languages: [python]
+fix: manual
+fix_reason: "whether the method is a required hook or an optional no-op is a design decision"
+stability: preview
+ported_from: [ruff/B027]
+since: 0.1.0
+---
+
+In a class that inherits from `ABC`, a method whose body is empty is marked `@abstractmethod`.
+
+**Why:** An empty, unmarked method lets subclasses forget to implement it.
+
+```codelaw
+native: py/empty-method-without-abstract-decorator
+```
+
+## How to fix
+
+1. Add `@abstractmethod` if subclasses must implement it.
+2. Otherwise give it a docstring saying it is an optional hook.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+from abc import ABC, abstractmethod
+
+
+class Shape(ABC):
+    @abstractmethod
+    def area(self): ...
+
+    def draw(self):
+        pass
+```
+
+#### Do
+
+```py
+from abc import ABC, abstractmethod
+
+
+class Shape(ABC):
+    @abstractmethod
+    def area(self): ...
+
+    @abstractmethod
+    def draw(self): ...
+```

codelaw_rules_python/rules/py/except-with-empty-tuple.md

@@ -0,0 +1,44 @@
+---
+id: py/except-with-empty-tuple
+title: "No `except ():`"
+languages: [python]
+fix: manual
+fix_reason: "the exceptions to catch are the author's choice"
+stability: preview
+ported_from: [ruff/B029]
+since: 0.1.0
+---
+
+An `except` clause doesn't name an empty tuple.
+
+**Why:** `except ():` catches nothing, so the handler never runs.
+
+```codelaw
+native: py/except-with-empty-tuple
+```
+
+## How to fix
+
+1. Name the exceptions to catch, or remove the handler.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except ():
+    log()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except ValueError:
+    log()
+```

codelaw_rules_python/rules/py/except-with-non-exception-classes.md

@@ -0,0 +1,44 @@
+---
+id: py/except-with-non-exception-classes
+title: "`except` names exception classes"
+languages: [python]
+fix: manual
+fix_reason: "the exception class to catch is the author's choice"
+stability: preview
+ported_from: [ruff/B030]
+since: 0.1.0
+---
+
+An `except` clause names exception classes (or tuples of them), not literals or other values.
+
+**Why:** Catching anything else raises `TypeError` the moment an exception reaches the handler.
+
+```codelaw
+native: py/except-with-non-exception-classes
+```
+
+## How to fix
+
+1. Replace the value with the exception class you meant to catch.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except "error":
+    log()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except RuntimeError:
+    log()
+```

codelaw_rules_python/rules/py/f-string-docstring.md

@@ -0,0 +1,40 @@
+---
+id: py/f-string-docstring
+title: "Docstrings aren't f-strings"
+languages: [python]
+fix: manual
+fix_reason: "the docstring's wording has to change to drop the placeholder"
+stability: preview
+ported_from: [ruff/B021]
+since: 0.1.0
+---
+
+The first statement of a module, class or function isn't an f-string meant as its docstring.
+
+**Why:** Python treats an f-string there as an expression, so `__doc__` stays empty.
+
+```codelaw
+native: py/f-string-docstring
+```
+
+## How to fix
+
+1. Remove the `f` prefix and write the text without placeholders.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def greet():
+    f"""Say hello to {NAME}."""
+```
+
+#### Do
+
+```py
+def greet():
+    """Say hello to the configured name."""
+```

codelaw_rules_python/rules/py/f-string-missing-placeholders.cases.md

@@ -0,0 +1,49 @@
+# py/f-string-missing-placeholders — cases
+
+### case: escaped braces become plain braces
+
+```py
+x = f"{{literal}}"
+```
+
+```expect
+1:5 py/f-string-missing-placeholders
+```
+
+```fixed
+x = "{literal}"
+```
+
+### case: one part of a concatenation has a placeholder
+
+```py
+x = f"a" f"{b}"
+```
+
+```expect
+(none)
+```
+
+### case: all parts lack placeholders
+
+```py
+x = (f"a" "b")
+```
+
+```expect
+1:6 py/f-string-missing-placeholders
+```
+
+```fixed
+x = ("a" "b")
+```
+
+### case: nested f-string in a format spec
+
+```py
+x = f"{v:{w}}"
+```
+
+```expect
+(none)
+```

codelaw_rules_python/rules/py/f-string-missing-placeholders.md

@@ -0,0 +1,33 @@
+---
+id: py/f-string-missing-placeholders
+title: "An f-string has a placeholder"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/F541]
+since: 0.1.0
+---
+
+A string with the `f` prefix contains at least one `{…}` placeholder.
+
+**Why:** Without one, the prefix does nothing and often means a placeholder was forgotten.
+
+```codelaw
+native: py/f-string-missing-placeholders
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+print(f"hello")
+```
+
+#### Do
+
+```py
+print("hello")
+```