habit-hooks-python 1.0.0__tar.gz

habit_hooks_python-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Per-plugin Node tool deps (installed via npm ci; see plugins/*/package.json)
+node_modules/
+dist
+coverage
+.DS_Store
+.idea
+.claude-channel/
+*.tgz
+*.log
+.vscode/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.spec-runs/
+
+/ruff.toml
+
+# Workflow orchestration script (run from ~/.claude, never a repo deliverable)
+.claude/workflows-build-overnight.js

habit_hooks_python-1.0.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: habit-hooks-python
+Version: 1.0.0
+Summary: The Python Habit Hooks plugin
+Requires-Python: >=3.11

habit_hooks_python-1.0.0/docs/python-plugin.spec.md

@@ -0,0 +1,249 @@
+# The python plugin — acceptance
+
+The python plugin runs its sensors through the real `habit-sensors` pipeline.
+These cases run the **actual** tools (`ruff`, `deptry`) against a fixture with a
+known smell and assert the canonical finding comes out, mapped to the smell keys
+in [smell-vocabulary.md](smell-vocabulary.md).
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+```
+
+## ruff adapter maps rule IDs to canonical smells
+
+The `ruff` adapter selects `C901,PLR0913,PLR0915,F841,F401,BLE001` and a jq
+transform in its command groups the flat output into one finding per smell,
+stamping `source: "ruff:<code>"` on each issue. The shipped `ruff.toml` carries
+`max-args = 3`, so a four-argument function trips `PLR0913`.
+
+📄ruff.toml @plugins/python/src/habit_hooks_python/ruff.toml
+
+📄pyproject.toml
+```toml
+[project]
+name = "demo"
+version = "0.0.0"
+```
+
+📄billing.py
+```python
+import os
+
+
+def charge(a, b, c, d):
+    unused = 1
+    return a + b + c + d
+```
+
+```bash
+habit-sensors --all | jq 'sort_by(.smell)[] | {smell, language, key: (.issues[0].key | sub(".*/"; "")), line: .issues[0].details.line, source: .issues[0].details.source}'
+```
+
+🖥️ ✅
+```json
+{
+  "smell": "too-many-parameters",
+  "language": "python",
+  "key": "billing.py",
+  "line": 4,
+  "source": "ruff:PLR0913"
+}
+{
+  "smell": "unused-import",
+  "language": "python",
+  "key": "billing.py",
+  "line": 1,
+  "source": "ruff:F401"
+}
+{
+  "smell": "unused-variable",
+  "language": "python",
+  "key": "billing.py",
+  "line": 5,
+  "source": "ruff:F841"
+}
+```
+
+## ruff maps a syntax error to parse-error
+
+A file ruff cannot parse surfaces as `parse-error` (ruff reports it as
+`invalid-syntax`), not a null smell, so a broken file is still coached rather
+than silently mislabelled. This mirrors the TS plugin, where `eslint:fatal`
+maps to `parse-error`.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.deptry]
+disabled = true
+```
+
+📄ruff.toml @plugins/python/src/habit_hooks_python/ruff.toml
+
+📄broken.py
+```python
+def broken(:
+    return 1
+```
+
+```bash
+habit-sensors --all | jq '.[] | {smell, source: .issues[0].details.source}'
+```
+
+🖥️ ✅
+```json
+{
+  "smell": "parse-error",
+  "source": "ruff:invalid-syntax"
+}
+```
+
+## deptry sensor maps DEP002 to unused-dependency
+
+The `deptry` sensor runs deptry against a temp JSON report and shapes each
+`DEP002` (a declared but unused dependency) into an `unused-dependency` finding,
+one issue per module keyed by the module name.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.ruff]
+disabled = true
+```
+
+📄pyproject.toml
+```toml
+[project]
+name = "demo"
+version = "0.0.0"
+dependencies = ["requests", "rich"]
+```
+
+📄app.py
+```python
+import requests
+
+
+def fetch(url):
+    return requests.get(url).text
+```
+
+```bash
+habit-sensors --all | jq '.[] | {smell, language, key: .issues[0].key, file: .issues[0].details.file, source: .issues[0].details.source}'
+```
+
+🖥️ ✅
+```json
+{
+  "smell": "unused-dependency",
+  "language": "python",
+  "key": "rich",
+  "file": "pyproject.toml",
+  "source": "deptry:DEP002"
+}
+```
+
+## A crashing deptry fails the run, never reports clean
+
+deptry needs a `pyproject.toml` to analyse; without one it exits non-zero
+instead of emitting findings. The sensor must surface that as a failure — a
+crashed tool is never a clean run. The sensor exits with a code outside the
+findings range, so `habit-sensors` raises, names the sensor on stderr, and exits
+1 rather than printing an empty (false-clean) result.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.ruff]
+disabled = true
+```
+
+📄app.py
+```python
+def fetch(url):
+    return url
+```
+
+```bash
+habit-sensors --all
+```
+
+🖥️ ❌ 1
+```json
+[]
+```
+
+🚨
+```text
+habit-sensors: sensor 'deptry' failed: python ${dir}/deptry_sensor.py
+```
+
+## A crashing ruff fails the run, never reports clean
+
+The `ruff` sensor pipes the tool into `jq`. A crashing `ruff` (here, a malformed
+`ruff.toml` that makes the tool exit non-zero) prints nothing on stdout, so a
+naive pipe would let `jq` succeed on empty input and mask the crash as a false-
+clean run. The command sets `pipefail` so the tool's failing exit propagates
+through the pipe; `habit-sensors` then raises, names the sensor on stderr, and
+exits 1.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.deptry]
+disabled = true
+```
+
+📄ruff.toml
+```toml
+this is not = valid ruff config
+```
+
+📄app.py
+```python
+import os
+```
+
+```bash
+habit-sensors --all
+```
+
+🖥️ ❌ 1
+```json
+[]
+```
+
+🚨
+```text
+habit-sensors: sensor 'ruff' failed: set -o pipefail
+ruff check --output-format=json --select=C901,PLR0913,PLR0915,F841,F401,BLE001 ${files} | jq '
+  map(. + {smell: ({
+    "C901": "high-complexity",
+    "PLR0913": "too-many-parameters",
+    "PLR0915": "oversized-function",
+    "F841": "unused-variable",
+    "F401": "unused-import",
+    "BLE001": "swallowed-exception",
+    "invalid-syntax": "parse-error"
+  }[.code])})
+  | group_by(.smell)
+  | map({
+      smell: .[0].smell,
+      details: {},
+      issues: map({
+        key: .filename,
+        details: {
+          file: .filename,
+          line: .location.row,
+          column: .location.column,
+          message: .message,
+          source: ("ruff:" + .code)
+        }
+      })
+    })'
+```

habit_hooks_python-1.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "habit-hooks-python"
+version = "1.0.0"
+description = "The Python Habit Hooks plugin"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.entry-points."habit_hooks.plugins"]
+python = "habit_hooks_python"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/habit_hooks_python"]

habit_hooks_python-1.0.0/src/habit_hooks_python/__init__.py

@@ -0,0 +1 @@
+"""The python Habit Hooks plugin: package data discovered via the habit_hooks.plugins entry point."""

habit_hooks_python-1.0.0/src/habit_hooks_python/config.toml

@@ -0,0 +1,5 @@
+# Python plugin defaults.
+language = "python"
+files = ["**/*.py"]
+sensors = ["ruff", "deptry"]
+transformers = []

habit_hooks_python-1.0.0/src/habit_hooks_python/guides/high-complexity.md

@@ -0,0 +1,12 @@
+High cyclomatic complexity means one function is making too many decisions at once. The smell is not the number, it is that the function has quietly taken on more than one job. The count is the symptom, tangled responsibilities are the cause.
+
+{% include "includes/line_level_issues.md" %}
+Work through it in order:
+
+1. **Name what each branch is for.** Give every branch a one-sentence description of the responsibility it handles. If two branches describe the same thing, they belong together. If a branch has no clean name, that path probably wants its own function.
+2. **Lift the guards out first.** Turn early-exit conditions into guard clauses (`if not user: return None`) so the happy path stays flat and left-aligned. Most of the count is preconditions wrapped around the real work.
+3. **Change the shape, do not just move it.** When every branch is the same kind of decision, reshape it: a long `if/elif` on a value is often a dict dispatch or polymorphism, a nested loop often a comprehension or a generator. When polymorphism is not the right fit and the branches are genuinely separate jobs, extract one named method per branch, each named for the responsibility it handles. The goal is fewer decisions in one place, not the same tangle split into `_part1` / `_part2` behind worse names.
+
+Reducing the number without reducing the tangle is not a fix. Do not merge conditions with `and`/`or` just to drop a branch, and do not rewrite `if` statements as ternaries to slip under the check. ruff's mccabe does not count ternary expressions, so that trick lowers the score while a human still has to hold every condition in their head.
+
+The test is not whether the number dropped. It is whether someone reading the function for the first time can hold it in their head at once. If not, it is still doing too much.

habit_hooks_python-1.0.0/src/habit_hooks_python/guides/swallowed-exception.md

@@ -0,0 +1,12 @@
+A broad `except` (`except:`, `except Exception`, `except BaseException`) that discards the error silently is hiding a failure you have not understood, not handling one you planned for. Before you write it, name the specific error you expect and why. That one sentence is usually the fix.
+
+{% include "includes/line_level_issues.md" %}
+Work through it in order:
+
+1. **Catch only what you can name.** `ValueError`, `KeyError`, `TimeoutError`, whatever the call really raises. If you cannot name it, you are guessing, and every other error should stay free to surface where someone can see it.
+2. **Make the decision visible.** Recover from it, add context and re-raise (`raise ... from err`), or, at a boundary that has to stay alive, log the full traceback (`logging.exception(...)`) and continue. Logging and returning a default is a real option, not automatically a swallow.
+3. **The test is not whether you re-raised.** Ask one question: if this fires at 3am, will anyone know it happened, and will they know why? What turns a catch into a swallow is doing it blindly: a wide catch, no named error, nothing logged, the failure gone without a trace. If the answer is no, it is still a swallow, however you dressed it up.
+
+Narrowing the type or adding `# noqa` only to quiet ruff is not a fix if the error is still discarded.
+
+If you are unsure whether this catch is a real decision or a reflex, check with a human before you keep it.

habit_hooks_python-1.0.0/src/habit_hooks_python/ruff.toml

@@ -0,0 +1,6 @@
+[lint.mccabe]
+max-complexity = 10
+
+[lint.pylint]
+max-args = 3
+max-statements = 12

habit_hooks_python-1.0.0/src/habit_hooks_python/sensors/deptry.toml

@@ -0,0 +1 @@
+command = "python ${dir}/deptry_sensor.py"

habit_hooks_python-1.0.0/src/habit_hooks_python/sensors/deptry_sensor.py

@@ -0,0 +1,70 @@
+"""Run deptry and print ``unused-dependency`` findings.
+
+deptry's stdout is unreliable when piped, so this wrapper runs it against a temp
+JSON report, reads that report, and shapes each ``DEP002`` (a declared but unused
+dependency) into the canonical finding.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def run_deptry(report: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["deptry", ".", "--json-output", str(report)],
+        capture_output=True,
+        text=True,
+    )
+
+
+def deptry_crashed(result: subprocess.CompletedProcess[str], report: Path) -> bool:
+    return result.returncode not in (0, 1) or not report.is_file()
+
+
+def unused_dependencies(report: Path) -> list[dict]:
+    entries = json.loads(report.read_text())
+    return [entry for entry in entries if entry["error"]["code"] == "DEP002"]
+
+
+def issue(entry: dict) -> dict:
+    return {
+        "key": entry["module"],
+        "details": {
+            "module": entry["module"],
+            "file": entry["location"]["file"],
+            "message": entry["error"]["message"],
+            "source": "deptry:DEP002",
+        },
+    }
+
+
+def findings(entries: list[dict]) -> list[dict]:
+    if not entries:
+        return []
+    return [
+        {
+            "smell": "unused-dependency",
+            "details": {},
+            "issues": [issue(entry) for entry in entries],
+        }
+    ]
+
+
+def main() -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        report = Path(tmp) / "deptry-report.json"
+        result = run_deptry(report)
+        if deptry_crashed(result, report):
+            sys.stderr.write(result.stderr)
+            return 2
+        print(json.dumps(findings(unused_dependencies(report))))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

habit_hooks_python-1.0.0/src/habit_hooks_python/sensors/ruff.toml

@@ -0,0 +1,28 @@
+command = """
+set -o pipefail
+ruff check --output-format=json --select=C901,PLR0913,PLR0915,F841,F401,BLE001 ${files} | jq '
+  map(. + {smell: ({
+    "C901": "high-complexity",
+    "PLR0913": "too-many-parameters",
+    "PLR0915": "oversized-function",
+    "F841": "unused-variable",
+    "F401": "unused-import",
+    "BLE001": "swallowed-exception",
+    "invalid-syntax": "parse-error"
+  }[.code])})
+  | group_by(.smell)
+  | map({
+      smell: .[0].smell,
+      details: {},
+      issues: map({
+        key: .filename,
+        details: {
+          file: .filename,
+          line: .location.row,
+          column: .location.column,
+          message: .message,
+          source: ("ruff:" + .code)
+        }
+      })
+    })'
+"""