docs(v4): update Python code snippets/links/details by vdice · Pull Request #1 · itowlson/spin-docs

vdice · 2026-04-08T18:57:24Z

TODO (either here or in follow-ups):

more updates to python-components.md? I didn't want to step on your toes (re: spinframework@df70d5a#diff-ca0ac8f75876532d1d35b81ee3842b95b68d6d61aed6abc887510aebce5133af)
links to the spin-python-sdk GH repo (eg example apps) shouldn’t use main - will there be a v4 tag? edit: possibly maybe

Signed-off-by: Vaughn Dice <vdice@akamai.com>

itowlson

This is great, thank you so much for getting it done. I had a few wording suggestions and there is one place I think we need to go async but otherwise looking really good!

itowlson · 2026-04-08T20:08:42Z

+> [**Want to go straight to the reference documentation?**  Find it here.](https://spinframework.github.io/spin-python-sdk/v4/http/index.html)

-HTTP functions and classes are available in the `http` module. The function name is [`send`](https://spinframework.github.io/spin-python-sdk/v3/http/index.html#spin_sdk.http.send). The [request type](https://spinframework.github.io/spin-python-sdk/http/index.html#spin_sdk.http.Request) is `Request`, and the [response type](https://spinframework.github.io/spin-python-sdk/v3/http/index.html#spin_sdk.http.Response) is `Response`. For example:
+HTTP functions and classes are available in the `http` module. The function name is [`send`](https://spinframework.github.io/spin-python-sdk/v4/http/index.html#spin_sdk.http.send). The [request type](https://spinframework.github.io/spin-python-sdk/http/index.html#spin_sdk.http.Request) is `Request`, and the [response type](https://spinframework.github.io/spin-python-sdk/v4/http/index.html#spin_sdk.http.Response) is `Response`. For example:


Should the request type link have a v4 in it?

👀 great catch!

itowlson · 2026-04-08T20:11:51Z

 from spin_sdk.http import Request, Response, send
-response = send(Request("GET", "https://random-data-api.fermyon.app/animals/json", {}, None))
+
+class WasiHttpHandler030Rc20260315(http.Handler):


I would drop this. I'd recommend just showing the send line, as the previous fragment did - I don't think we need to show a full request handler. (But if we do, I'd prefer to avoid such a distractingly long class name!)

What is your stance now that the class name is HttpHandler? Although I appreciate that it is clearer/more obvious to just show the send line, it won't be runnable (or 'compilable') as is. Maybe we add 'snippet' indications? Also, most/many of the other Python code samples do include the full class/handler declarations and it would be nice to keep consistent one way or the other.

For myself I am happier with snippets that show me the one thing the text is describing, so that I don't need to parse it out from the boilerplate. But I know many others feel differently, and it's certainly not a hill I intend to die on, at least not in the context of this PR. So I'm happy with whatever you prefer, and agree on the value of consistency.

itowlson · 2026-04-08T20:13:37Z

+> [**Want to go straight to the reference documentation?**  Find it here.](https://spinframework.github.io/spin-python-sdk/v4/)

-In Python, the application must define a top-level class named IncomingHandler which inherits from [IncomingHandler](https://spinframework.github.io/spin-python-sdk/v3/http/index.html#spin_sdk.http.IncomingHandler), overriding the `handle_request` method.
+In Python, the application must define a top-level class named `WasiHttpHandler030Rc20260315` which inherits from [http.Handler](https://spinframework.github.io/spin-python-sdk/v4/http/index.html#spin_sdk.http.Handler), overriding the `handle_request` method.


WasiHttpHandler030Rc20260315

EGAD

Do we really have to call it that?

Your wish is dicej's command 🪄

itowlson · 2026-04-08T20:41:25Z

 {{ startTab "Python"}}

-In Python, the handler needs to implement the [`InboundRedis`](https://spinframework.github.io/spin-python-sdk/v3/wit/exports/index.html#spin_sdk.wit.exports.InboundRedis) class, and override the `handle_message` method:
+In Python, the handler needs to implement the [`SpinRedisInboundRedis300`](https://spinframework.github.io/spin-python-sdk/v4/wit/exports/index.html#spin_sdk.wit.exports.SpinRedisInboundRedis300) class, and override the `handle_message` method:


Oh this one only needs to implement the base class? The application class doesn't need a specific name itself the way we said HTTP did?

itowlson · 2026-04-08T20:43:06Z

 {{ startTab "Python"}}

-In Python, the handler needs to implement the [`InboundRedis`](https://spinframework.github.io/spin-python-sdk/v3/wit/exports/index.html#spin_sdk.wit.exports.InboundRedis) class, and override the `handle_message` method:
+In Python, the handler needs to implement the [`SpinRedisInboundRedis300`](https://spinframework.github.io/spin-python-sdk/v4/wit/exports/index.html#spin_sdk.wit.exports.SpinRedisInboundRedis300) class, and override the `handle_message` method:


Is it at all possible to alias or wrap this? We know it's Spin because this is the Spin SDK, the 300 is clutter, and SpinRedisInboundRedis is a heck of a lot of Redises to pack into four words!

itowlson · 2026-04-08T20:45:45Z

+    async def handle_request(self, request: Request) -> Response:
+        with await sqlite.open_default() as db:
+            result = db.execute("SELECT * FROM todos WHERE id > (?);", [Value_Integer(1)])
            rows = result.rows


This still works because I added the async stuff backward compatibly in a 3.x interface, but we should really be encouraging people to use the async forms (and ideally the SDK would only surface the async forms, i.e. SDK execute maps to WIT execute-async).

Thanks, created spinframework/spin-python-sdk#146

itowlson · 2026-04-08T20:47:09Z

 **General Notes**
-* The `execute` method returns [a `QueryResult` object](https://spinframework.github.io/spin-python-sdk/v3/wit/imports/sqlite.html#spin_sdk.wit.imports.sqlite.QueryResult) with `rows` and `columns` methods. `columns` returns a list of strings representing column names. `rows` is an array of rows, each of which is an array of [`RowResult`](https://spinframework.github.io/spin-python-sdk/v3/wit/imports/sqlite.html#spin_sdk.wit.imports.sqlite.RowResult) in the same order as `columns`.
-* The connection object doesn't surface the `close` function.
+* The `execute` method returns [a `QueryResult` object](https://spinframework.github.io/spin-python-sdk/v4/wit/imports/spin_sqlite_sqlite_3_1_0.html#spin_sdk.wit.imports.spin_sqlite_sqlite_3_1_0.QueryResult) with `rows` and `columns` methods. `columns` returns a list of strings representing column names. `rows` is an array of rows, each of which is an array of [`RowResult`](https://spinframework.github.io/spin-python-sdk/v4/wit/imports/spin_sqlite_sqlite_3_1_0.html#spin_sdk.wit.imports.spin_sqlite_sqlite_3_1_0.RowResult) in the same order as `columns`.


We should be sending people to execute_async (and wrapping it in the SDK so they don't need to use the wart).

Tracking in spinframework/spin-python-sdk#146

Co-authored-by: itowlson <github@hestia.cc> Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice · 2026-04-09T17:36:02Z

@itowlson I added all of your code suggestions and then fixed up other feedback in the subsequent commit. Let me know if I missed anything or if new items come up.

Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice · 2026-04-09T17:59:22Z

@itowlson shall I look at updating v4/python-components.md next, now that you've added specific notes around async? Or did you have some changes in the works already?

itowlson · 2026-04-09T20:46:58Z

@itowlson shall I look at updating v4/python-components.md next, now that you've added specific notes around async? Or did you have some changes in the works already?

That would be brilliant - thank you!

Signed-off-by: Vaughn Dice <vdice@akamai.com>

itowlson

LGTM - I suggest we get this merged and update things like SQLite async as they come - is that okay?

vdice · 2026-04-09T23:01:34Z

@itowlson yes, please merge when convenient. Will look into spinframework/spin-python-sdk#146 tomorrow.

docs(v4): update Python code snippets/links/details

343cbf3

Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice mentioned this pull request Apr 8, 2026

Spin 4.0 spinframework/spin-docs#183

Merged

itowlson reviewed Apr 8, 2026

View reviewed changes

vdice mentioned this pull request Apr 9, 2026

modules(db): only surface async methods spinframework/spin-python-sdk#146

Closed

Apply suggestions from code review

ac9a62d

Co-authored-by: itowlson <github@hestia.cc> Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice force-pushed the spin-4.0-py-api-and-code-updates branch from a6afd55 to 6f97b0a Compare April 9, 2026 17:34

docs(content/v4): further Python SDK/example amendments

8e2bf4c

Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice force-pushed the spin-4.0-py-api-and-code-updates branch from 6f97b0a to 8e2bf4c Compare April 9, 2026 17:43

docs(content/v4): python-components.md snippets/links updates

35340db

Signed-off-by: Vaughn Dice <vdice@akamai.com>

vdice requested a review from itowlson April 9, 2026 22:05

itowlson approved these changes Apr 9, 2026

View reviewed changes

itowlson merged commit 1250ba3 into itowlson:spin-4.0 Apr 9, 2026

Conversation

vdice commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itowlson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vdice commented Apr 9, 2026

Uh oh!

vdice commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itowlson commented Apr 9, 2026

Uh oh!

itowlson left a comment

Choose a reason for hiding this comment

Uh oh!

vdice commented Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vdice commented Apr 8, 2026 •

edited

Loading

vdice commented Apr 9, 2026 •

edited

Loading