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

codelaw_rules_python/rules/py/no-print.cases.md

@@ -0,0 +1,40 @@
+# py/no-print — cases
+
+### case: adds the import
+
+```py
+def run():
+    print("x")
+```
+
+```expect
+2:5 py/no-print
+```
+
+```fixed
+import logging
+def run():
+    logging.getLogger(__name__).info("%s", "x")
+```
+
+### case: several arguments: no edit
+
+```py
+print("a", 1)
+```
+
+```expect
+1:1 py/no-print
+```
+
+### case: a local print function
+
+```py
+def print(x):
+    pass
+print(1)
+```
+
+```expect
+(none)
+```

codelaw_rules_python/rules/py/no-print.md

@@ -0,0 +1,42 @@
+---
+id: py/no-print
+title: "No `print()` in library code"
+languages: [python]
+files: ["src/**"]
+fix: suggest
+fix_reason: "the log level, and whether the output was meant for the user, need a person"
+stability: preview
+since: 0.1.0
+---
+
+Code under `src/` reports through `logging`, not `print()`.
+
+**Why:** `print` writes to standard output whether or not the caller wants it; a logger can be filtered, redirected and silenced.
+
+```codelaw
+native: py/no-print
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py path=src/app.py
+import logging
+
+
+def run():
+    print("started")
+```
+
+#### Do
+
+```py path=src/app.py
+import logging
+
+
+def run():
+    logging.getLogger(__name__).info("%s", "started")
+```

codelaw_rules_python/rules/py/no-star-import.cases.md

@@ -0,0 +1,11 @@
+# py/no-star-import — cases
+
+### case: relative star import re-exports
+
+```py
+from .core import *
+```
+
+```expect
+(none)
+```

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

@@ -0,0 +1,47 @@
+---
+id: py/no-star-import
+title: "No `from module import *`"
+languages: [python]
+fix: manual
+fix_reason: "which names the module needs can only be found by reading its uses"
+stability: preview
+ported_from: [ruff/F403]
+since: 0.1.0
+---
+
+Modules import the names they use explicitly instead of `from module import *`.
+
+**Why:** A star import hides where names come from, can silently replace local names, and stops a linter from finding undefined names.
+
+```codelaw
+native: py/no-star-import
+```
+
+## How to fix
+
+1. List the names the module uses from the star-imported module.
+2. Replace the star with those names.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+from os.path import *
+
+print(join("a", "b"))
+```
+
+#### Do
+
+```py
+from os.path import join
+
+print(join("a", "b"))
+```
+
+## Differences from the source
+
+Relative star imports (`from .sub import *`) are not reported: that is how a package re-exports its submodules' API, and Ruff leaves them alone in `__init__.py`.

codelaw_rules_python/rules/py/no-tunable-literals.cases.md

@@ -0,0 +1,54 @@
+# py/no-tunable-literals — cases
+
+### case: default parameter
+
+```py
+def connect(host, retries=5):
+    pass
+```
+
+```expect
+1:19 py/no-tunable-literals
+```
+
+### case: module constant is the config point
+
+```py
+TIMEOUT = 30
+```
+
+```expect
+(none)
+```
+
+### case: zero and one are fine
+
+```py
+get(url, timeout=0)
+loop(max_items=1)
+```
+
+```expect
+(none)
+```
+
+### case: unrelated names
+
+```py
+resize(width=640)
+```
+
+```expect
+(none)
+```
+
+### case: local assignment
+
+```py
+def f():
+    max_size = 1024
+```
+
+```expect
+2:5 py/no-tunable-literals
+```

codelaw_rules_python/rules/py/no-tunable-literals.md

@@ -0,0 +1,58 @@
+---
+id: py/no-tunable-literals
+title: "No hard-coded timeouts, limits or thresholds"
+languages: [python]
+fix: manual
+fix_reason: "which configuration key holds the value is the author's choice"
+stability: preview
+since: 0.1.0
+---
+
+A number passed as, defaulted to or assigned to a setting whose name says it is tunable (`timeout`, `retries`, `max_*`, `limit`, `threshold`, `interval`, `delay`, `ttl`, `backoff`, `deadline`, …) comes from configuration, not a literal in the code. `0` and `1` are allowed, and so are module-level `UPPER_CASE` constants, the one place such a value may be written down.
+
+**Why:** Tunable values buried in code can't be changed per environment without a release, and the same number drifts apart in several places.
+
+```codelaw
+match:
+  any:
+    - all:
+        - kind: keyword_argument
+        - has: { field: name, regex: '(?i)(^|_)(timeouts?|retries|retry|attempts|limit|threshold|interval|delay|ttl|backoff|deadline|max|min|maximum|minimum)(_|$)' }
+        - has: { field: value, any: [{ kind: integer }, { kind: float }], not: { regex: '^(0|1|0\.0|1\.0)$' } }
+    - all:
+        - any: [{ kind: default_parameter }, { kind: typed_default_parameter }]
+        - has: { field: name, regex: '(?i)(^|_)(timeouts?|retries|retry|attempts|limit|threshold|interval|delay|ttl|backoff|deadline|max|min|maximum|minimum)(_|$)' }
+        - has: { field: value, any: [{ kind: integer }, { kind: float }], not: { regex: '^(0|1|0\.0|1\.0)$' } }
+    - all:
+        - kind: assignment
+        - has: { field: left, kind: identifier, regex: '(?i)(^|_)(timeouts?|retries|retry|attempts|limit|threshold|interval|delay|ttl|backoff|deadline|max|min|maximum|minimum)(_|$)', not: { regex: '^[A-Z0-9_]+$' } }
+        - has: { field: right, any: [{ kind: integer }, { kind: float }], not: { regex: '^(0|1|0\.0|1\.0)$' } }
+message: "This tunable value is hard-coded; read it from configuration"
+```
+
+## How to fix
+
+1. Pick or add a configuration key for the value.
+2. Read the value from configuration where it is used.
+3. For a fixed protocol constant, name it as a module-level `UPPER_CASE` constant instead.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+def fetch(url):
+    return get(url, timeout=30)
+```
+
+#### Do
+
+```py
+from config import settings
+
+
+def fetch(url):
+    return get(url, timeout=settings.http_timeout)
+```

codelaw_rules_python/rules/py/none-comparison.md

@@ -0,0 +1,36 @@
+---
+id: py/none-comparison
+title: "Compare with `None` using `is`"
+languages: [python]
+fix: suggest
+fix_reason: "an object whose `__eq__` treats itself as equal to `None` would compare differently"
+stability: preview
+ported_from: [ruff/E711]
+since: 0.1.0
+---
+
+Comparisons with `None` use `is` / `is not`, not `==` / `!=`.
+
+**Why:** `None` is a singleton; `==` calls the other object's `__eq__`, which may not return what you expect.
+
+```codelaw
+native: py/none-comparison
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+if user == None:
+    login()
+```
+
+#### Do
+
+```py
+if user is None:
+    login()
+```

codelaw_rules_python/rules/py/not-in-test.md

@@ -0,0 +1,35 @@
+---
+id: py/not-in-test
+title: "Write `x not in y`"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/E713]
+since: 0.1.0
+---
+
+A membership test is negated as `x not in y`, not `not x in y`.
+
+**Why:** `not x in y` reads as `(not x) in y`; `not in` says what is meant.
+
+```codelaw
+native: py/not-in-test
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+if not item in seen:
+    keep(item)
+```
+
+#### Do
+
+```py
+if item not in seen:
+    keep(item)
+```

codelaw_rules_python/rules/py/not-is-test.md

@@ -0,0 +1,35 @@
+---
+id: py/not-is-test
+title: "Write `x is not y`"
+languages: [python]
+fix: auto
+stability: preview
+ported_from: [ruff/E714]
+since: 0.1.0
+---
+
+An identity test is negated as `x is not y`, not `not x is y`.
+
+**Why:** `not x is y` reads as `(not x) is y`; `is not` says what is meant.
+
+```codelaw
+native: py/not-is-test
+```
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+if not value is None:
+    use(value)
+```
+
+#### Do
+
+```py
+if value is not None:
+    use(value)
+```

codelaw_rules_python/rules/py/percent-format-count-mismatch.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-count-mismatch
+title: "A `%` format string gets one value per placeholder"
+languages: [python]
+fix: manual
+fix_reason: "which value is missing, or extra, can't be inferred"
+stability: preview
+ported_from: [ruff/F507]
+since: 0.1.0
+---
+
+The tuple (or single literal) formatted into a `%` string has as many values as the string has positional placeholders.
+
+**Why:** Too few values raise `TypeError: not enough arguments`; too many raise `TypeError: not all arguments converted`.
+
+```codelaw
+native: py/percent-format-count-mismatch
+```
+
+## How to fix
+
+1. Add or remove values, or placeholders, until they match.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%s is %s" % ("Ada",)
+```
+
+#### Do
+
+```py
+message = "%s is %s" % ("Ada", 36)
+```

codelaw_rules_python/rules/py/percent-format-expected-mapping.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-expected-mapping
+title: "Named `%` placeholders get a mapping"
+languages: [python]
+fix: manual
+fix_reason: "the key each value belongs to isn't written anywhere"
+stability: preview
+ported_from: [ruff/F502]
+since: 0.1.0
+---
+
+A `%` format string with named placeholders (`%(name)s`) is applied to a mapping, not a tuple.
+
+**Why:** Python raises `TypeError: format requires a mapping`.
+
+```codelaw
+native: py/percent-format-expected-mapping
+```
+
+## How to fix
+
+1. Pass a dict whose keys are the placeholder names.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%(name)s" % ("Ada",)
+```
+
+#### Do
+
+```py
+message = "%(name)s" % {"name": "Ada"}
+```

codelaw_rules_python/rules/py/percent-format-expected-sequence.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-expected-sequence
+title: "Positional `%` placeholders get a tuple"
+languages: [python]
+fix: manual
+fix_reason: "the order of the values isn't written anywhere"
+stability: preview
+ported_from: [ruff/F503]
+since: 0.1.0
+---
+
+A `%` format string with two or more positional placeholders is applied to a tuple, not a dict.
+
+**Why:** A dict is a single value, so Python raises `TypeError: not enough arguments`.
+
+```codelaw
+native: py/percent-format-expected-sequence
+```
+
+## How to fix
+
+1. Pass a tuple with one value per placeholder, or switch to named placeholders.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%s and %s" % {"a": 1, "b": 2}
+```
+
+#### Do
+
+```py
+message = "%s and %s" % (1, 2)
+```

codelaw_rules_python/rules/py/percent-format-invalid.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-invalid
+title: "A `%` format string is complete"
+languages: [python]
+fix: manual
+fix_reason: "the intended placeholder can't be inferred"
+stability: preview
+ported_from: [ruff/F501]
+since: 0.1.0
+---
+
+A string formatted with `%` has no unfinished placeholder such as `%(name` or a trailing `%`.
+
+**Why:** Python raises `ValueError` when the string is formatted.
+
+```codelaw
+native: py/percent-format-invalid
+```
+
+## How to fix
+
+1. Finish the placeholder (`%(name)s`) or escape a literal percent as `%%`.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%(name" % {"name": "Ada"}
+```
+
+#### Do
+
+```py
+message = "%(name)s" % {"name": "Ada"}
+```

codelaw_rules_python/rules/py/percent-format-missing-argument.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-missing-argument
+title: "Every named `%` placeholder has a value"
+languages: [python]
+fix: manual
+fix_reason: "the value for the missing key has to be supplied"
+stability: preview
+ported_from: [ruff/F505]
+since: 0.1.0
+---
+
+A dict literal formatted into a `%` string has a key for every named placeholder.
+
+**Why:** A missing key raises `KeyError` when the string is formatted.
+
+```codelaw
+native: py/percent-format-missing-argument
+```
+
+## How to fix
+
+1. Add the missing key to the dict, or remove the placeholder.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%(name)s is %(age)s" % {"name": "Ada"}
+```
+
+#### Do
+
+```py
+message = "%(name)s is %(age)s" % {"name": "Ada", "age": 36}
+```

codelaw_rules_python/rules/py/percent-format-mixed-placeholders.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-mixed-placeholders
+title: "A `%` format string doesn't mix positional and named placeholders"
+languages: [python]
+fix: manual
+fix_reason: "which style the string should use is the author's choice"
+stability: preview
+ported_from: [ruff/F506]
+since: 0.1.0
+---
+
+A `%` format string uses either positional placeholders (`%s`) or named ones (`%(name)s`), not both.
+
+**Why:** Python can't fill both from one right-hand side and raises `TypeError`.
+
+```codelaw
+native: py/percent-format-mixed-placeholders
+```
+
+## How to fix
+
+1. Name every placeholder, or make every placeholder positional.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%(name)s is %s" % {"name": "Ada"}
+```
+
+#### Do
+
+```py
+message = "%(name)s is %(age)s" % {"name": "Ada", "age": 36}
+```

codelaw_rules_python/rules/py/percent-format-star-requires-sequence.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-star-requires-sequence
+title: "A `*` width in a `%` format takes a tuple"
+languages: [python]
+fix: manual
+fix_reason: "the order of the values has to be decided"
+stability: preview
+ported_from: [ruff/F508]
+since: 0.1.0
+---
+
+A `%` format string using `*` for a width or precision is applied to a tuple.
+
+**Why:** The `*` takes its value from the next positional argument, which a mapping doesn't have.
+
+```codelaw
+native: py/percent-format-star-requires-sequence
+```
+
+## How to fix
+
+1. Pass a tuple with the width before the value.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%*d" % {"width": 5, "value": 1}
+```
+
+#### Do
+
+```py
+message = "%*d" % (5, 1)
+```

codelaw_rules_python/rules/py/percent-format-unsupported-character.md

@@ -0,0 +1,38 @@
+---
+id: py/percent-format-unsupported-character
+title: "A `%` format uses known conversions"
+languages: [python]
+fix: manual
+fix_reason: "the intended conversion can't be inferred"
+stability: preview
+ported_from: [ruff/F509]
+since: 0.1.0
+---
+
+Each `%` placeholder ends with a conversion Python knows (`s`, `r`, `a`, `d`, `f`, `x`, …).
+
+**Why:** An unknown conversion raises `ValueError: unsupported format character`.
+
+```codelaw
+native: py/percent-format-unsupported-character
+```
+
+## How to fix
+
+1. Use the conversion you meant, or escape a literal percent as `%%`.
+
+## Examples
+
+### Python
+
+#### Don't
+
+```py
+message = "%y" % (1,)
+```
+
+#### Do
+
+```py
+message = "%s" % (1,)
+```