@suss/adapter-python 0.22.1 → 0.22.3

package/README.md

@@ -66,7 +66,8 @@ Every cell describes what the library itself does. We read that off the library'
 | `"/"`                | the route path, no prefix  | the app does not start     | stated, and trimming leaves nothing                                          |
 | `""`                 | `/` + the namespace's name | the route path, no prefix  | unstated where the pack says a no-value prefix is unstated, otherwise stated |
 | `None`, `False`, `0` | `/` + the namespace's name | the app does not start     | unstated where the pack says so, otherwise unreadable                        |
-| a name or a call     | whatever it evaluates to   | whatever it evaluates to   | unreadable                                                                   |
+| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | whatever it evaluates to | stated, with the string it settles on                     |
+| anything the evaluator cannot settle | whatever it evaluates to | whatever it evaluates to | unreadable                                                   |
 
 **At the mount** (`add_namespace(ns, path=...)`, `include_router(router, prefix=...)`):
 
@@ -77,7 +78,8 @@ Every cell describes what the library itself does. We read that off the library'
 | `"/api/"`            | `/api/` + the route path, kept as written            | the app does not start                             | stated                                                |
 | `""`                 | where the constructor put it                         | the constructor's prefix + the route path          | unstated where the pack says so, otherwise stated     |
 | `None`, `False`, `0` | where the constructor put it                         | the app does not start                             | unstated where the pack says so, otherwise unreadable |
-| a name or a call     | whatever it evaluates to                             | whatever it evaluates to                           | unreadable                                            |
+| a name, a call, or an f-string the evaluator settles | whatever it evaluates to              | whatever it evaluates to                           | stated, with the string it settles on                 |
+| anything the evaluator cannot settle | whatever it evaluates to             | whatever it evaluates to                           | unreadable                                            |
 
 The two libraries differ on one property, and the pack says which way each one goes. flask-restx checks whether the path is truthy, so all four no-value spellings mean the same thing as writing nothing, at both places. FastAPI wants a string, so an empty string is an ordinary prefix that happens to add nothing, and the other three stop the app from starting.
 
@@ -101,7 +103,8 @@ FastAPI has no column here: its app has no prefix of its own, and the pack decla
 | `"/"` | the rest of the path, once the merge collapses the doubled slash | stated, and merging leaves nothing |
 | `""`, `None` | the rest of the path, no prefix | unstated |
 | `False`, `0` | the app does not start: Flask hands the value straight to `rstrip` | unstated |
-| a name or a call | whatever it evaluates to | unreadable |
+| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | stated, with the string it settles on |
+| anything the evaluator cannot settle | whatever it evaluates to | unreadable |
 
 **At the `Api`** (`Api(bp, prefix=...)`):
 
@@ -111,7 +114,8 @@ FastAPI has no column here: its app has no prefix of its own, and the pack decla
 | `"/extra"` | the blueprint's prefix + `/extra` + the rest | stated |
 | `"/extra/"` | the same, concatenated as written, and Werkzeug answers the merged path | stated, and the composed path is merged |
 | `""`, `None`, `False`, `0` | the blueprint's prefix + the rest | unstated |
-| a name or a call | whatever it evaluates to | unreadable |
+| a name, a call, or an f-string the evaluator settles | whatever it evaluates to | stated, with the string it settles on |
+| anything the evaluator cannot settle | whatever it evaluates to | unreadable |
 
 ### A call that spreads a dictionary
 
@@ -149,11 +153,12 @@ A prefix written with a trailing slash leaves the composed path with two. Werkze
 
 ## 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.
+A route ends where it returns and where it raises, and each of those places is
+what makes 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 |
 | --- | --- |
@@ -161,7 +166,7 @@ of an earlier arm, and the budget are all shared with TypeScript.
 | `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 |
+| `return`, `raise` | `exit`, which is what gives each of them its own transition |
 | `break`, `continue` | `exit`, which the engine uses for reachability rather than as an outcome |
 | anything else | `opaque` |
 
@@ -182,6 +187,45 @@ 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.
 
+### A branch that ends by raising
+
+Most frameworks let a route end the request by raising rather than by
+returning, and the status the client receives is then whatever the raised
+call was given. A pack says which of its library's callables do that, under
+`responseStatusCalls`, and where each of them takes its status:
+
+```ts
+responseStatusCalls: [
+  {
+    callee: "fastapi.HTTPException",
+    statusKeyword: "status_code",
+    statusArgument: 0,
+  },
+],
+```
+
+`callee` is the name as the file imports it, module and name together, which
+is what tells FastAPI's `HTTPException` apart from a project class of the same
+name. A `raise` of one of these becomes a transition responding with that
+status, and so does a bare call to one written as a statement of its own,
+which is how Flask's `abort(404)` ends a request. So this handler:
+
+```python
+@app.get("/items/{item_id}")
+def show(item_id: int):
+    if item_id > 10:
+        raise HTTPException(status_code=404, detail="missing")
+    return {"id": item_id}
+```
+
+comes out as a 404 under `item_id > 10` and a 200 under its negation.
+
+A status the reading cannot resolve to a number is reported as the text it was
+written as, so the transition says a status was set without claiming which. A
+`raise` of anything the pack does not list is still a transition, with the
+exception type on it and no status, since the framework is the only thing that
+knows what it turns that exception into.
+
 ### Keying anything on a node
 
 tree-sitter hands back a fresh wrapper object every time a child is read, so
@@ -232,6 +276,15 @@ 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 chain also matches when the name it starts on is declared, where the chain
+is written, as one of the query types: a parameter annotated `db: Session`,
+a local bound by `session = Session()` or `with Session() as session:`, or a
+project function whose return annotation says `Session`. The type has to be
+imported from the pattern's module, so a project class that happens to share
+the name does not match. `recordsNothing` lists the methods on such a type
+that touch no rows of their own: `execute` runs a statement whose own chain is
+the read or write, and `close` manages the session.
+
 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:
@@ -240,11 +293,15 @@ site importing one matches on that:
 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.
+For one of these the function itself is the operation, so
+`update(User).where(...).values(...)` is an update however it ends.
+
+`fields` comes from the columns a query spells out, `User.id` in
+`select(User.id, User.email)`, and from the keywords of a call the pack lists
+under `valueMethods`, `name` in `.values(name="x")`. `selector` comes from
+the keywords every other call in the chain picks rows by, `id` in
+`filter_by(id=user_id)`. Raw SQL handed to `text` is read as its own effect,
+with the kind and table taken from the statement.
 
 ## Where a mount is written
 
@@ -296,7 +353,7 @@ Taking the only mount it could follow would put the route at `/test`, where no r
 
 Both of those qualifiers matter. Only counting loops keeps the ordinary case working: two factories that each register their own routers by name are not competing, because neither one could have registered the other's. Only counting a loop in a *different* place keeps a factory working when it mixes an explicit registration with a loop, since both of those run together whenever that function runs.
 
-A module-level mount is never dropped this way. It runs whichever factory the app calls. flask-restx trims at the constructor and not at the mount, because only the constructor's path goes through the property that strips it. The pack declares trimming per library, and the mount side does not need it, since a mount that states a prefix on that library abstains anyway.
+A module-level mount is never dropped this way. It runs whichever factory the app calls.
 
 ## What a file reads from the environment