6 ms·

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

48 points by rpicard 13y ago

apl 13y 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.
- rpicard 13y 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 13y 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!
    - rpicard 13y ago
      Thanks for the tip! I don't know if I would have thought to set another date after missing the first. Hopefully I won't have to, but if the time comes I'll keep that in mind.
taude 13y 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.
- taude 13y 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.
wbond 13y 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 13y 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/ http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/ Edit: they = Flask and some dependencies
- bsg75 13y 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-webframeworks.html http://www.pythondiary.com/blog/Feb.14,2012/too-many-micro-w...)
- taude 13y 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.
- rpicard 13y 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 https://news.ycombinator.com/item?id=5757038
kfk 13y 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-get-call-delivered-by-flask-web-framework-call-fails 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
- taude 13y 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-about http://stackoverflow.com/questions/2067472/what-is-jsonp-all...
- alptrv 13y 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/ http://www.w3.org/TR/cors/
- rpicard 13y 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.
bsaul 13y 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).
- rpicard 13y 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?
  - bsaul 13y 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.
    - rpicard 13y ago
      That's very interesting. I'm making a note of this for inclusion in the book.
sheakluse 13y 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/ http://www.realpython.com/
- rpicard 13y ago
  Thank you! The writer of that has actually contacted me too!

48 points by rpicard 13y ago

apl 13y 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.

rpicard 13y 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 13y 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!
  - rpicard 13y ago
    Thanks for the tip! I don't know if I would have thought to set another date after missing the first. Hopefully I won't have to, but if the time comes I'll keep that in mind.

taude 13y 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.

taude 13y 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.

wbond 13y 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 13y 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/ http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/ Edit: they = Flask and some dependencies
bsg75 13y 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-webframeworks.html http://www.pythondiary.com/blog/Feb.14,2012/too-many-micro-w...)
taude 13y 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.
rpicard 13y 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 https://news.ycombinator.com/item?id=5757038

kfk 13y 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-get-call-delivered-by-flask-web-framework-call-fails 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

taude 13y 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-about http://stackoverflow.com/questions/2067472/what-is-jsonp-all...
alptrv 13y 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/ http://www.w3.org/TR/cors/
rpicard 13y 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.

bsaul 13y 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).

rpicard 13y 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?
- bsaul 13y 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.
  - rpicard 13y ago
    That's very interesting. I'm making a note of this for inclusion in the book.

sheakluse 13y 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/ http://www.realpython.com/

rpicard 13y ago
Thank you! The writer of that has actually contacted me too!