

I'm writing a book on Flask, the Python web framework - rpicard
http://robert.io/blog/2013/05/22/im-writing-a-book-on-flask/

======
taude
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.

~~~
bsg75
> ...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?

~~~
taude
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.

~~~
codegeek
"Flask is like Legos in that you choose the pieces to build onto its
minimalist stack."

Very well said.

"best for new-comers to web dev to use a full stack that makes decisions for
you"

I do not agree. When I started learning web dev. using python, I started with
Django. As I moved along trying to hack a simple side project using django, I
realized that I was just not understanding the "why" of many things. For
example, I tried to create a simple user registration and needed my own fields
on the user object. Playing around with User and User_Profile on django, I
gave up after a few hours. When I came across Flask, I actually found it
easier to do some of my own stuff to understand the whys and then i could
always choose a vetted extension/plugin. For example, I wrote my own login
system in flask and then switched to Flask-Login later. Btw, this is not about
django vs flask but just giving a perspective as a newbie learner.

To newbies, my personal opinion is to understand the "whys" a lot more than
just the "what". I actually think that flask is a better way to start learning
because it will force you to think about the basics like sessions, user
management etc. The more you learn why something works the way it works, the
better you will become at it.

~~~
rpicard
This is just about the same experience that I had. If I'm recommending a
framework to a new developer (as I recently did) I go with Flask all the way.
You can start off with a simple one file app that serves your index, then when
you realize, "Man, this file is getting unruly," you can switch to using
modules. Then you think, "Man, I want my admin panel code to be separate from
my user dashboard code," and you learn about Blueprints.

The same goes for all of the plugins. You only have to add (and therefore
learn about) the "legos" -- to use taude's metaphor -- that you need to build
your spaceship.

~~~
bsg75
Is this an advantage of Flask having modules over the single file Bottle
framework, when apps evolve new features or use cases?

~~~
rpicard
Is Bottle limited to a single file? I have never really played with it. If so,
I'd definitely say that it's an advantage for Flask.

~~~
bsg75
I believe it is: "Bottle is a fast, simple and lightweight WSGI micro web-
framework for Python. It is distributed as a single file module and has no
dependencies other than the Python Standard Library."

~~~
rpicard
Oh, so the framework is a single file. Your app can be multiple files though,
right?

------
kfk
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...](http://stackoverflow.com/questions/16134164/jquery-ajax-json-get-
call-delivered-by-flask-web-framework-call-fails)), 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

~~~
alptrv
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/>

------
apl

      > 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
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
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
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.

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

------
sheakluse
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/>

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

------
wbond
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.

~~~
rpicard
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>

~~~
wbond
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.

~~~
rpicard
It's my understanding that Armin Ronacher -- the creator of Flask -- has been
making a lot of progress lately on porting to Python 3.[1] I don't think it's
ready for production yet, but it's definitely something to keep an eye on. I
might make it a point to address it in the book.

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

