heki 0.1.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
@@ -0,0 +1,268 @@
1
+ Metadata-Version: 2.4
2
+ Name: heki
3
+ Version: 0.1.0
4
+ Classifier: Development Status :: 2 - Pre-Alpha
5
+ Classifier: Intended Audience :: Developers
6
+ Classifier: Programming Language :: Python :: 3
7
+ Classifier: Programming Language :: Python :: 3.11
8
+ Classifier: Programming Language :: Python :: 3.12
9
+ Classifier: Programming Language :: Python :: 3.13
10
+ Classifier: Programming Language :: Python :: 3.14
11
+ Classifier: Programming Language :: Python :: 3.15
12
+ Classifier: Programming Language :: Rust
13
+ Classifier: Topic :: Software Development :: Quality Assurance
14
+ License-File: LICENSE
15
+ Summary: Experimental static checker for Python that tracks side effects and mutations across function calls
16
+ Keywords: linter,static-analysis,effect-analysis,alias-analysis,python,rust
17
+ Home-Page: https://github.com/koxudaxi/heki
18
+ License-Expression: MIT
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
21
+ Project-URL: Documentation, https://heki.koxudaxi.dev
22
+ Project-URL: Homepage, https://github.com/koxudaxi/heki
23
+ Project-URL: Issues, https://github.com/koxudaxi/heki/issues
24
+ Project-URL: Repository, https://github.com/koxudaxi/heki
25
+
26
+ # heki
27
+
28
+ 🧱 heki (壁, "wall") is a static checker for Python, written in Rust. It tracks side effects and
29
+ mutations across function calls.
30
+
31
+ With no configuration, it catches blocking I/O in `async` code, database queries and HTTP clients
32
+ in loops, and quadratic loops. You can also add rules in `pyproject.toml` to restrict
33
+ which functions may mutate state or reach I/O.
34
+
35
+ πŸ“š [Documentation](https://heki.koxudaxi.dev/) Β·
36
+ πŸš€ [Getting started](https://heki.koxudaxi.dev/getting-started/) Β·
37
+ πŸ“ [Rules](https://heki.koxudaxi.dev/rules/)
38
+
39
+ [![PyPI](https://img.shields.io/pypi/v/heki.svg)](https://pypi.org/project/heki/)
40
+ [![Python versions](https://img.shields.io/pypi/pyversions/heki.svg)](https://pypi.org/project/heki/)
41
+ [![CI](https://github.com/koxudaxi/heki/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/koxudaxi/heki/actions/workflows/ci.yml)
42
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/koxudaxi/heki/blob/main/LICENSE)
43
+
44
+ ---
45
+
46
+ ### A blocking call two helpers below an `async def`
47
+
48
+ ```python
49
+ # app/users.py
50
+ import requests
51
+
52
+ def fetch_name(user_id: int) -> str:
53
+ return requests.get(f"https://api.example.com/users/{user_id}", timeout=5).text
54
+
55
+ def load_user(user_id: int) -> dict[str, str]:
56
+ return {"id": str(user_id), "name": fetch_name(user_id)}
57
+ ```
58
+
59
+ ```python
60
+ # app/api.py
61
+ from app.users import load_user
62
+
63
+ async def get_user(user_id: int) -> dict[str, str]:
64
+ return load_user(user_id)
65
+ ```
66
+
67
+ ```console
68
+ $ heki check
69
+ app/api.py:5:12: EFF101 (async-blocking-call) [error] `get_user` reaches the blocking call `requests.get` on the event loop
70
+ |
71
+ 5 | return load_user(user_id)
72
+ | ^
73
+ = related: app/api.py:5:12: `get_user` calls `app.users.load_user`
74
+ = related: app/users.py:8:41: `load_user` calls `app.users.fetch_name`
75
+ = related: app/users.py:5:12: `fetch_name` calls `requests.get`
76
+ = help: offload it with `asyncio.to_thread`, or use an async client
77
+
78
+ Found 1 diagnostic(s) in 2 file(s).
79
+ ```
80
+
81
+ ### A query one helper below a loop
82
+
83
+ ```python
84
+ # app/orders.py
85
+ import sqlite3
86
+
87
+ def customer_name(cursor: sqlite3.Cursor, customer_id: int) -> str:
88
+ cursor.execute("SELECT name FROM customers WHERE id = ?", (customer_id,))
89
+ return str(cursor.fetchone()[0])
90
+
91
+ def order_summaries(cursor: sqlite3.Cursor, orders: list[tuple[int, int]]) -> list[str]:
92
+ lines: list[str] = []
93
+ for order_id, customer_id in orders:
94
+ lines.append(f"#{order_id} {customer_name(cursor, customer_id)}")
95
+ return lines
96
+ ```
97
+
98
+ ```console
99
+ $ heki check
100
+ app/orders.py:11:37: EFF103 (loop-db-query) [error] `app.orders.customer_name` runs a database query (`sqlite3.Cursor.execute`) on every loop iteration (N+1)
101
+ |
102
+ 11 | lines.append(f"#{order_id} {customer_name(cursor, customer_id)}")
103
+ | ^
104
+ = related: app/orders.py:11:37: `order_summaries` calls `app.orders.customer_name`
105
+ = related: app/orders.py:5:5: `customer_name` calls `sqlite3.Cursor.execute`
106
+ = help: batch the queries, or load the data once before the loop
107
+
108
+ Found 1 diagnostic(s) in 1 file(s).
109
+ ```
110
+
111
+ Ruff, ty, Pyrefly, pyright, and mypy report nothing for either example with their default settings.
112
+
113
+ ### Your own conventions, too
114
+
115
+ The checks above need no configuration. The rules of your own project, which you keep today by
116
+ review, by AST scripts, or by run-time guards in tests, can be added as a few lines of it:
117
+
118
+ ```toml
119
+ [[tool.heki.write-owners]]
120
+ targets = ["app.models.Order.items"]
121
+ allowed-writers = ["app.store.*"]
122
+ ```
123
+
124
+ heki follows aliases, helpers, and subclasses, with no decorators and nothing running at run
125
+ time. The other contracts are `read-owners`, `call-owners`, `readonly-returns`, `invalidation`,
126
+ and `effect-boundaries`.
127
+
128
+ > [!WARNING]
129
+ > πŸ§ͺ **Experimental.** heki is under active development: rules, configuration keys, diagnostics,
130
+ > and output formats can change between releases without a deprecation period. Try it on your
131
+ > code and report what it gets wrong, but do not depend on its output staying the same yet.
132
+
133
+ ## ✨ Why heki?
134
+
135
+ Types say what values are; heki checks what code does:
136
+
137
+ - **Aliases and in-place changes:** which objects a function changes, through any alias, helper,
138
+ or subclass.
139
+ - **Contracts:** who may write, read, or call what, and which code may reach I/O.
140
+ - **Proven rewrites:** quadratic patterns are rewritten only when the rewrite is proven, not
141
+ guessed.
142
+
143
+ ### What code does, not what types it has
144
+
145
+ Each report shows the chain of calls that leads to the bug.
146
+
147
+ | What goes wrong | Rule |
148
+ | --- | --- |
149
+ | A blocking call several helpers below an `async def` | `EFF101` |
150
+ | A database query, or a new HTTP client, on every loop iteration | `EFF103`, `EFF102` |
151
+ | An attribute that `__hash__` reads, changed after the object went into a `set` | `MUT107` |
152
+ | A `Sequence` / `Mapping` argument changed in place by a helper | `MUT110` |
153
+ | Opt-in: a frozen or `ReadOnly` field changed in place | `MUT108` |
154
+ | Opt-in: I/O while a lock or a database transaction is held | `EFF106` |
155
+ | Opt-in: a generator consumed twice | `MUT106` |
156
+ | Opt-in, experimental: a `@cached_property` left stale after another method changes what it read | `MUT101` |
157
+ | Opt-in: a function reading a `@cached_property` that another method leaves stale | `MUT111` |
158
+
159
+ ### A safety net for reviews and coding agents
160
+
161
+ - The language server checks while you edit and re-checks only what an edit can affect.
162
+ - `heki snapshot` records what each public function does, and `MUT103` reports a function that gained an
163
+ effect, which a diff does not show.
164
+ - Coding agents get the same checks as JSON.
165
+
166
+ ### Fast, quiet, and easy to adopt
167
+
168
+ - Under a second for a 200,000-line project.
169
+ - A report needs evidence: when heki cannot tell, it stays quiet.
170
+ - Configuration, suppression comments, and output formats follow Ruff, and a baseline fails CI
171
+ only on new findings.
172
+
173
+ ## πŸ”“ What Python leaves open
174
+
175
+ | What Python leaves open | What other languages enforce | What heki checks |
176
+ | --- | --- | --- |
177
+ | Any code can change any object it reaches | ownership and borrowing (Rust), `const` / `readonly` | read-only parameters and fields changed through helpers (`MUT110`, `MUT108`); `write-owners` / `read-owners` contracts (`MUT201`, `MUT203`) |
178
+ | A signature does not say what a function does | effect types, `IO` in the type (Haskell) | blocking calls reached from `async def`, and clients and queries in loops (`EFF101`–`EFF103`); `effect-boundaries` (`EFF201`); effect snapshots (`MUT103`) |
179
+ | Shared mutable objects hide changes | value semantics, immutability by default | stale cached properties and hashes (`MUT101`, `MUT107`); changed shared return values (`MUT202`); writes an `invalidation` contract must announce (`MUT109`) |
180
+ | Dynamic dispatch blocks optimizations | static types let a compiler prove a rewrite | quadratic patterns (`OPT`), rewritten only when proven under CPython's semantics |
181
+
182
+ ## πŸ” How heki differs
183
+
184
+ The difference is the model, not reaching across files: type checkers already follow types
185
+ across modules. heki models effects and aliases, what code does:
186
+
187
+ | Tool | Models | heki adds |
188
+ | --- | --- | --- |
189
+ | Ruff | syntax and style | the effects behind a call: a blocking call, a query, or a write, wherever it happens |
190
+ | ty, Pyrefly, pyright, mypy | declared types | in-place changes, through aliases and helpers, to `frozen`, `ReadOnly`, and `Final` fields and to `Sequence` / `Mapping` arguments |
191
+ | tach, import-linter | which modules may import which | which functions write or read a field, call a function, or reach I/O |
192
+
193
+ Their stricter settings do not close the gap. The second example above is fully annotated and
194
+ passes Ruff's annotation rules (`ANN`), `mypy --strict`, pyright's strict mode, and Pyrefly's
195
+ `strict` preset, yet it sends one query per order: the types are right, and what the code does
196
+ is slow.
197
+
198
+ heki leaves to these tools what they cover, and keeps doing so as they grow: use it next to them.
199
+
200
+ ## πŸ”§ Rewrites proven under CPython's semantics
201
+
202
+ The `OPT` rules find quadratic list, dict, set, bytes, and queue patterns. `heki check --fix`
203
+ rewrites one only when it proves that the program behaves the same:
204
+
205
+ - it trusts no type annotation (a subclass can override `__add__`);
206
+ - any other reference to the object blocks an in-place update;
207
+ - evaluation order and exceptions are kept;
208
+ - builtins count only while the module does not rebind them.
209
+
210
+ The scope analysis is checked against CPython's `symtable` on 3.11 to 3.15, and adversarial
211
+ programs that break a naive rewrite must all be blocked on CPython. When a proof fails, the
212
+ report names the missing obligation instead of offering a fix.
213
+
214
+ ## 🎯 Scope
215
+
216
+ - Its knowledge comes from its own analysis, a catalog of library behavior, contracts you
217
+ declare in `pyproject.toml`, and type annotations, which only help it resolve calls: rewrites
218
+ never trust them.
219
+ - When it cannot tell, it stays quiet. Annotations, catalog entries, and contracts close the
220
+ findings it misses.
221
+ - It does not model `__getattr__` proxies, metaclasses, or framework machinery, and it never
222
+ runs your code.
223
+
224
+ See [Scope and limitations](https://heki.koxudaxi.dev/scope/) for the details.
225
+
226
+ ## πŸ“¦ Installation
227
+
228
+ ```console
229
+ $ uv tool install heki # or: pipx install heki / pip install heki
230
+ $ uvx heki check # run without installing
231
+ ```
232
+
233
+ ## πŸƒ Usage
234
+
235
+ ```console
236
+ $ heki check # check the project
237
+ $ heki check --diff # preview proven-safe fixes
238
+ $ heki check --fix # apply them
239
+ $ heki check --baseline heki-baseline.toml # fail only on new findings
240
+ $ heki rule EFF101 # explain a rule
241
+ $ heki server # LSP server for editors
242
+ ```
243
+
244
+ ## πŸ“š Documentation
245
+
246
+ **πŸ‘‰ [heki.koxudaxi.dev](https://heki.koxudaxi.dev/)**
247
+
248
+ - πŸš€ [Getting started](https://heki.koxudaxi.dev/getting-started/) - run heki on a project, read a diagnostic, apply a fix
249
+ - 🎯 [Scope and limitations](https://heki.koxudaxi.dev/scope/) - what heki checks and what it leaves to other tools
250
+ - βš™οΈ [Configuration](https://heki.koxudaxi.dev/configuration/) - rule selection, contracts, the Python version
251
+ - πŸ“ [Rules](https://heki.koxudaxi.dev/rules/) - all 31 rules
252
+ - πŸ”§ [Fixes and safety](https://heki.koxudaxi.dev/fixes/) - how rewrites are proven safe
253
+ - πŸͺœ [Adopting heki](https://heki.koxudaxi.dev/adoption/) - Ratchet baselines, pre-commit, CI
254
+ - πŸ–₯️ [Editors (LSP)](https://heki.koxudaxi.dev/lsp/) - VS Code, Neovim, and any LSP client
255
+ - πŸ€– [Coding agents](https://heki.koxudaxi.dev/coding-agents/) - JSON output and agent setup
256
+ - ⌨️ [CLI reference](https://heki.koxudaxi.dev/cli-reference/) - every command and option
257
+ - πŸ› οΈ [Development](https://heki.koxudaxi.dev/development/) - building, testing, and the gates
258
+ - πŸ“ [Changelog](https://github.com/koxudaxi/heki/blob/main/CHANGELOG.md)
259
+
260
+ ## πŸ“› Name
261
+
262
+ *heki* is 壁, "wall", in its Sino-Japanese (*on*) reading, the one used in compounds such as
263
+ 防火壁 (*bōkaheki*, "firewall"). On its own the character is usually read *kabe*.
264
+
265
+ ## πŸ“„ License
266
+
267
+ [MIT](https://github.com/koxudaxi/heki/blob/main/LICENSE)
268
+
@@ -0,0 +1,6 @@
1
+ heki-0.1.0.data/scripts/heki.exe,sha256=nLOW1rK6jEZMCwUOGvJUUZikfOy8YTM-hFIkIk8EhIY,15001600
2
+ heki-0.1.0.dist-info/METADATA,sha256=YEVXNAoSwX0hDd3PLdpNN06GejThfgg6gqb9O9saEJY,12618
3
+ heki-0.1.0.dist-info/WHEEL,sha256=Uvw7WSmy7Kj2FBk8Va4L_dq4MDW8X5Ynby-pOX3ZNS0,94
4
+ heki-0.1.0.dist-info/licenses/LICENSE,sha256=rGsmf59Akgygcf58usb2EmFa_VyARMylt_TNCNaIlfE,1089
5
+ heki-0.1.0.dist-info/sboms/heki.cyclonedx.json,sha256=66PI59NR3I4CVSoYYyGg4KtM8UMUqpdrkhD9Iu1VsSA,212602
6
+ heki-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.16.0)
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-win_amd64
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Koudai Aono
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.