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
|
+
[](https://pypi.org/project/heki/)
|
|
40
|
+
[](https://pypi.org/project/heki/)
|
|
41
|
+
[](https://github.com/koxudaxi/heki/actions/workflows/ci.yml)
|
|
42
|
+
[](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,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.
|