rpicard/explore-flask

Source of Explore Flask book

explore-flask's Issues

Add mention of testing to 7##Refactoring small apps to use blueprints

From @willkg

These sections are the home page, the user dashboard, the admin dashboard, the API and the company blog.

Before launching into steps, it's probably helpful to note that this is a refactoring and like any code refactoring, it's really handy to have decent tests so you can catch regressions caused by refactoring.

Incorrect information in 6##View decorators

From @willkg

Python decorators let us modify functions using other functions. When a function is “decorated” with another function, the decorator is called and can then call the original function, though it doesn’t have to.

So... this isn't really correct. "Decorators" in Python are just syntactic sugar for functions that take a function or class and return a function or class.

The wrapping function can do whatever it likes with the function argument including performing setup/teardown for the function/class, modifying the function/class, registering the function/class with some manager, modifying the function/class, ...

http://docs.python.org/2/glossary.html#term-decorator

Suggestion

Your book is very cool, and I'd like to propose a little suggestion. I came across gitbook tool and I really like it. Why don't you look and maybe you could use it for your book (https://www.gitbook.io)

pdf

Sample- https://github.com/realpython/about/blob/master/deployment.pdf

Would you like me to detail the steps on generating a PDF (as well as mobi and epub)? I can also set up a makefile to automate it.

content suggestion - add flask-testing extension

Add image credit to Dominic Flask

Need to make sure to include him in the next release!

Formatting in 4###Package

From @willkg

config.py
requirements.txt
run.py
instance/
  /config.py
yourapp/
  /__init__.py
  /views.py
  /models.py
  /forms.py
  /static/
  /templates/

This is totally a nit, but I wouldn't have a / at the beginning of these lines. The fact that they're indented suggests they're files in the parent directory.

In some places, I've seen lists. So something like this:

instance/
    * config.py
yourapp/
    * __init__.py
    * views.py
    * models.py
    * static/
    * templates/

Ch. 11 and 12 - Address logout CSRF issue

What is the best way to handle logouts? Is it a CSRF protected form inserted onto every page with a logout link? That sounds like a pain in the ass. Should it just be shrugged off as insignificant? That doesn't sit right with me.

Update Sphinx theme

Bold fonts are not correctly displayed in Google Chrome. See here: readthedocs/sphinx_rtd_theme#121

Ch. 11: Can input field HTML attributes be defined in the class or only on calling the field

[preface] the Youtube link is dead

The link on the preface page (talk with Armin Ronacher) is dead now.

https://github.com/rpicard/explore-flask/blob/master/source/preface.rst#id5

Move debugging chapter closer to beginning

From aezell on Hacker News:

I love this. I think it would be useful to move the debugging chapter much earlier in the book. Presumably, new users of Flask will encounter the (pretty awesome) Werkzeug error page as they move through the book. It might work well if a debugging chapter had exposed them to a little bit of how to interpret and use that tool. I'm sure there's a lot more about debugging to cover so maybe splitting things up makes sense too.

https://news.ycombinator.com/item?id=6834818

Ch. 8: Add section on Null Master fallback

From @willkg

Part of me wants to suggest adding a section on null-master fallback because it’s so interesting and has a few helpful use cases. But it’s also pretty esoteric. I think I’ve used it once.

Awkward wording in 4##definitions

From @willkg

but that’s out of the scope here

This feels a little awkward. Maybe "but I'm not going to talk about that right now" or "but that's a topic for another time" or even just leaving this part of the sentence out altogether?

What about a chapter about Security?

Hi,

it would be nice if there was also a chapter dedicated to the most common security best practices when using Flask.

Hyperlink issue in environment page

"To install virtualenvwrapper, follow the instructions in the documentation. See Box~ref{aside:vwrap_docs} for that link."

It seems like "Box~ref{aside:vwrap_docs}" should be a link, but that's not how it shows up on the page.

Table Of Content broken

This is how it looks when I open in Preview (Mac). The chapters appear to be all there but nested instead of side by side.

Change variable names in 7###Using a dynamic subdomain

From @willkg

# Note that the capitalized Site and the lowercase site
# are two completely separate variables. Site is a model
# and site is a blueprint.

Pretty sure the Flask docs use "mod" and "bp" for Blueprint instances. I use "mod". That reduces the name collision problems here especially when you get into "I need a variable to hold an instance of the Site model" kinds of things.

URL Converters section should go first in 6

From @willkg

It's likely this section is the most generally useful in this chapter, so I'd put it first.

flask login

Flask-Login does not handle authentication at all. In fact, in your example, you are handling authentication manually by verifying the supplied username and password with the username and password in the database.

Thus, this is wrong:

1. "This extension simplifies the process of handling user sessions and authentication."

This, implies that Flask-Login is handling auth -

1. "Now we can define the signin view that will handle authentication."

If you agree, I will update the wording in the chapter. And add wording in about ways of handling authentication - username/password, persona (https://github.com/garbados/flask-browserid)

Roadmap to 1.0

Grammar

Plan to write a static analysis script to check for these things once I've decided on the best choice for grammar.

• Decide on contractions (it's, we'll, I'll, you'll)

Front matter

• Thank the people who need thanking
• Update release notes

Formatting

• Note boxes
• File names should be italics
• Interesting terms should be bold
• Listings should be formatted in appropriate boxes
• References (internal and external) should be checked

Kickstarter

• Mail postcards
• Mail stickers
• Mail print books at 1.0
• List names of $50+ backers
• Encode $100+ backers
• Balanced logo

Compress and compile static assets on Flask initialization rather than on first request

In Ch. 9. See here: #29 (diff)

email confirmation

you should really encode the user id as well (with it's dangerous), and then confirm it, to make certain that specific confirm email is associated with the right email (in case multiple emails are registered). this is also a security issue.

also, you reference a flask-mail method that you don't mentioned anything about - send_mail

Add research process info to website

From OverTheHillCoder on Reddit:

One thing I noticed is that your kickstarter page has a section where you tell a bit about yourself and the list of experts you've been consulting to write the book. That info is missing from your site landing page. I know when I go to a new sales site in my mind I'm asking myself questions like "Who is this person?", and "What can they do for me?". Your kickstarter page covered that well. Good luck with the book. I plan on buying a copy in the next couple of days.

http://www.reddit.com/r/flask/comments/1rx1xb/explore_flask_patterns_and_best_practices_most/cdrywjb

Build order inconsistent

The expression used: {1,2,3,4,5,6,7,8}*.md leads to the PDF building in a non sequential manner.

The way they are built is

1,10,11,12,13,2,3...

This small shell command gives what is required but I am still looking at how to integrate it into the Makefile:

find . -regex '^.*\d*-.*\.md' -maxdepth 1 | xargs basename | sort -n -t - -k1 | tr "\\n" " "

content suggestion - add basic deployment options

Clarification in 6###Built-in converters

From @willkg

string: accepts any text without a slash (the default)

Does "text" include alphanumeric characters and punctuation? If so, might as well explicitly state that.

Ch. 8: Use a different Jinja filter example

From @willkg

In response to: e97a3ad#diff-4828b9b6c796c267e80c7517c9f86dabR128

I think this Note suggests we should use a different filter example.

Maybe a filter that takes an email address and generates a gravatar url?

Note should be added in 5##The simple case

From @willkg

app.config.from_object('config')

I think you should either explicitly state that this string is in Python module format and needs to be on the Python path or point to the Flask documentation for this method.

Dead link referenced on Blueprints page

A note on the Blueprints page says:

"At the time of writing this, the Flask website at http://flask.pocoo.org uses this structure. Take a look for yourself on GitHub."

and refers to this link.

However, the correct link seems to be this.

Broken Link on Bluprints Page

Hi,

The note about Functional structure gives Flask website as an example but the link to the repository is broken. I guess it should be this one.

vector graphics

The chapter illustration are lovely and seem potentially useful for repurposing (e.g. in presentations, articles etc. - thanks to you putting the contents in the public domain, of course).

It seems like they might have been created as vector graphics originally - if that's the case, could you make them available as SVGs?

`import .views` in blueprinst.rst

There are two places in blueprints.rst that include the line import .views, which produces a SyntaxError for me in both python 2.7.11 and python 3.5.1.

I believe this should be changed to from . import views.

"has" instead of "as" in 7Why would you use blueprints?

This line:

This allows you to structure your app has several smaller “apps” that each do one thing.

Should read as:

This allows you to structure your app as several smaller “apps” that each do one thing.

Syntax highlight

For some reasons, there is no syntax highlight for the last code example of Custom Validators section at the https://exploreflask.com/forms.html#custom-validators. At least at readthedocs.org service.

Links errors on environment.html

currently it is showing:

• That virtual environment directory created in Listing~ref{code:venv_create} adds clutter to your project repository.
• To install virtualenvwrapper, follow the instructions in the documentation. See Box~ref{aside:vwrap_docs} for that link.

LaTeX feature requests

1. The Latin Modern (and the original Computer Modern) fonts have a very ugly monospace font. Use \usepackage{DejaVuSansMono}, alternatively \usepackage{beramono}* if DVSM does not exist; if none work you need to install the DejaVuSansMono (or dejavu) package.
2. Please install the upquote package, as lines 7 and 8 suggest to have stuff in look better. Even if you have it, please also revise quotes (both " and ') in your code; for example the Hello World uses fancy Unicode quotes and does not run under any Python!
3. I hope you will work on the “final” version of the book in LaTeX itself and not in Markdown (which is a very unpythony choice anyways). I can offer some LaTeX advice if needed.

* some people suggest \usepackage[scaled]{beramono}

Flask Docs Sphinx Theme for Exploreflask.com

Please consider switching to Flask Sphinx theme (https://github.com/mitsuhiko/flask-sphinx-themes) for exploreflask.com.

Create exploreflask.com

Need to create a marketing site for the book.

Probably just 1 page with information, a cover image and a purchase link. On the purchasing link note, I'm thinking of doing a pay-what-you-want approach. Especially for early versions.

Gumroad modal not closing

From Silhouette on Reddit:

http://www.reddit.com/r/flask/comments/1rx1xb/explore_flask_patterns_and_best_practices_most/cdrslqk

They're in Firefox on Windows 7.

Notes on 4

From @willkg

Editorially doesn't let me pick an empty line to start a discussion on, so I'm starting it on this word.

This chapter is really great. But I think there are a couple of other things that should get covered.

There's an implied "if you outgrow this structure, you can switch to this structure", but I think there should be an explicit section about switching between structures. That's got to be a common scenario especially for projects that start off as prototypes.

One thing none of these structures explicitly show is a directory for tests. I think having that is important even if you're going to cover it in the test chapter. Location of tests is kind of a tricky thing sometimes and you could mirror your structure with tests. For example, in the blueprint structure, you probably want tests alongside the blueprints they're testing. I'd just add a tests/ kind of thing to each of the structures where it naturally fits even though there are a bunch of options.

The blueprint section should also cover the fact that many Flask extensions are blueprints. Blueprints allow you to use functionality other people wrote and also to extract functionality you wrote and spin it off into a new Flask extension project. You don't have to go into crazy detail about this, but a paragraph would be good.

The See Also list should point to the chapters on configuration, templates and other things that are mentioned in this chapter.

Good job! I like it!

Incorrect information in 6###Custom decorators

From @willkg

2: @wraps is a decorator that tells Python that the function decorated_function() wraps around the view function func().

This isn't quite right. All it's doing is some bookkeeping so that the decorated_function() "looks like" the wrapped function for the purposes of documentation and debugging. It's not really telling Python anything.

content suggestion - add basic development to deployment workflow

For example -

1. Feature Branch
2. Create PR
3. Run CI
4. Merge
5. Auto deploy to staging
6. Test
7. Auto deploy to production

I'm a fan of Docker for this. Docker, Jenkins, Digital Ocean

Book Translation

Can I start a translation of the book to Brazilian Portuguese? And have you any recommendation on that?

Great work! Great book about flask

@rpicard

Just finish reading for the book, very helpful to me.

Thanks!

Content suggestion in 6###Authentication

From @willkg

Only an authenticated user will be able to access the /dashboard route. You can configure Flask-Login to redirect unauthenticated users to a login page, return an HTTP 401 status or anything else you’d like it to do with them.

This is a good spot for a SEE MORE with the link to the Flask-Login docs.

Handling Users

Hi Robert,

Thank you very much for your excellent book. My apologies in advance if this is an obvious answer as I am somewhat new to flask. In this chapter, it seems you describe several account creation methods - "create_account" and "signup" to be specific - which don't appear to work together. Also, you only describe a User model once, and it only contains columns for 'username' and '_password', whereas earlier you mention creating an instance of the User class with 'email' and 'password', as well as an 'email_confirmed' boolean. I am confused as to if this chapter is meant to have any coherence throughout the code samples or if I am missing the logic. I see most of the snippets building off of eachother and then some not at all.

Thanks for your thoughts in advance,
Mark

Form chapter: Unique validator missing init message

In Handling Forms chapter, Unique validator doesn't initialize message. Should be changed to this:

def __init__(self, model, field, message=u'This element already exists.'):
    self.model = model
    self.field = field
    self.message = message

Incorrect imports in Handling Forms

The Handling Forms page has the following imports for WTForms:

from flask.ext.wtforms import Form
from wtforms import TextField, PasswordField, Required, Email

However, these have changed in 0.9.0 and now produce errors if run. These are the correct imports:

from flask.ext.wtf import Form
from wtforms.fields import TextField, PasswordField
from wtforms.validators import Required, Email

Ch. 8: Tweak explanation of context

From @willkg

[...] Then you can tweak the rest of the paragraph to talk about the environment context formed by Flask's context processors and also the developer's context processors.