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

codelaw_rules_python/rules/py/lambda-assignment.cases.md

@@ -0,0 +1,48 @@
+# py/lambda-assignment — cases
+
+### case: in a class body
+
+```py
+class C:
+    m = lambda self: 1
+```
+
+```expect
+2:5 py/lambda-assignment
+```
+
+```fixed
+class C:
+    def m(self):
+        return 1
+```
+
+### case: tuple targets are fine
+
+```py
+a, b = lambda: 0, 1
+```
+
+```expect
+(none)
+```
+
+### case: lambda as an argument
+
+```py
+items.sort(key=lambda x: x[1])
+```
+
+```expect
+(none)
+```
+
+### case: attribute targets are fine
+
+```py
+obj.handler = lambda: None
+```
+
+```expect
+(none)
+```

codelaw_rules_python/rules/py/lambda-assignment.md

@@ -0,0 +1,35 @@
+---
+id: py/lambda-assignment
+title: "Define functions with `def`, not a lambda"
+languages: [python]
+fix: suggest
+fix_reason: "an annotation on the assigned name is dropped by the rewrite"
+stability: preview
+ported_from: [ruff/E731]
+since: 0.1.0
+---
+
+A name is bound to a function with `def`, not by assigning a `lambda`.
+
+**Why:** A `def` has a real name in tracebacks, can have a docstring, and reads as a definition.
+
+```codelaw
+native: py/lambda-assignment
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+double = lambda x: x * 2
+```
+
+#### Do
+
+```py
+def double(x):
+    return x * 2
+```

codelaw_rules_python/rules/py/late-future-import.md

@@ -0,0 +1,40 @@
+---
+id: py/late-future-import
+title: "`from __future__` imports come first"
+languages: [python]
+fix: manual
+fix_reason: "moving statements above it can change the order the module runs in"
+stability: preview
+ported_from: [ruff/F404]
+since: 0.1.0
+---
+
+`from __future__ import …` statements come before any other statement except the module docstring.
+
+**Why:** Python rejects a late `__future__` import with a `SyntaxError`.
+
+```codelaw
+native: py/late-future-import
+```
+
+## How to fix
+
+1. Move the `from __future__` import to the top, after the docstring.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import os
+from __future__ import annotations
+```
+
+#### Do
+
+```py
+from __future__ import annotations
+import os
+```

codelaw_rules_python/rules/py/loop-variable-overrides-iterator.md

@@ -0,0 +1,41 @@
+---
+id: py/loop-variable-overrides-iterator
+title: "A loop variable doesn't replace what it iterates"
+languages: [python]
+fix: manual
+fix_reason: "the new name is the author's choice"
+stability: preview
+ported_from: [ruff/B020]
+since: 0.1.0
+---
+
+A `for` loop's target doesn't reuse a name read in the iterable expression.
+
+**Why:** After the loop the name holds the last item, not the collection, which breaks later uses.
+
+```codelaw
+native: py/loop-variable-overrides-iterator
+```
+
+## How to fix
+
+1. Give the loop variable its own name.
+2. Update its uses in the loop body.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+for items in items:
+    print(items)
+```
+
+#### Do
+
+```py
+for item in items:
+    print(item)
+```

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

@@ -0,0 +1,46 @@
+---
+id: py/map-without-explicit-strict
+title: "`map()` over several iterables says `strict=`"
+languages: [python]
+fix: suggest
+fix_reason: "`strict=` exists only from Python 3.14, 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.14 the rule is off" }
+ported_from: [ruff/B912]
+since: 0.1.0
+---
+
+`map()` with two or more iterables is called with `strict=True` or `strict=False`.
+
+**Why:** Without it, `map` silently stops at the shortest input. The keyword exists from Python 3.14.
+
+```codelaw
+native: py/map-without-explicit-strict
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+sums = map(add, xs, ys)
+```
+
+#### Do
+
+```py
+sums = map(add, xs, ys, strict=True)
+```
+
+#### Fixed
+
+```py
+sums = map(add, xs, ys, strict=False)
+```
+
+## Differences from the source
+
+The fix is `suggest` (`codelaw fix --unsafe`), not `auto`: the `target_version` option may be unset, and on Python before 3.14 the keyword raises `TypeError`.

codelaw_rules_python/rules/py/module-import-not-at-top.cases.md

@@ -0,0 +1,64 @@
+# py/module-import-not-at-top — cases
+
+### case: sys.path change before imports
+
+```py
+import sys
+sys.path.insert(0, 'lib')
+import local_module
+```
+
+```expect
+(none)
+```
+
+### case: os.environ change before imports
+
+```py
+import os
+os.environ['X'] = '1'
+import other
+```
+
+```expect
+(none)
+```
+
+### case: conditional imports
+
+```py
+try:
+    import ujson as json
+except ImportError:
+    import json
+import os
+```
+
+```expect
+(none)
+```
+
+### case: dunders and docstring
+
+```py
+"""Doc."""
+__all__ = []
+__version__ = '1'
+import os
+```
+
+```expect
+(none)
+```
+
+### case: imports inside functions are fine
+
+```py
+x = 1
+def f():
+    import os
+```
+
+```expect
+(none)
+```

codelaw_rules_python/rules/py/module-import-not-at-top.md

@@ -0,0 +1,46 @@
+---
+id: py/module-import-not-at-top
+title: "Module-level imports come first"
+languages: [python]
+fix: manual
+fix_reason: "moving an import above other code changes the order the module runs in"
+stability: preview
+ported_from: [ruff/E402]
+since: 0.1.0
+---
+
+Module-level imports come before other code. A docstring, `__future__` imports, dunder assignments (`__all__`, `__version__`), `if`/`try`/`with` blocks and changes to `sys.path` or `os.environ` may come before them.
+
+**Why:** Imports scattered through a module hide its dependencies, and code that runs before them can change what they load.
+
+```codelaw
+native: py/module-import-not-at-top
+```
+
+## How to fix
+
+1. Move the import up to the module's import section.
+2. If it must run after the code above it, keep it and suppress the finding with a comment saying why.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import os
+
+print(os.name)
+
+import sys
+```
+
+#### Do
+
+```py
+import os
+import sys
+
+print(os.name)
+```

codelaw_rules_python/rules/py/multiple-imports-on-one-line.md

@@ -0,0 +1,38 @@
+---
+id: py/multiple-imports-on-one-line
+title: "One module per `import` statement"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/E401]
+since: 0.1.0
+---
+
+Each `import` statement imports one module; `import os, sys` is split into one line per module.
+
+**Why:** One import per line keeps diffs and merges clean and lets import sorting work line by line.
+
+```codelaw
+native: py/multiple-imports-on-one-line
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import os, sys
+```
+
+#### Do
+
+```py
+import os
+import sys
+```
+
+## Differences from the source
+
+`from module import a, b` is not affected; it imports from one module.

codelaw_rules_python/rules/py/multiple-starred-expressions.md

@@ -0,0 +1,38 @@
+---
+id: py/multiple-starred-expressions
+title: "One starred target per assignment"
+languages: [python]
+fix: manual
+fix_reason: "which target should collect the rest has to be chosen"
+stability: preview
+ported_from: [ruff/F622]
+since: 0.1.0
+---
+
+An unpacking assignment has at most one starred target.
+
+**Why:** Two starred targets are ambiguous and a `SyntaxError`.
+
+```codelaw
+native: py/multiple-starred-expressions
+```
+
+## How to fix
+
+1. Keep the star on one target only.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+*head, *tail = values
+```
+
+#### Do
+
+```py
+head, *tail = values
+```

codelaw_rules_python/rules/py/mutable-contextvar-default.md

@@ -0,0 +1,42 @@
+---
+id: py/mutable-contextvar-default
+title: "No mutable `ContextVar` defaults"
+languages: [python]
+fix: manual
+fix_reason: "whether to use an immutable value or set a fresh one per context is a design choice"
+stability: preview
+ported_from: [ruff/B039]
+since: 0.1.0
+---
+
+A `ContextVar`'s `default=` isn't a list, dict, set or the result of a call.
+
+**Why:** The default is one object shared by every context, so mutating it leaks state between them.
+
+```codelaw
+native: py/mutable-contextvar-default
+```
+
+## How to fix
+
+1. Use an immutable default, or no default and set a fresh value in each context.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+from contextvars import ContextVar
+
+items = ContextVar("items", default=[])
+```
+
+#### Do
+
+```py
+from contextvars import ContextVar
+
+items = ContextVar("items", default=())
+```

codelaw_rules_python/rules/py/nested-star-import.md

@@ -0,0 +1,42 @@
+---
+id: py/nested-star-import
+title: "`import *` only at module level"
+languages: [python]
+fix: manual
+fix_reason: "the names to import must be chosen by reading the function"
+stability: preview
+ported_from: [ruff/F406]
+since: 0.1.0
+---
+
+`from module import *` appears only at the top level of a module.
+
+**Why:** Inside a function or class a star import is a `SyntaxError` in Python 3.
+
+```codelaw
+native: py/nested-star-import
+```
+
+## How to fix
+
+1. Replace the star with the names the function uses.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def paths():
+    from os.path import *
+    return join("a", "b")
+```
+
+#### Do
+
+```py
+def paths():
+    from os.path import join
+    return join("a", "b")
+```

codelaw_rules_python/rules/py/no-bare-except.cases.md

@@ -0,0 +1,37 @@
+# py/no-bare-except — cases
+
+### case: a handler that re-raises
+
+```py
+try:
+    run()
+except:
+    cleanup()
+    raise
+```
+
+```expect
+(none)
+```
+
+### case: a conditional re-raise still swallows
+
+```py
+try:
+    run()
+except:
+    if strict:
+        raise
+```
+
+```expect
+3:1 py/no-bare-except
+```
+
+```fixed
+try:
+    run()
+except Exception:
+    if strict:
+        raise
+```

codelaw_rules_python/rules/py/no-bare-except.md

@@ -0,0 +1,44 @@
+---
+id: py/no-bare-except
+title: "No bare `except:`"
+languages: [python]
+fix: suggest
+fix_reason: "`except Exception:` no longer catches `KeyboardInterrupt` and `SystemExit`"
+stability: preview
+ported_from: [ruff/E722]
+since: 0.1.0
+---
+
+Every `except` clause names the exceptions it handles.
+
+**Why:** A bare `except:` also catches `KeyboardInterrupt` and `SystemExit`, so Ctrl-C and `sys.exit()` stop working inside it.
+
+```codelaw
+native: py/no-bare-except
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+try:
+    run()
+except:
+    log()
+```
+
+#### Do
+
+```py
+try:
+    run()
+except Exception:
+    log()
+```
+
+## Differences from the source
+
+As in Ruff, a handler whose body re-raises with a bare `raise` is allowed: it doesn't swallow anything.

codelaw_rules_python/rules/py/no-explicit-stacklevel.md

@@ -0,0 +1,38 @@
+---
+id: py/no-explicit-stacklevel
+title: "`warnings.warn` sets `stacklevel`"
+languages: [python]
+fix: suggest
+fix_reason: "`stacklevel=2` is right for a warning about the caller; deeper helpers need a higher value"
+stability: preview
+ported_from: [ruff/B028]
+since: 0.1.0
+---
+
+`warnings.warn()` is called with `stacklevel=` (or `skip_file_prefixes=`).
+
+**Why:** The default `stacklevel=1` points the warning at the line inside your library, not at the caller who needs to change.
+
+```codelaw
+native: py/no-explicit-stacklevel
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+import warnings
+
+warnings.warn("old API")
+```
+
+#### Do
+
+```py
+import warnings
+
+warnings.warn("old API", stacklevel=2)
+```

codelaw_rules_python/rules/py/no-mutable-default.cases.md

@@ -0,0 +1,58 @@
+# py/no-mutable-default — cases
+
+### case: after a docstring
+
+```py
+def f(x={}):
+    """Doc."""
+    return x
+```
+
+```expect
+1:9 py/no-mutable-default
+```
+
+```fixed
+def f(x=None):
+    """Doc."""
+    if x is None:
+        x = {}
+    return x
+```
+
+### case: constructor calls
+
+```py
+def f(a=set(), b=dict(k=1), c=list()):
+    pass
+```
+
+```expect
+1:9 py/no-mutable-default
+1:18 py/no-mutable-default
+1:31 py/no-mutable-default
+```
+
+### case: a default that reads the outer name: no edit
+
+```py
+def outer(lnum):
+    def reader(lnum=[lnum]):
+        return lnum
+    return reader
+```
+
+```expect
+2:21 py/no-mutable-default
+```
+
+### case: immutable defaults
+
+```py
+def f(a=(), b=frozenset(), c=None, d=""):
+    pass
+```
+
+```expect
+(none)
+```

codelaw_rules_python/rules/py/no-mutable-default.md

@@ -0,0 +1,44 @@
+---
+id: py/no-mutable-default
+title: "No mutable default arguments"
+languages: [python]
+fix: suggest
+fix_reason: "callers that relied on the shared object, or passed `None` on purpose, behave differently"
+stability: preview
+ported_from: [ruff/B006]
+since: 0.1.0
+---
+
+A parameter's default isn't a list, dict or set (literal, comprehension or constructor call).
+
+**Why:** The default is created once, when the function is defined, and every call shares and mutates the same object.
+
+```codelaw
+native: py/no-mutable-default
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def append(item, items=[]):
+    items.append(item)
+    return items
+```
+
+#### Do
+
+```py
+def append(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+```
+
+## Differences from the source
+
+The fix is offered only for unannotated parameters whose default doesn't read the parameter's own name; Ruff also rewrites an annotation to `T | None`.