codehound 1.4.2__tar.gz → 1.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.4.2
+Version: 1.5.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-two 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 ~2,600 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.5.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,12 @@ 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 |
 
 `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-CH022 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 +212,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 +257,20 @@ 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.
+
 **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 +326,14 @@ 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)
 ```
 
 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. 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 +363,8 @@ 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
 - [ ] 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.5.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-two 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 ~2,600 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.5.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,12 @@ 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 |
 
 `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-CH022 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 +192,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 +237,20 @@ 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.
+
 **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 +306,14 @@ 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)
 ```
 
 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. 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 +343,8 @@ 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
 - [ ] 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.5.0/src/codehound/__init__.py

@@ -0,0 +1,26 @@
+"""codehound - an AST-based static analyzer that hunts real bugs in Python code.
+
+Twenty-two 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-CH022) 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.5.0"
+
+__all__ = [
+    "ALL_CHECKS",
+    "get_checks",
+    "Check",
+    "Finding",
+    "scan_file",
+    "scan_path",
+    "__version__",
+]

{codehound-1.4.2 → codehound-1.5.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
@@ -18,6 +19,7 @@ from codehound.checks.lru_cache_on_method import LruCacheOnMethod
 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_module import RemovedStdlibModule
 from codehound.checks.resource_leak import UnclosedFileHandle
 from codehound.checks.unawaited_coroutine import UnawaitedCoroutineCall
 from codehound.checks.unclosed_socket import UnclosedSocket
@@ -45,6 +47,8 @@ ALL_CHECKS: list[type[Check]] = [
     RemovedAsyncioTaskMethods,
     RemovedGetargspec,
     BareExcept,
+    RemovedStdlibModule,
+    AsyncioCoroutineDecorator,
 ]
 
 

codehound-1.5.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

codehound-1.5.0/src/codehound/checks/removed_stdlib_module.py

@@ -0,0 +1,142 @@
+"""CH021 - importing a stdlib module that no longer exists.
+
+``distutils`` was deprecated in 3.10 and removed outright in 3.12 (PEP
+632) - still one of the most common "why won't this install on the new
+Python" reports, since it was the default build backend for `setup.py`
+for two decades. `asynchat`/`asyncore`/`imp` were removed the same
+release. Python 3.13 then removed the 19 modules PEP 594 called the
+standard library's "dead batteries" - old data-format, multimedia, and
+platform-specific modules with long-unmaintained implementations and
+better replacements on PyPI (`aifc`, `audioop`, `cgi`, `cgitb`, `chunk`,
+`crypt`, `imghdr`, `mailcap`, `msilib`, `nis`, `nntplib`, `ossaudiodev`,
+`pipes`, `sndhdr`, `spwd`, `sunau`, `telnetlib`, `uu`, `xdrlib`).
+
+Same failure mode as CH017/CH019: `ImportError` the moment the module is
+loaded on the Python version it was removed in, not a subtle runtime
+bug - but real, and common in anything with an older dependency tree or
+a `setup.py` that hasn't been touched since distutils was normal.
+
+Not flagged when the import sits in a `try:` body whose `except` catches
+`ImportError` (or anything broader) - a real, deliberate pattern found in
+agno: `try: import imghdr except ImportError: import filetype` explicitly
+anticipates and falls back from exactly this removal, so it isn't a bug
+waiting to happen, it's already handled.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+_IMPORT_ERROR_NAMES = {"ImportError", "ModuleNotFoundError", "Exception", "BaseException"}
+
+
+def _handles_import_error(handler: ast.ExceptHandler) -> bool:
+    if handler.type is None:
+        return True
+    candidates = handler.type.elts if isinstance(handler.type, ast.Tuple) else [handler.type]
+    return any(isinstance(c, ast.Name) and c.id in _IMPORT_ERROR_NAMES for c in candidates)
+
+
+def _is_guarded_by_import_error_handler(node: ast.AST, parents: dict) -> bool:
+    """True if `node` sits in the `try:` body of a Try with a matching
+    handler, at any enclosing level up to the function/class/module
+    boundary."""
+    cur = node
+    while cur is not None:
+        p = parents.get(id(cur))
+        if p is None:
+            return False
+        if isinstance(p, ast.Try) and cur in p.body and any(_handles_import_error(h) for h in p.handlers):
+            return True
+        if isinstance(p, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module)):
+            return False
+        cur = p
+    return False
+
+_REMOVED_IN: dict[str, str] = {
+    "distutils": "3.12",
+    "asynchat": "3.12",
+    "asyncore": "3.12",
+    "imp": "3.12",
+    "aifc": "3.13",
+    "audioop": "3.13",
+    "cgi": "3.13",
+    "cgitb": "3.13",
+    "chunk": "3.13",
+    "crypt": "3.13",
+    "imghdr": "3.13",
+    "mailcap": "3.13",
+    "msilib": "3.13",
+    "nis": "3.13",
+    "nntplib": "3.13",
+    "ossaudiodev": "3.13",
+    "pipes": "3.13",
+    "sndhdr": "3.13",
+    "spwd": "3.13",
+    "sunau": "3.13",
+    "telnetlib": "3.13",
+    "uu": "3.13",
+    "xdrlib": "3.13",
+}
+
+
+class RemovedStdlibModule(Check):
+    code = "CH021"
+    name = "removed-stdlib-module"
+    description = "Importing a stdlib module removed in a later Python version (distutils, PEP 594 modules, etc)."
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        findings: list[Finding] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                if _is_guarded_by_import_error_handler(node, parents):
+                    continue
+                for alias in node.names:
+                    top_level = alias.name.split(".")[0]
+                    version = _REMOVED_IN.get(top_level)
+                    if version is not None:
+                        findings.append(
+                            Finding(
+                                path=path,
+                                line=node.lineno,
+                                col=node.col_offset,
+                                code=self.code,
+                                message=(
+                                    f"`import {alias.name}` - the `{top_level}` module was removed "
+                                    f"in Python {version}; there is no drop-in stdlib replacement, "
+                                    f"see its migration notes."
+                                ),
+                            )
+                        )
+            elif (
+                isinstance(node, ast.ImportFrom)
+                and node.module is not None
+                and node.level == 0
+                and not _is_guarded_by_import_error_handler(node, parents)
+            ):
+                # `node.level` is the number of leading dots (0 = absolute). A
+                # relative `from .chunk import x` has `node.module == "chunk"`
+                # too - indistinguishable from the real stdlib module by name
+                # alone. Real false positive found in vllm's own local
+                # `fla/ops/chunk.py` sibling module, imported via `from .chunk
+                # import chunk_gated_delta_rule`.
+                top_level = node.module.split(".")[0]
+                version = _REMOVED_IN.get(top_level)
+                if version is not None:
+                    names = ", ".join(alias.name for alias in node.names)
+                    findings.append(
+                        Finding(
+                            path=path,
+                            line=node.lineno,
+                            col=node.col_offset,
+                            code=self.code,
+                            message=(
+                                f"`from {node.module} import {names}` - the `{top_level}` module "
+                                f"was removed in Python {version}; there is no drop-in stdlib "
+                                f"replacement, see its migration notes."
+                            ),
+                        )
+                    )
+        return findings

{codehound-1.4.2 → codehound-1.5.0}/tests/test_checks.py

@@ -1043,3 +1043,111 @@ def test_ch020_flags_base_exception_with_raise_only_in_nested_handler():
     )
     assert len(_run(code, ["CH020"])) == 1
 
+
+# --- CH021 removed-stdlib-module ------------------------------------------------------
+
+
+def test_ch021_flags_distutils_import():
+    findings = _run("import distutils\n", ["CH021"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH021"
+
+
+def test_ch021_flags_distutils_submodule_import():
+    findings = _run("import distutils.core\n", ["CH021"])
+    assert len(findings) == 1
+
+
+def test_ch021_flags_distutils_from_import():
+    code = "from distutils.core import setup\n"
+    findings = _run(code, ["CH021"])
+    assert len(findings) == 1
+
+
+def test_ch021_flags_pep594_dead_battery_modules():
+    for mod in ["cgi", "imghdr", "telnetlib", "nntplib", "asynchat", "asyncore", "imp"]:
+        findings = _run(f"import {mod}\n", ["CH021"])
+        assert len(findings) == 1, f"expected {mod} to be flagged"
+
+
+def test_ch021_ignores_unrelated_modules():
+    code = "import os\nimport sys\nfrom collections import OrderedDict\n"
+    assert _run(code, ["CH021"]) == []
+
+
+def test_ch021_ignores_similarly_named_local_module():
+    # A module named e.g. `imp` in the removed set shouldn't false-positive
+    # on an unrelated attribute/name access - only actual import statements.
+    code = "imp = 5\nprint(imp)\n"
+    assert _run(code, ["CH021"]) == []
+
+
+def test_ch021_ignores_relative_import_of_same_named_local_module():
+    # Real false positive found in vllm: `from .chunk import
+    # chunk_gated_delta_rule` imports a local sibling module named
+    # chunk.py, not the removed stdlib `chunk` module - `node.module` is
+    # "chunk" either way, so only `node.level == 0` (absolute) tells them
+    # apart.
+    code = "from .chunk import chunk_gated_delta_rule\n"
+    assert _run(code, ["CH021"]) == []
+
+
+def test_ch021_ignores_import_guarded_by_import_error_handler():
+    # Real false positive found in agno: `try: import imghdr except
+    # ImportError: import filetype` explicitly anticipates and falls back
+    # from the removal - already handled, not a bug waiting to happen.
+    code = "try:\n    import imghdr\nexcept ImportError:\n    import filetype\n"
+    assert _run(code, ["CH021"]) == []
+
+
+def test_ch021_ignores_from_import_guarded_by_broad_except():
+    code = "try:\n    from distutils.core import setup\nexcept Exception:\n    setup = None\n"
+    assert _run(code, ["CH021"]) == []
+
+
+def test_ch021_still_flags_import_in_try_with_unrelated_handler():
+    # A try/except that doesn't actually catch ImportError provides no
+    # real protection, so this must still be flagged.
+    code = "try:\n    import distutils\nexcept ValueError:\n    pass\n"
+    findings = _run(code, ["CH021"])
+    assert len(findings) == 1
+
+
+def test_ch021_still_flags_import_outside_any_try():
+    code = "import distutils\ntry:\n    risky()\nexcept ImportError:\n    pass\n"
+    findings = _run(code, ["CH021"])
+    assert len(findings) == 1
+
+
+# --- CH022 removed-asyncio-coroutine-decorator -----------------------------------------
+
+
+def test_ch022_flags_asyncio_coroutine_decorator():
+    code = "import asyncio\n@asyncio.coroutine\ndef f():\n    yield from g()\n"
+    findings = _run(code, ["CH022"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH022"
+
+
+def test_ch022_flags_bare_coroutine_when_imported_from_asyncio():
+    code = "from asyncio import coroutine\n@coroutine\ndef f():\n    yield from g()\n"
+    findings = _run(code, ["CH022"])
+    assert len(findings) == 1
+
+
+def test_ch022_ignores_bare_coroutine_not_imported_from_asyncio():
+    # Real name-collision guard, same shape as CH018's for `Task`: a
+    # same-named decorator from somewhere else shouldn't be misidentified.
+    code = "from mylib import coroutine\n@coroutine\ndef f():\n    return 1\n"
+    assert _run(code, ["CH022"]) == []
+
+
+def test_ch022_ignores_async_def_without_decorator():
+    code = "async def f():\n    return 1\n"
+    assert _run(code, ["CH022"]) == []
+
+
+def test_ch022_ignores_unrelated_attribute_named_coroutine():
+    code = "import asyncio\n@other.coroutine\ndef f():\n    return 1\n"
+    assert _run(code, ["CH022"]) == []
+

codehound-1.4.2/src/codehound/__init__.py

@@ -1,25 +0,0 @@
-"""codehound - an AST-based static analyzer that hunts real bugs in Python code.
-
-Twenty checks. Seven are each backed by a bug that was actually found and
-fixed in a popular open-source AI framework (agno, crewAI, mem0,
-llama_index, accelerate). The rest (CH007-CH009, CH011-CH020) are
-hardening rules verified against real false positives across a
-~20-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.4.2"
-
-__all__ = [
-    "ALL_CHECKS",
-    "get_checks",
-    "Check",
-    "Finding",
-    "scan_file",
-    "scan_path",
-    "__version__",
-]