add tutorial showing how to build something useful with Twisted Klein

[pawelmhm]

Flask or Django have nice tutorials that guide users through building some simple web application. It should be rather simple to write something like this for Twisted Klein. It should show some basic functionality: handling requests, connecting to database, using html templates, returning error codes etc. It should also demonstrate how to use deferreds and async code in real life practical scenarios.

[notoriousno]

What do you think is a good guide? I'd been thinking about this for a while but had little time and motivation. I'd be willing to help. I've got some basic examples in my repos and blog.

[pawelmhm]

What do you think is a good guide?

I actually started writing something. I thought about tutorial that will show simple application that acts as sort of reverse proxy for project gutenberg. The idea is that application shows simple index page with books. Books are stored in sqlite database and contain link to full text of book in project gutenberg. When user clicks on book it will download book with twister-treq on the server side - show to user - and cache in filesystem so that for next user download from gutenberg won't be performed.

For db I thought about sqlite. Downloading text of book with treq as example of using Deferred. Db transactions with ADB-API. At the end it would add user login. I have some of this written, will push it to some branch for feedback.

[notoriousno]

Sounds good to my ears. I can help review if you need it.

[wsanchez]

FWIW, I started this sample app for similar reasons: https://github.com/wsanchez/sample-klein-app

[glyph]

Oops. I didn't see this issue. Github emails me about comments on tickets where I participate but I'm pretty sure it's not emailing me about new tickets on projects. Is there a setting for that someplace?

In any case - I've been building the infrastructure I think we need for such a tutorial, particularly things like "a safe and sensible way to interact with databases" - you can see my ongoing work with that here - https://github.com/glyph/klein/tree/form-hacks

I still need to break up a lot of that work into sensible small changes, test them, and turn it into a series of PRs, but I've been waiting to try it on a small real-world application first. You can see that work here: https://github.com/twisted-infra/lists.twistedmatrix.com/ - hopefully it will start to bear fruit in the form of a live site soon.

[notoriousno]

@glyph You have to set the "watch: all conversations" settings. Then check your spam filter because all my emails go there :)

[pawelmhm]

I think we need for such a tutorial, particularly things like "a safe and sensible way to interact with databases"

@glyph wow this branch looks really big and your application lists.twistedmatrix is like you say in commit message almost like a framework :) Do we really need such complex "infastructure" for this simple tutorial? Or are you thinking about some e-learning platform for Twisted?

re: interacting with database in tutorial, I was thinking about simply sharing .csv file with database with users, and they will just run their own examples on their computers. My idea was to have something extremely basic, for total noobs that dont even know Python very well. Flask success in part is due to it's ability to appeal to noobs, would, be nice if Twisted could get them on board easily too.

[glyph]

Do we really need such complex "infastructure" for this simple tutorial?

There's one place that we do: form handling.

The naive approach to handling input in a web app is actively dangerous. It can easily allow any attacker that can get an authenticated user to click on any website to perform authenticated operations on yours. See here for more detail on this specific attack. This why the branch is called "form hacks".

We don't need SQL for a tutorial - but then, your proposed example already has SQL in it, it's just injection-prone plain-text SQL rather than properly expression-object data access as with SQLAlchemy or similar. And everyone is going to want to have some kind of backing database anyway.

I do think the tutorial should start out as light as possible, and introduce concepts gradually, but like it or not Klein is a web framework, and I think this example should be complete enough to prevent people from shooting themselves in the foot :).