Login example broke the flow

[dansalmo]

I am very new to python, flask, heroku, git etc. but I was able to easily and successfully flow through the quickstart guide and get the minimal app deployed on heroku. I was very impressed with documentation flow and accuracy. However, I ran into a significant stumbling block with the "HTTP Methods" section. There were two issues that caused me stumble and I think others may stumble here as well.

The most significant issue was that the login example code calls descriptive stubs that don't exist. This may be fine for those that already understand what the example is showing, but for people like me that learn by trying to run the code examples, it took quite a while to figure that my app was crashing due to the non-existent function calls.

The second issue involves the difference between the flask routing and what I was familiar with for form processing in PHP. I initially expected something along the lines of a login.py script that would get invoked by action="http://mysite.com/login.py" attribute of the form.

Eventually I figured out how it worked by creating what I believe would be a more easily understood example for the method and form functionality. This is the code that I eventually created to learn and confirm the functionality.

Please consider revising the Flask example(s) to show code that can actually be executed like the previous examples I have tried, and to show what the HTML would look like if needed.

@app.route('/form', methods=['POST', 'GET'])
def form():
    if request.method == 'POST':
        return 'form POST dictionary: %s' % request.form
    if request.method == 'GET':
        return 'form GET args: %s' % request.args

<form method="POST" action="http://your_sites_url_here.com/form">
  Username: <input type="text" name="username" size="15" /><br />
  Password: <input type="password" name="password" size="15" /><br />
            <p><input type="submit" value="Login" /></p>
 </form>

[jasonLaster]

I like the pseudocode do_the_login() and show_the_login_form(). Maybe we can comment them out so that it's obvious that these two methods are not supposed to be run.

Also, I got stuck at this point too because I did not know that I had to import Request. Maybe it would be possible to link to a complete working example for each of these small examples so that it would be easy to see the important code and then copy and paste the full example and play with it?

[untitaker]

IMO it's obvious that functions you didn't import or define in your code don't exist.

[dansalmo]

Sometimes obvious is not good enough for a good user experience.

[untitaker]

This is not targeted to the end user though, also a developer should at least work through a basic introductory book before just trying.

Flask was made to make writing webapps faster in Python, but it will never work without a basic understanding of the language you're using.

[dansalmo]

A key reason Python is so popular is the usability of the language, available documentation and tools as compared to other languages. This seems to be by careful consideration and design. This particular example was a stand out exception that could be easily fixed. I am only qualified to say what I find easy to use and what I do not. Everyone is a user at all levels and designing frameworks and documentation that is easier to understand and use is very hard. Sometime the best you can do it put it out there and then improve it based on feedback.

[DasIch]

It's neither practical nor useful to make all examples executable, especially when in this case the focus is on abstractions. Of course in this case it could be turned into an executable example but it loses all information about potential use cases.

All of these different pieces of technolgy simply can't all be learned at the same time, at least not in a way that will provide you with a full understanding of them. Start learning Python and then build up on that step by step.