documentation - patterns - larger applications - add link to explain why "Python does not want modules in packages to be the startup file"

[zachvalenta]

This paragraph:

But how do you run your application now? The naive python yourapplication/__init__.py will not work. Let’s just say that Python does not want modules in packages to be the startup file.

could be summarized as:

You can't do that, and we won't explain why; just trust us.

In lieu of actually explaining, a link to the Python docs that actually do explain what's going on here seems in order.

[davidism]

A much more charitable and less snarky summary would be "plenty of our developers over years have experienced weird behavior when trying to run packages directly like that, but there's no straightforward documentation of all Python's weird behaviors; just trust us."

I'm not sure where that reference is, if it exists. I guess pallets/werkzeug#1416 is a good writeup of some of the the behavior I've encountered recently, but it's not something I want to subject most users to reading. If you have a reference to add, I'm happy to consider a PR, but I'm going to close this for now.

[zachvalenta]

Your summary works for me. Having it footnoted, with a link to the Werkzeug ticket you mentioned, is a solution I like. If that makes since to you, would be happy to open PR.

Sorry if the ticket came off snarky. What I'm getting at here is that this section of the docs proposes a big leap for someone with a basic Flask app:

• refactoring project directory structure
• moving the app obj to __init__.py (a non-trivial piece of Python import's system to understand)
• adding setup.py (which a newer developer might typically hear about in the context of distribution and distutils)

Given the big leap, felt like the existing explanation didn't sufficiently sell the necessity of making such changes.

I realize the Flask docs have been trying to walk the line between friendly-for-newcomers and scalable project structure since the rewrite for 1.0. My bias is friendly-for-newcomers; I realize it's a bias and hopefully am not being dismissive of other perspectives here.

Either way, thanks for responding, and thanks for passing along that Werkzeug ticket; really shows how hairy the problem can get :)