Tutorial: step 3 (Installing as package) needs rationale

[uvtc]

Step 3 of the tutorial (installing flaskr as a package) needs rationale at the top. As it stands, that section of the tutorial tells the user out of the blue that they should install their webapp as a package, but doesn't say why. The user can already run their webapp via flask run, so it's not clear why they should at this point set up and install their package into their venv.

[davidism]

• It's installed like all other packages, rather than relying on injecting the current directory into sys.path. This means that it's importable as long as you're in the virtualenv, rather than needing to be at the root project directory.
• FLASK_APP can refer to it by name instead of path (or path to __init__.py). (This is true in some cases for non-installed packages in the next release, but installing is still recommended.)
• You can install entry points, which is especially helpful if you need to customize the CLI.
• You can deploy like any other Python library, by creating a wheel and installing it. The dev environment now mirrors the prod environment. This also helps you separate your app behavior from your repository structure.
• In Python 2 especially, it avoids common "everything at the top level" relative import problems.
• You can isolate your tests using tox.
• It prepares you for better organization for larger projects.

Basically, you get all the benefits of installing packages in general.

[uvtc]

Thanks, David. If I can figure out how it works without installing (posting in another thread), I'll create a PR for tutorial.

[davidism]

I don't want the tutorial to not install the project. We want to encourage installation.

[uvtc]

This is what I'm trying to understand (just posted to the ML). Isn't it customary to run from the project directory during development, without installing it? Trying to understand how development workflow goes, as opposed to deployment.

My guess is that there should be a paragraph at the top of this section saying something about how, in the end, you're going to want to be able to install as a package for a number of reasons, and so should set up your project that way from the start, but then describe how regular development works in the project dir.

Haven't gotten this working, nor finished reading the tut, so will get back to this! :)

[davidism]

"Regular development" is installing the package in develop mode. Yes, we should explain why, but no, we should not say that not installing the package is the way to do things.

[ThiefMaster]

During develop you should install it, but with -e so the installed package just references your source directory.

[uvtc]

BTW, my original comment on this issues was mistaken: I couldn't run my app with a simple flask run without first installing it. I was confused because the Quickstart doc did that with a simple standalone hello.py file, rather than as a package.

[davidism]

continued in #2513