I'm writing a book on Flask, the Python web framework

http://robert.io/blog/2013/05/22/im-writing-a-book-on-flask/

by rpicard • 13 years ago

48 40 13 years ago

apl• 13 years ago

  > I have June and July to write, edit, market, and launch
  > the book. It may be slightly ambitious, but I plan to
  > have a lot of time on my hands.

That'd be an absurdly demanding schedule for an experienced author and seasoned web programmer. Good luck; regardless of what comes out of it, it's a decent exercise.

rpicard14• 13 years ago

I think that depends on the parameters. I'm imagining a length of around 100 pages (though I'll have to see where the book takes it, I don't want to force any particular length). Also, I'm self publishing so there isn't any red tape to deal with editors and what not. I'll probably send it to a couple of people for a grammar review, and a couple of people for a technical review.

At least that's what I'm telling myself. I know Sacha Grief published his book in something like three weeks, though it was shorter than what I'm going for and he's more experienced with his topic.

Nonetheless, you're right that regardless of what comes out of it, it'll be a decent exercise.

ktf• 13 years ago

Just don't give up if you don't hit your date! I edited technical books for four years and never once had an author actually hit their target date.

But do set a new target date if you miss your original one. Having a big red circle on the calendar can be an amazing motivator, even if there's no consequences for missing it.

Good luck!

taude8• 13 years ago

Some random thoughts: I think the documentation for Flask is pretty good. By it's nature, it's not a framework for new web developers, so I don't think all the general regurgitated stuff that usually goes into books should be included. It's not for beginners, don't try to make it so.

What I see as being a useful book on Flask:

1) listing and naming common stable plugins (flask-security, flask-login) and how they integrate and work together. There's a good page on the Flask site, but I feel a lot of the plug-ins don't work particularly well together. There's tons of different authentication librarys (especially when dealing with OAuth) that work with varying degree out there. Some guidance around this would be really useful.

2) Different ways to setup a large project. How to structure folders, etc. There's some good topics on StackOverflow about this, but my experience trying to integrate different plug-ins, etc, leads to a more messy solution. Maybe some ideas in abstracting out data access.

3) The Art of building up your tech stack with lego bricks. Choosing which plug-ins to use.

4) Testing patterns.

5) More of a style of "I'm trying to do this", this is how you do it. (Note: there's lots of great questions and solutions on the email list that could/should be culled for ideas and consolidated)

6) Debugging and tracing through 3rd party flask-plugins. This is a huge problem for me as most don't include log comments

7) Writing and structuring a good plug-in/blueprint, with some examples of different ways to include reusable code into the project.

Note: I've co-authored a book in the past that was published by Wiley and I think your schedule is pretty optimistic, especially considering you've still got some learning and research to do. Unless, you're just regurgitating the already pretty in-depth documentation.

Second Note: I'm just reading the O'Reily book on Angular.JS, it's less that 200 pages. It's dense with ideas and explanations on WHY something is. This makes it extremely useful. I really like books that focus on the WHY, because the HOW because much simpler to comprehend. I also appreciate the book because it's not some 600 page tome of regurgitated documentation.

taude8• 13 years ago

I had some more ideas about the plug-in development section:

1) offer guidance on making appropriate configuration guidelines

2) suggestions on how to structure a plugin so the view templates can be easily customized or overwritten. Same with the route logic. Same with the controller.

3) decoupling code with signals and blinker.

Generally, how to make a plug-in that provides enough hooks so someone using it doesn't just have to fork their own code off of it.

taude8• 13 years ago

Actually, I've thought about this a bit more....there could be a whole book of guidance written about how to create a flask-plugin to be consumed by other users.

bsg754• 13 years ago

> ...Flask is pretty good. By it's nature, it's not a framework for new web developers...

Curious (and no experience web dev-ing here), why not? Flask and Bottle seem "minimalist", which in my thought process means less stuff to worry about to start simple apps in.

This logic could of course be upside down - less framework = more code to write?

tjr• 13 years ago

I wondered the same thing. I've not used Flask, but perusing the documentation, it looks pretty similar to CherryPy, which is the only web framework I've ever used (and thus, my first).

Django looked too confusing! :-)

MostAwesomeDude• 13 years ago

Neither. Flask presumes that you know Python and that you understand how requests and responses work. This isn't impossible for a beginner, but it's certainly not likely.

Flask's main API is heavily based on decorators, and those are a perennial problem for new programmers.

taude8• 13 years ago

It will vary what your definition of simple app is. Simple as in "doesn't do much", or simple as in "minimalistic for a real world use case", in which case session management, login, security, authentication/authorization, template rendering, data access, etc. are all going to be required. I say "mimimalistic for real world use" because I have yet to create an application that didn't include all these things (at a minimum). Of which, you need to be aware of, so you can choose the appropriate library for your application.

Flask is like Legos in that you choose the pieces to build onto its minimalist stack. You can use if for lightweight prototyping or full-blown web apps.

Since all these things "are a worry", it's probably best for new-comers to web dev to use a full stack that makes decisions for you, that has cohesive documentation across components, and a large contingent of users.

rpicard14• 13 years ago

As I'm formulating the exact focus of the book I've been finding myself wondering how much introductory material I should include. I think you're right about leaving as much out as possible. When there is prerequisite knowledge for a particular topic, I can just point them to the documentation and avoid cluttering the book with that stuff.

Regarding the schedule, since I've gotten I few comments on this I'm starting to think it might have a little weight to it. I'm pretty determined to get it done by that launch date, but my primary concern is writing a really good book. If I must delay launch, I'd rather do that than rush it.

I really like the idea of explaining the "Why?" Do you mean explaining why certain practices are preferable, or why the creators of plugins and Flask itself did certain things?

Also, your notes are all amazing and I'll be referring to them as I outline the book!

wbond2• 13 years ago

I'm curious, and not just from the author, but why Flask and not something like Bottle? After recently starting a Python 3 web project I was disappointed to see that Flask and many of its main dependencies don't run on Python 3.

Don't get me wrong, Flask seems to have a lot of mind-share, it just seems like a lot of people would be interested in working with Python 3.

fallenhitokiri• 13 years ago

They are being ported to Python 3. You can find some infos about it in Armin Ronachers twitter stream and in this[1] blog post.

Personally I am in no hurry to switch to Python 3 and Flask "just works" and does everything I need in a, at least for me, sane way.

[1] http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/

Edit: they = Flask and some dependencies

bsg754• 13 years ago

The number of choices in the minimal framework category is a bit ironic. Hard to tell where to start. (re http://www.pythondiary.com/blog/Feb.14,2012/too-many-micro-w...)

taude8• 13 years ago

One of the reasons I went with Flask over one of the other minimalit frameworks was the plugin support. There's "just enough" existing code to get you up to speed quickly without acquiring all the technical debt of a full-fledged framework stack.

I used and played with bottle first, and seriously thought about it for implementing my restful-ish APIs.

rpicard14• 13 years ago

I don't have extensive experience with other Python frameworks, but what attracted me to Flask is what taude said.[1] There is just enough existing code to get you started and you don't have all of the technical debt of a full-fledged framework.

When I was starting, my first thought (like most people) was to work with Django, but what drove me crazy was that my project started with a bunch of files and code that I didn't write. I want all of that to be abstracted away via plugins and modules, and Flask does that really well.

I'm not sure how that compares to Bottle or other Python frameworks, but I feel like Flask suits me perfectly.

Regarding Python 3 support, a port is in progress so as Python 3 gains traction I think Flask will emerge as part of that transition, but for now Python 2 works well for most people.

[1] https://news.ycombinator.com/item?id=5757038

wbond2• 13 years ago

Yeah, I just didn't want to acquire all of the technical debt of starting a new project in 2.7 when 3 has been out for 5 years now and 2 is effectively in support mode. All new standard library enhancements will be in 3 and I can't imagine people will start many new packages that are 2.x only.

I haven't done much Python web development before, but I have a fair amount of experience with PHP and Ruby, so I found stitching together something useful with Bottle and a number of other packages was pretty low-friction other than porting a half-dozen different packages to Python 3. Unfortunately looking at flask it seemed the work to port it along with jinja2 and werkzeug was too much of a barrier to entry.

count• 13 years ago

A lot of people aren't interested in Python 3 yet, as you noted - many dependencies, etc. are not '3' compatible yet.

kfk• 13 years ago

I'd pay at least 30$ for a book that does an analysis of the Flask's source code explaining the basics of the http protocol and restful apis.

For example, I use jsonp and I use a decorator from the Flask snippets (http://stackoverflow.com/questions/16134164/jquery-ajax-json...), however, I have no idea how this works and why jsonp is better than json...

Then I would like the book to link these learning to building secure and well tested web applications.

The reasons why I would pay for this are: 1. I would like to build a spreadsheets sharing app but I am very scared of handling sensible data if I don't know very well (by very well I mean the source code) my tech stack and also I know little about web security 2. I would like to contribute to Flask development one day (because it's cool, let' be honest) 3. It takes too much time for me to find out these things on my own and I would gladly pay for the time I save with a book

taude8• 13 years ago

I don't know much about JSONP except it allows cross-domain JSON data access. To learn more than I know, check out this: http://stackoverflow.com/questions/2067472/what-is-jsonp-all...

alptrv• 13 years ago

Basically JSONP is used by API providers, so that theirs API might be called by JavaScript running in browser. Until CORS[1] got supported by current browsers, JSONP was used to get some JSON from an API located on different domain (well it of course can be used today for browsers that don't support CORS) The code snipped you linked just wraps standard JSON response making it an executable script that when included on the page calls the supplied callback's name passing the JSON.

1. http://www.w3.org/TR/cors/

rpicard14• 13 years ago

My concern would be that by analyzing the Flask source in addition to patterns and best practices for developing apps the book would lose focus.

It is something that I'll keep in mind in writing, but I think it might be better for another project.

bsaul2• 13 years ago

Building a flask app myself at the moment, a few (non obvious) things come to my mind :

- sqlalchemy integration by "hand" (not using flask-sqlalchemy module) : managing sqlalchmey session scope and lifecycle "in the middle" of the flask request lifecycle

- celery integration "by hand" : flask app configuration reuse by celery tasks.

- google app engine deployment

- uwsgi + nginx deployment

- user credential + session management.

+ a chapter on good REST JSON API architecture (eg : returning both HTTP error code along with JSON data).

rpicard14• 13 years ago

I appreciate the suggestions. Since it's something I'll want to consider writing about, why are you interested in the "by hand" integrations rather than using the Flask plugins?

bsaul2• 13 years ago

Because you really need to understand how things work to debug them sometimes. Personal example : flask-sqlalchemy binds the session lifecycle to the flask request lifecycle. 1 session <-> 1 request.

Now i've got celery tasks, and they're also using sqlalchemy, and all of the sudden, my celery tasks running on the same thread seem to keep the same session object for different tasks.

One solution (IIRC) was to create a new "fake" request context for each task, and then let sqlalchemy session bind to that fake request.

If i just plugged the flask-sqlalchemy module, i wouldn't have even known about session scopes, and would have looked at the celery bug with a blank stare.

Since flask is a micro framework it lets you customize those kind of things. But more importantly, it lets you LEARN about the issues in the first place. I think that's one of the major benefits of dealing with micro frameworks.

sheakluse• 13 years ago

Flask is a great book topic. So just an add on, I think it is always good to see what else is out on there on the topic as a starting point. And I just purchased this book that recently came out on Python for the Web and it speaks a lot about Flask as well. So it may be beneficial to look that over and see what that author already has out there, so you could expand or hit different points. Here's the link if you are interested, http://www.realpython.com/

rpicard14• 13 years ago

Thank you! The writer of that has actually contacted me too!

I'm writing a book on Flask, the Python web framework

Related Stories