@suss/adapter-python 0.3.2-0 → 0.5.0

package/README.md

@@ -101,6 +101,105 @@ A registration nobody wrote leaves the reading standing rather than abstaining.
 
 A prefix written with a trailing slash leaves the composed path with two. Werkzeug answers such a rule at the merged path and redirects the written one, so `/api/v1//orders` is reached at `/api/v1/orders`; the pack says so, and the reader merges repeated slashes in every path it composes. Starlette does not do this, so FastAPI's pack says nothing and its paths stand as composed.
 
+## What a body lowers to
+
+A route's own returns are what make it produce more than one transition, so the
+adapter lowers a function body into the statement form the shared path engine
+in `@suss/extractor` walks. That engine is generic over the language's own
+condition handle and never looks inside one, so the enumeration, the negation
+of an earlier arm, and the budget are all shared with TypeScript.
+
+| Python | Lowers to |
+| --- | --- |
+| `if` / `elif` / `else` | one `if` per test, with the elif chain nested into the else arm the way Python reads it |
+| `while`, `for` | `loop` |
+| `try` / `except` / `finally` | `try`, with every except arm as the catch body |
+| `match` / `case` | `switch`, one group per case, `case _` as the default group |
+| `return`, `raise` | `exit`, which is what gives each return its own transition |
+| `break`, `continue` | `exit`, which the engine uses for reachability rather than as an outcome |
+| anything else | `opaque` |
+
+A statement's exit kind comes from scanning its own subtree for a return or a
+raise, stopping at a nested `def` or `lambda`, because those belong to the
+function they declare. A raise anywhere beats a return anywhere.
+
+So a handler written this way:
+
+```python
+def get(self, order_id) -> dict:
+    if not found:
+        return {"error": "nope"}, 404
+    return {"a": 1}, 200
+```
+
+comes out as two transitions, the 404 gated on the opaque condition
+`not found` and the 200 gated on its negation, rather than as one claim with a
+guessed status.
+
+### Keying anything on a node
+
+tree-sitter hands back a fresh wrapper object every time a child is read, so
+two reads of one node are never `===` and a plain `Set` or `Map` keyed on a
+node matches nothing. Use `NodeSet` and `NodeMap`, which key on the node id.
+`npm run check:style` fails a build that keys either on a node.
+
+## What a body does with the database
+
+A pack says which query types its library defines, and a call chain matches
+when the method behind it says it returns one:
+
+```ts
+storage: [
+  {
+    module: "sqlalchemy.orm",
+    queryTypes: ["Query"],
+    writes: ["update", "delete", "add"],
+    storageSystem: "postgres",
+  },
+]
+```
+
+Matching on the return rather than on the import is what reads a project's own
+wrapper. A measured Flask service imports `sqlalchemy` in 50 files, and every
+one of its 157 queries still goes through a base class the call sites never
+import:
+
+```python
+# in the project, not in the library
+class Base:
+    @classmethod
+    def query(cls) -> Query: ...
+
+class Orders(Base): ...
+
+# in a handler, importing neither the base nor SQLAlchemy
+found = Orders.query().filter_by(id=1).first()
+```
+
+A recognizer keyed on the import finds none of that. Following the call to
+`Base.query` and reading what it says it returns finds all of it, and the
+inheritance hop comes from `contains`, which reads `holdsProperty` and adds
+what a base class declares.
+
+A chain is one thing the code does, so the three calls above are one read. The
+call that starts the chain is the one resolved, and the method the chain ends
+with tells a read from a write. A method a base and a subclass both declare
+gives two, and nothing is claimed.
+
+A query built from a function the library exports has no project method in
+between for its return to be read off, so a pack lists those by name and a call
+site importing one matches on that:
+
+```ts
+queryFunctions: ["select", "insert", "update", "delete"]
+```
+
+`fields` comes from the columns a query names, `User.id` in
+`select(User.id, User.email)`. `selector` comes from the keywords the chain
+picks rows by, `id` in `filter_by(id=user_id)`, gathered from every call in
+the chain rather than only the last. Raw SQL handed to `execute` is not read
+at all.
+
 ## Where a mount is written
 
 Almost no service mounts anything at the top level of a module. It builds its routers or namespaces there, each with a literal prefix, and registers them inside the function that builds the app, often by looping over a list that another function put together: