codehound 1.4.2__tar.gz → 1.6.0__tar.gz

{codehound-1.4.2 → codehound-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.4.2
+Version: 1.6.0
 Summary: An AST-based static analyzer that hunts real correctness and async-safety bugs in Python code.
 Project-URL: Homepage, https://github.com/kratos0718/codehound
 Project-URL: Issues, https://github.com/kratos0718/codehound/issues
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">codehound</h1>
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty checks, seven backed by a bug that was actually found and merged into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~20-framework validation corpus instead of just reasoned about.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty-eight checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
 
 [![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codehound.svg)](https://pypi.org/project/codehound/)
@@ -71,7 +71,7 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 pip install codehound
 ```
 
-Zero dependencies — it's ~2,200 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
+Zero dependencies — it's ~3,200 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
 
 <details>
 <summary>From a clone instead (for development)</summary>
@@ -132,7 +132,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.4.2
+    rev: v1.6.0
     hooks:
       - id: codehound
 ```
@@ -153,7 +153,7 @@ repos:
 | **CH008** | `asyncio-run-in-running-loop` | `asyncio.run(...)` called from inside an `async def` — always raises `RuntimeError`, immediately, every time. | hardening rule — zero corpus hits (see below) |
 | **CH009** | `floating-thread` | A non-daemon `threading.Thread` that's `.start()`ed but never `.join()`ed — the thread analog of CH006. | hardening rule — see below |
 | **CH010** | `loop-closure-capture` | A `lambda` inside a `for` loop (or comprehension) that's *stored* (appended, assigned, returned) and captures the loop variable by reference — every stored instance ends up sharing the loop's **final** value. | **accelerate** (HuggingFace) — `MegatronEngine.get_module_config`'s `param_sync_func` list, PR #4273 |
-| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup |
+| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup; **litellm** — `Router._cached_get_model_group_info` leaked every `Router` even after its own documented `discard()` cleanup |
 | **CH012** | `floating-process` | A non-daemon `multiprocessing.Process` that's `.start()`ed but never `.join()`ed — the process analog of CH009. | hardening rule |
 | **CH013** | `discarded-future` | `ThreadPoolExecutor`/`ProcessPoolExecutor.submit(...)` called as a bare statement — the returned `Future` (and any exception raised inside the submitted work) is silently discarded. | hardening rule — real hits in litellm, accelerate, langchain |
 | **CH014** | `unprotected-lock-acquire` | `lock.acquire()` outside a `with`, whose matching `.release()` isn't inside a `finally:` — an exception between acquire and release deadlocks every future caller of that lock. | hardening rule — real hits in vllm, accelerate, torchtune |
@@ -163,10 +163,18 @@ repos:
 | **CH018** | `removed-asyncio-task-methods` | `asyncio.Task.current_task()` / `.all_tasks()` — both removed in Python 3.9; use `asyncio.current_task()` / `asyncio.all_tasks()`. | hardening rule |
 | **CH019** | `removed-getargspec` | `inspect.getargspec(...)` — removed in Python 3.11 after a decade-plus deprecation; use `inspect.signature(...)`. | hardening rule |
 | **CH020** | `bare-except` | A bare `except:` (or unused `except BaseException:`) — also catches `KeyboardInterrupt`/`SystemExit`, so Ctrl-C stops working and `sys.exit()` gets silently absorbed. | hardening rule — real hits in agno, llama_index, marimo, litellm |
+| **CH021** | `removed-stdlib-module` | `import distutils` (removed 3.12) or any of the 19 PEP 594 "dead battery" modules (`cgi`, `imghdr`, `telnetlib`, `nntplib`, …, removed 3.13) — `ImportError` the moment the module loads. | hardening rule — real hit in agno (already guarded, see below) |
+| **CH022** | `removed-asyncio-coroutine-decorator` | `@asyncio.coroutine` — removed in Python 3.11 after a generator-based-coroutine bridge that predates `async def`; `AttributeError` the moment the decorator line runs. | hardening rule |
+| **CH023** | `removed-stdlib-attribute` | A specific removed function on a module that still imports fine — `time.clock()` (3.8), `platform.linux_distribution()`/`.dist()` (3.8), `cgi.escape()` (3.8), `base64.encodestring()`/`.decodestring()` (3.9). | hardening rule — real hit in scikit-learn |
+| **CH024** | `unittest-deprecated-alias` | `self.assertEquals(...)`/`self.failUnless(...)` and a dozen other legacy `unittest.TestCase` aliases — removed in Python 3.12. | hardening rule |
+| **CH025** | `is-literal-comparison` | `x is 1000` / `x is not "foo"` — `is` checks identity, not equality; relies on CPython's small-int caching / string interning, neither guaranteed. (pyflakes F632) | hardening rule — real false positive fixed in litellm's own code, see below |
+| **CH026** | `mutable-class-attribute` | `class C: items = []` mutated via `self.items.append(...)` without ever being reassigned per instance — every instance shares and mutates the *same* list. | **vllm**, **llama_index**, **optuna**, **transformers** — see below |
+| **CH027** | `unwaited-subprocess` | `subprocess.Popen(...)` never `.wait()`ed/`.communicate()`d with, and not context-managed — risks a zombie process and a full pipe buffer deadlocking the child. | hardening rule — real hit in dspy (already handled, see below) |
+| **CH028** | `floating-timer` | `threading.Timer(...)` started but never `.cancel()`ed or handed off — nothing can stop the callback from firing later, on stale context. | hardening rule — real hits in marimo, transformers |
 
 `codehound list` prints this from the source of truth.
 
-CH007-CH020 don't have found-and-merged bugs behind all of them the way
+CH007-CH028 don't have found-and-merged bugs behind all of them the way
 CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
 tracked down first. CH010 and CH011 are the exceptions: both found
@@ -210,20 +218,28 @@ it's very unlikely to survive basic testing; CH007 and CH009 both only
 match same-file names by design, and most real cases of either are
 plausibly cross-module.
 
-**The optuna and llama_index finds (CH011):** both are `@lru_cache(maxsize=
-None)` decorating an instance method - a strong reference to `self`
-retained forever. In optuna, `_FanovaTree`'s node-lookup methods leak
-every tree built for a `get_param_importances()` call (one per
-random-forest estimator). In llama_index, `VectaraIndex._get_corpus_key`
-leaks the index itself - and since `VectaraIndex.__del__` exists
-specifically to close the index's `requests.Session` on garbage
-collection, the leak silently disables that cleanup too, so an HTTP
-session leaks along with every index. Both fixed the same way: move the
-cache from a class-level decorator to a per-instance one built in
-`__init__`, so it's freed with the instance instead of outliving it. Both
-have a regression test verified to fail pre-fix and pass post-fix.
+**The optuna, llama_index, and litellm finds (CH011):** all three are
+`@lru_cache(maxsize=None)` (or a fixed `maxsize`) decorating an instance
+method - a strong reference to `self` retained for the life of the
+process. In optuna, `_FanovaTree`'s node-lookup methods leak every tree
+built for a `get_param_importances()` call (one per random-forest
+estimator). In llama_index, `VectaraIndex._get_corpus_key` leaks the
+index itself - and since `VectaraIndex.__del__` exists specifically to
+close the index's `requests.Session` on garbage collection, the leak
+silently disables that cleanup too, so an HTTP session leaks along with
+every index. In litellm, `Router._cached_get_model_group_info` leaks
+every `Router` that's ever served a request through it - proved this
+survives even a correctly-called `router.discard()` (Router's own
+documented cleanup method), so it isn't a "you forgot to clean up" bug.
+All three fixed the same way: move the cache from a class-level decorator
+to a per-instance one built in `__init__`, so it's freed with the
+instance instead of outliving it - the exact pattern litellm's own
+`cached_deployment_model_info` sibling method already used, just not yet
+applied to this one. Each has a regression test verified to fail pre-fix
+and pass post-fix.
 PRs: [optuna/optuna#6859](https://github.com/optuna/optuna/pull/6859),
-[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089).
+[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089),
+[BerriAI/litellm#41582](https://github.com/BerriAI/litellm/pull/41582).
 
 **A third CH011 shape needed a guard instead of a PR:** dspy's `Image` (a
 pydantic model) caches `format()` the same way, but `Image` is frozen
@@ -247,6 +263,74 @@ as escaped when it's returned as part of a tuple/list or passed as an
 argument to any call. A full corpus rescan afterward found zero remaining
 CH016 hits.
 
+**CH021 did the same thing twice, minutes apart.** The first real-corpus
+scan found a false positive in vllm - `from .chunk import
+chunk_gated_delta_rule`, a relative import of vllm's own local `chunk.py`
+sibling module, not the removed stdlib `chunk`. `ast.ImportFrom.module`
+is `"chunk"` either way; only `node.level` (the leading-dot count) tells
+a relative import apart from an absolute one, and the check wasn't
+checking it. Fixed, rescanned, and found a *second* false positive in
+agno: `try: import imghdr except ImportError: import filetype` - a
+real, deliberate fallback that already anticipates this exact removal,
+not a bug waiting to happen. Added a second guard: skip an import inside
+a `try:` body whose `except` catches `ImportError` (or anything
+broader). A full corpus rescan after both fixes found zero remaining
+CH021 hits.
+
+**CH026 found four real, previously-unreported bugs on its first real
+scan.** All four are the exact same shape: a class-level mutable default
+(`items = []`) mutated in place via `self.items.append(...)` (or
+subscript assignment) with no per-instance reassignment anywhere, so
+every instance of the class shares and corrupts the *same* object. In
+vllm's `AXK1ForCausalLM`, `self.packed_modules_mapping["qkv_proj"] =
+[...]` patches a routing table shared by every instance of the model
+class. In llama_index's `ZapierToolSpec`, `self.spec_functions.append(...)`
+means a second tool-spec instance (a different API key, a different
+user) inherits every action name the first instance ever registered. In
+optuna's CLI `_Studies` command, `self._study_list_header.append(...)`
+does the same to a table-header list. In HuggingFace transformers'
+`CodeGenTokenizer`, `self.model_input_names.append("token_type_ids")`
+means constructing one tokenizer with `return_token_type_ids=True`
+silently changes what field every *other* `CodeGenTokenizer` instance in
+the same process expects, regardless of how it was configured - exactly
+the "spooky action at a distance" class of bug this project exists to
+catch. None have PRs yet: vllm and transformers both require AI-assisted
+PRs to carry an explicit disclosure, which this project's own policy
+doesn't do, so those two are documented here rather than filed.
+
+**CH028 hit the exact same name-collision problem CH018/CH022 already
+had a guard for, because that guard didn't get reused.** The very first
+corpus scan came back with ~30 hits, almost all in agno - which doesn't
+use `threading.Timer` at all. `from agno.utils.timer import Timer` is
+agno's own unrelated stopwatch class, called as `Timer()` with zero
+arguments (real `threading.Timer` requires `interval` and `function` and
+would raise `TypeError` immediately). Fixed by requiring `from threading
+import Timer` before trusting a bare `Timer(...)` call - the same guard
+already built for CH022's `coroutine` minutes earlier in the same
+session, just not applied here the first time. Also missed CH009's
+`daemon=True` escape entirely (found in weaviate-python-client's
+watchdog timer, `_timeout_timer.daemon = True`, a deliberate
+"outlive the caller" choice) - added both a constructor-kwarg and a
+post-construction-assignment check for it, matching CH009 exactly. Real
+hits remain in marimo (a non-daemon browser-opening timer, never
+cancelled) and transformers (a chained, never-captured checkpoint-retry
+timer).
+
+**CH025 and CH027 each found one real bug in the first scan, and one
+real gap in the check.** CH025 (is-literal-comparison) flagged litellm's
+`if "usage" in response_obj is not None:` - but for the wrong reason.
+`ast.Compare` puts every operand and every op from a chained comparison
+in one node; checking "is there a literal anywhere" and "is there an
+`is`/`is not` anywhere" independently, without pairing each op with its
+own adjacent operands, matched the string literal (paired with `in`)
+against the wrong op (`is not`, actually comparing `response_obj` to the
+allowed singleton `None`). Fixed by walking the chain as adjacent
+`(left, op, right)` triples. CH027 (unwaited-subprocess) flagged dspy's
+`process = subprocess.Popen(...)`, followed by `lm.process = process` -
+a real hand-off to a different object, reaped later through a separate
+`terminate_process(lm.process)` call, the same "stored as any object's
+attribute" escape CH009/CH016/CH028 already needed. Added it.
+
 **Two checks we built and did not ship.** `exception-chaining` (`except X
 as e: raise Y(...)` with no `from e`, discarding the real traceback -
 overlaps flake8-bugbear B904) worked exactly as designed, but at a scale
@@ -302,12 +386,20 @@ codehound/
     ├── collections_abc_import.py (CH017)
     ├── removed_asyncio_task_methods.py (CH018)
     ├── removed_getargspec.py   (CH019)
-    └── bare_except.py          (CH020)
+    ├── bare_except.py          (CH020)
+    ├── removed_stdlib_module.py (CH021)
+    ├── asyncio_coroutine_decorator.py (CH022)
+    ├── removed_stdlib_attribute.py (CH023)
+    ├── unittest_deprecated_alias.py (CH024)
+    ├── is_literal_comparison.py (CH025)
+    ├── mutable_class_attribute.py (CH026)
+    ├── unwaited_subprocess.py  (CH027)
+    └── floating_timer.py       (CH028)
 ```
 
 Each check receives a parsed `ast` tree plus the precomputed parent map and returns `Finding`s. Adding a rule is one file + one registry line + a test. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a full walkthrough of the engine, the parent map, and the design decisions.
 
-**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
+**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. CH025 pairs each chained comparison's op with only its own adjacent operands, rather than matching a literal and an `is`/`is not` anywhere in the same chain independently — a real pattern found in litellm. CH027 and CH028 both recognize a handle stored as *any* object's attribute as a hand-off, matching CH009/CH016's precedent — real patterns found in dspy and weaviate-python-client respectively. CH028 also only trusts a bare `Timer(...)` when `from threading import Timer` was actually seen — real hits in agno were its own unrelated stopwatch class. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -337,6 +429,11 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [x] 20 checks — memory leaks (`lru_cache` on methods), floating processes,
       discarded futures, unprotected locks, async properties, unclosed
       sockets, removed-in-3.9/3.10/3.11 stdlib APIs, bare `except:` — CH011-CH020
+- [x] 22 checks — removed stdlib modules (`distutils`, PEP 594 "dead
+      batteries"), removed `@asyncio.coroutine` decorator — CH021-CH022
+- [x] 28 checks — removed stdlib functions, deprecated unittest aliases,
+      `is`-literal comparisons, mutable class attributes, unwaited
+      subprocesses, floating timers — CH023-CH028
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)

{codehound-1.4.2 → codehound-1.6.0}/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">codehound</h1>
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty checks, seven backed by a bug that was actually found and merged into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~20-framework validation corpus instead of just reasoned about.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty-eight checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
 
 [![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codehound.svg)](https://pypi.org/project/codehound/)
@@ -51,7 +51,7 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 pip install codehound
 ```
 
-Zero dependencies — it's ~2,200 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
+Zero dependencies — it's ~3,200 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
 
 <details>
 <summary>From a clone instead (for development)</summary>
@@ -112,7 +112,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.4.2
+    rev: v1.6.0
     hooks:
       - id: codehound
 ```
@@ -133,7 +133,7 @@ repos:
 | **CH008** | `asyncio-run-in-running-loop` | `asyncio.run(...)` called from inside an `async def` — always raises `RuntimeError`, immediately, every time. | hardening rule — zero corpus hits (see below) |
 | **CH009** | `floating-thread` | A non-daemon `threading.Thread` that's `.start()`ed but never `.join()`ed — the thread analog of CH006. | hardening rule — see below |
 | **CH010** | `loop-closure-capture` | A `lambda` inside a `for` loop (or comprehension) that's *stored* (appended, assigned, returned) and captures the loop variable by reference — every stored instance ends up sharing the loop's **final** value. | **accelerate** (HuggingFace) — `MegatronEngine.get_module_config`'s `param_sync_func` list, PR #4273 |
-| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup |
+| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup; **litellm** — `Router._cached_get_model_group_info` leaked every `Router` even after its own documented `discard()` cleanup |
 | **CH012** | `floating-process` | A non-daemon `multiprocessing.Process` that's `.start()`ed but never `.join()`ed — the process analog of CH009. | hardening rule |
 | **CH013** | `discarded-future` | `ThreadPoolExecutor`/`ProcessPoolExecutor.submit(...)` called as a bare statement — the returned `Future` (and any exception raised inside the submitted work) is silently discarded. | hardening rule — real hits in litellm, accelerate, langchain |
 | **CH014** | `unprotected-lock-acquire` | `lock.acquire()` outside a `with`, whose matching `.release()` isn't inside a `finally:` — an exception between acquire and release deadlocks every future caller of that lock. | hardening rule — real hits in vllm, accelerate, torchtune |
@@ -143,10 +143,18 @@ repos:
 | **CH018** | `removed-asyncio-task-methods` | `asyncio.Task.current_task()` / `.all_tasks()` — both removed in Python 3.9; use `asyncio.current_task()` / `asyncio.all_tasks()`. | hardening rule |
 | **CH019** | `removed-getargspec` | `inspect.getargspec(...)` — removed in Python 3.11 after a decade-plus deprecation; use `inspect.signature(...)`. | hardening rule |
 | **CH020** | `bare-except` | A bare `except:` (or unused `except BaseException:`) — also catches `KeyboardInterrupt`/`SystemExit`, so Ctrl-C stops working and `sys.exit()` gets silently absorbed. | hardening rule — real hits in agno, llama_index, marimo, litellm |
+| **CH021** | `removed-stdlib-module` | `import distutils` (removed 3.12) or any of the 19 PEP 594 "dead battery" modules (`cgi`, `imghdr`, `telnetlib`, `nntplib`, …, removed 3.13) — `ImportError` the moment the module loads. | hardening rule — real hit in agno (already guarded, see below) |
+| **CH022** | `removed-asyncio-coroutine-decorator` | `@asyncio.coroutine` — removed in Python 3.11 after a generator-based-coroutine bridge that predates `async def`; `AttributeError` the moment the decorator line runs. | hardening rule |
+| **CH023** | `removed-stdlib-attribute` | A specific removed function on a module that still imports fine — `time.clock()` (3.8), `platform.linux_distribution()`/`.dist()` (3.8), `cgi.escape()` (3.8), `base64.encodestring()`/`.decodestring()` (3.9). | hardening rule — real hit in scikit-learn |
+| **CH024** | `unittest-deprecated-alias` | `self.assertEquals(...)`/`self.failUnless(...)` and a dozen other legacy `unittest.TestCase` aliases — removed in Python 3.12. | hardening rule |
+| **CH025** | `is-literal-comparison` | `x is 1000` / `x is not "foo"` — `is` checks identity, not equality; relies on CPython's small-int caching / string interning, neither guaranteed. (pyflakes F632) | hardening rule — real false positive fixed in litellm's own code, see below |
+| **CH026** | `mutable-class-attribute` | `class C: items = []` mutated via `self.items.append(...)` without ever being reassigned per instance — every instance shares and mutates the *same* list. | **vllm**, **llama_index**, **optuna**, **transformers** — see below |
+| **CH027** | `unwaited-subprocess` | `subprocess.Popen(...)` never `.wait()`ed/`.communicate()`d with, and not context-managed — risks a zombie process and a full pipe buffer deadlocking the child. | hardening rule — real hit in dspy (already handled, see below) |
+| **CH028** | `floating-timer` | `threading.Timer(...)` started but never `.cancel()`ed or handed off — nothing can stop the callback from firing later, on stale context. | hardening rule — real hits in marimo, transformers |
 
 `codehound list` prints this from the source of truth.
 
-CH007-CH020 don't have found-and-merged bugs behind all of them the way
+CH007-CH028 don't have found-and-merged bugs behind all of them the way
 CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
 tracked down first. CH010 and CH011 are the exceptions: both found
@@ -190,20 +198,28 @@ it's very unlikely to survive basic testing; CH007 and CH009 both only
 match same-file names by design, and most real cases of either are
 plausibly cross-module.
 
-**The optuna and llama_index finds (CH011):** both are `@lru_cache(maxsize=
-None)` decorating an instance method - a strong reference to `self`
-retained forever. In optuna, `_FanovaTree`'s node-lookup methods leak
-every tree built for a `get_param_importances()` call (one per
-random-forest estimator). In llama_index, `VectaraIndex._get_corpus_key`
-leaks the index itself - and since `VectaraIndex.__del__` exists
-specifically to close the index's `requests.Session` on garbage
-collection, the leak silently disables that cleanup too, so an HTTP
-session leaks along with every index. Both fixed the same way: move the
-cache from a class-level decorator to a per-instance one built in
-`__init__`, so it's freed with the instance instead of outliving it. Both
-have a regression test verified to fail pre-fix and pass post-fix.
+**The optuna, llama_index, and litellm finds (CH011):** all three are
+`@lru_cache(maxsize=None)` (or a fixed `maxsize`) decorating an instance
+method - a strong reference to `self` retained for the life of the
+process. In optuna, `_FanovaTree`'s node-lookup methods leak every tree
+built for a `get_param_importances()` call (one per random-forest
+estimator). In llama_index, `VectaraIndex._get_corpus_key` leaks the
+index itself - and since `VectaraIndex.__del__` exists specifically to
+close the index's `requests.Session` on garbage collection, the leak
+silently disables that cleanup too, so an HTTP session leaks along with
+every index. In litellm, `Router._cached_get_model_group_info` leaks
+every `Router` that's ever served a request through it - proved this
+survives even a correctly-called `router.discard()` (Router's own
+documented cleanup method), so it isn't a "you forgot to clean up" bug.
+All three fixed the same way: move the cache from a class-level decorator
+to a per-instance one built in `__init__`, so it's freed with the
+instance instead of outliving it - the exact pattern litellm's own
+`cached_deployment_model_info` sibling method already used, just not yet
+applied to this one. Each has a regression test verified to fail pre-fix
+and pass post-fix.
 PRs: [optuna/optuna#6859](https://github.com/optuna/optuna/pull/6859),
-[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089).
+[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089),
+[BerriAI/litellm#41582](https://github.com/BerriAI/litellm/pull/41582).
 
 **A third CH011 shape needed a guard instead of a PR:** dspy's `Image` (a
 pydantic model) caches `format()` the same way, but `Image` is frozen
@@ -227,6 +243,74 @@ as escaped when it's returned as part of a tuple/list or passed as an
 argument to any call. A full corpus rescan afterward found zero remaining
 CH016 hits.
 
+**CH021 did the same thing twice, minutes apart.** The first real-corpus
+scan found a false positive in vllm - `from .chunk import
+chunk_gated_delta_rule`, a relative import of vllm's own local `chunk.py`
+sibling module, not the removed stdlib `chunk`. `ast.ImportFrom.module`
+is `"chunk"` either way; only `node.level` (the leading-dot count) tells
+a relative import apart from an absolute one, and the check wasn't
+checking it. Fixed, rescanned, and found a *second* false positive in
+agno: `try: import imghdr except ImportError: import filetype` - a
+real, deliberate fallback that already anticipates this exact removal,
+not a bug waiting to happen. Added a second guard: skip an import inside
+a `try:` body whose `except` catches `ImportError` (or anything
+broader). A full corpus rescan after both fixes found zero remaining
+CH021 hits.
+
+**CH026 found four real, previously-unreported bugs on its first real
+scan.** All four are the exact same shape: a class-level mutable default
+(`items = []`) mutated in place via `self.items.append(...)` (or
+subscript assignment) with no per-instance reassignment anywhere, so
+every instance of the class shares and corrupts the *same* object. In
+vllm's `AXK1ForCausalLM`, `self.packed_modules_mapping["qkv_proj"] =
+[...]` patches a routing table shared by every instance of the model
+class. In llama_index's `ZapierToolSpec`, `self.spec_functions.append(...)`
+means a second tool-spec instance (a different API key, a different
+user) inherits every action name the first instance ever registered. In
+optuna's CLI `_Studies` command, `self._study_list_header.append(...)`
+does the same to a table-header list. In HuggingFace transformers'
+`CodeGenTokenizer`, `self.model_input_names.append("token_type_ids")`
+means constructing one tokenizer with `return_token_type_ids=True`
+silently changes what field every *other* `CodeGenTokenizer` instance in
+the same process expects, regardless of how it was configured - exactly
+the "spooky action at a distance" class of bug this project exists to
+catch. None have PRs yet: vllm and transformers both require AI-assisted
+PRs to carry an explicit disclosure, which this project's own policy
+doesn't do, so those two are documented here rather than filed.
+
+**CH028 hit the exact same name-collision problem CH018/CH022 already
+had a guard for, because that guard didn't get reused.** The very first
+corpus scan came back with ~30 hits, almost all in agno - which doesn't
+use `threading.Timer` at all. `from agno.utils.timer import Timer` is
+agno's own unrelated stopwatch class, called as `Timer()` with zero
+arguments (real `threading.Timer` requires `interval` and `function` and
+would raise `TypeError` immediately). Fixed by requiring `from threading
+import Timer` before trusting a bare `Timer(...)` call - the same guard
+already built for CH022's `coroutine` minutes earlier in the same
+session, just not applied here the first time. Also missed CH009's
+`daemon=True` escape entirely (found in weaviate-python-client's
+watchdog timer, `_timeout_timer.daemon = True`, a deliberate
+"outlive the caller" choice) - added both a constructor-kwarg and a
+post-construction-assignment check for it, matching CH009 exactly. Real
+hits remain in marimo (a non-daemon browser-opening timer, never
+cancelled) and transformers (a chained, never-captured checkpoint-retry
+timer).
+
+**CH025 and CH027 each found one real bug in the first scan, and one
+real gap in the check.** CH025 (is-literal-comparison) flagged litellm's
+`if "usage" in response_obj is not None:` - but for the wrong reason.
+`ast.Compare` puts every operand and every op from a chained comparison
+in one node; checking "is there a literal anywhere" and "is there an
+`is`/`is not` anywhere" independently, without pairing each op with its
+own adjacent operands, matched the string literal (paired with `in`)
+against the wrong op (`is not`, actually comparing `response_obj` to the
+allowed singleton `None`). Fixed by walking the chain as adjacent
+`(left, op, right)` triples. CH027 (unwaited-subprocess) flagged dspy's
+`process = subprocess.Popen(...)`, followed by `lm.process = process` -
+a real hand-off to a different object, reaped later through a separate
+`terminate_process(lm.process)` call, the same "stored as any object's
+attribute" escape CH009/CH016/CH028 already needed. Added it.
+
 **Two checks we built and did not ship.** `exception-chaining` (`except X
 as e: raise Y(...)` with no `from e`, discarding the real traceback -
 overlaps flake8-bugbear B904) worked exactly as designed, but at a scale
@@ -282,12 +366,20 @@ codehound/
     ├── collections_abc_import.py (CH017)
     ├── removed_asyncio_task_methods.py (CH018)
     ├── removed_getargspec.py   (CH019)
-    └── bare_except.py          (CH020)
+    ├── bare_except.py          (CH020)
+    ├── removed_stdlib_module.py (CH021)
+    ├── asyncio_coroutine_decorator.py (CH022)
+    ├── removed_stdlib_attribute.py (CH023)
+    ├── unittest_deprecated_alias.py (CH024)
+    ├── is_literal_comparison.py (CH025)
+    ├── mutable_class_attribute.py (CH026)
+    ├── unwaited_subprocess.py  (CH027)
+    └── floating_timer.py       (CH028)
 ```
 
 Each check receives a parsed `ast` tree plus the precomputed parent map and returns `Finding`s. Adding a rule is one file + one registry line + a test. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a full walkthrough of the engine, the parent map, and the design decisions.
 
-**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
+**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. CH025 pairs each chained comparison's op with only its own adjacent operands, rather than matching a literal and an `is`/`is not` anywhere in the same chain independently — a real pattern found in litellm. CH027 and CH028 both recognize a handle stored as *any* object's attribute as a hand-off, matching CH009/CH016's precedent — real patterns found in dspy and weaviate-python-client respectively. CH028 also only trusts a bare `Timer(...)` when `from threading import Timer` was actually seen — real hits in agno were its own unrelated stopwatch class. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -317,6 +409,11 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [x] 20 checks — memory leaks (`lru_cache` on methods), floating processes,
       discarded futures, unprotected locks, async properties, unclosed
       sockets, removed-in-3.9/3.10/3.11 stdlib APIs, bare `except:` — CH011-CH020
+- [x] 22 checks — removed stdlib modules (`distutils`, PEP 594 "dead
+      batteries"), removed `@asyncio.coroutine` decorator — CH021-CH022
+- [x] 28 checks — removed stdlib functions, deprecated unittest aliases,
+      `is`-literal comparisons, mutable class attributes, unwaited
+      subprocesses, floating timers — CH023-CH028
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)

codehound-1.6.0/src/codehound/__init__.py

@@ -0,0 +1,26 @@
+"""codehound - an AST-based static analyzer that hunts real bugs in Python code.
+
+Twenty-eight checks. Eight are each backed by a bug that was actually
+found and fixed (or opened as a PR) in a popular open-source AI framework
+(agno, crewAI, mem0, llama_index, accelerate, optuna, litellm). The rest
+(CH007-CH009, CH012-CH028) are hardening rules verified against real
+false positives across a ~29-framework validation corpus instead - see
+docs/FINDINGS.md.
+"""
+
+from __future__ import annotations
+
+from codehound.checks import ALL_CHECKS, get_checks
+from codehound.core import Check, Finding, scan_file, scan_path
+
+__version__ = "1.6.0"
+
+__all__ = [
+    "ALL_CHECKS",
+    "get_checks",
+    "Check",
+    "Finding",
+    "scan_file",
+    "scan_path",
+    "__version__",
+]

{codehound-1.4.2 → codehound-1.6.0}/src/codehound/checks/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from codehound.checks.async_property import AsyncProperty
+from codehound.checks.asyncio_coroutine_decorator import AsyncioCoroutineDecorator
 from codehound.checks.asyncio_run_in_loop import AsyncioRunInRunningLoop
 from codehound.checks.bare_except import BareExcept
 from codehound.checks.blocking_async import BlockingCallInAsync
@@ -12,16 +13,23 @@ from codehound.checks.discarded_future import DiscardedFuture
 from codehound.checks.floating_process import FloatingProcess
 from codehound.checks.floating_task import FloatingTask
 from codehound.checks.floating_thread import FloatingThread
+from codehound.checks.floating_timer import FloatingTimer
 from codehound.checks.get_event_loop import DeprecatedGetEventLoop
+from codehound.checks.is_literal_comparison import IsLiteralComparison
 from codehound.checks.loop_closure_capture import LoopClosureCapture
 from codehound.checks.lru_cache_on_method import LruCacheOnMethod
+from codehound.checks.mutable_class_attribute import MutableClassAttribute
 from codehound.checks.mutable_defaults import MutableDefaultArgument
 from codehound.checks.removed_asyncio_task_methods import RemovedAsyncioTaskMethods
 from codehound.checks.removed_getargspec import RemovedGetargspec
+from codehound.checks.removed_stdlib_attribute import RemovedStdlibAttribute
+from codehound.checks.removed_stdlib_module import RemovedStdlibModule
 from codehound.checks.resource_leak import UnclosedFileHandle
 from codehound.checks.unawaited_coroutine import UnawaitedCoroutineCall
 from codehound.checks.unclosed_socket import UnclosedSocket
+from codehound.checks.unittest_deprecated_alias import UnittestDeprecatedAlias
 from codehound.checks.unprotected_lock import UnprotectedLockAcquire
+from codehound.checks.unwaited_subprocess import UnwaitedSubprocess
 from codehound.core import Check
 
 ALL_CHECKS: list[type[Check]] = [
@@ -45,6 +53,14 @@ ALL_CHECKS: list[type[Check]] = [
     RemovedAsyncioTaskMethods,
     RemovedGetargspec,
     BareExcept,
+    RemovedStdlibModule,
+    AsyncioCoroutineDecorator,
+    RemovedStdlibAttribute,
+    UnittestDeprecatedAlias,
+    IsLiteralComparison,
+    MutableClassAttribute,
+    UnwaitedSubprocess,
+    FloatingTimer,
 ]
 
 

codehound-1.6.0/src/codehound/checks/asyncio_coroutine_decorator.py

@@ -0,0 +1,70 @@
+"""CH022 - ``@asyncio.coroutine`` was removed in Python 3.11.
+
+The generator-based coroutine decorator predates `async def` (added in
+3.5) and was kept around for years as a bridge for old code, deprecated
+since 3.8 with an explicit `DeprecationWarning`, then removed outright in
+3.11 - `AttributeError: module 'asyncio' has no attribute 'coroutine'`
+the moment the decorator line runs, not something that surfaces later.
+`async def` is the direct replacement; there's no decorator to swap in.
+
+A bare `@coroutine` is only trusted to mean `asyncio.coroutine` if the
+file actually imported it via `from asyncio import coroutine` - the same
+name-collision guard CH018 uses for `Task`, since `coroutine` alone is
+common enough to plausibly be someone's own decorator.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+
+def _imports_coroutine_from_asyncio(tree: ast.AST) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "asyncio":
+            if any(alias.name == "coroutine" for alias in node.names):
+                return True
+    return False
+
+
+def _is_asyncio_coroutine_attr(node: ast.expr) -> bool:
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == "coroutine"
+        and isinstance(node.value, ast.Name)
+        and node.value.id == "asyncio"
+    )
+
+
+class AsyncioCoroutineDecorator(Check):
+    code = "CH022"
+    name = "removed-asyncio-coroutine-decorator"
+    description = "@asyncio.coroutine was removed in Python 3.11; use `async def` instead."
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        findings: list[Finding] = []
+        trust_bare_name = _imports_coroutine_from_asyncio(tree)
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            for dec in node.decorator_list:
+                is_match = _is_asyncio_coroutine_attr(dec) or (
+                    trust_bare_name and isinstance(dec, ast.Name) and dec.id == "coroutine"
+                )
+                if not is_match:
+                    continue
+                findings.append(
+                    Finding(
+                        path=path,
+                        line=dec.lineno,
+                        col=dec.col_offset,
+                        code=self.code,
+                        message=(
+                            f"`@{ast.unparse(dec)}` on `{node.name}` - removed in Python 3.11; "
+                            f"define `{node.name}` with `async def` instead."
+                        ),
+                    )
+                )
+                break
+        return findings