From e6f9d2b41417b442946acfede9200d361ac401cc Mon Sep 17 00:00:00 2001 From: Kyle Lawlor Date: Thu, 8 Sep 2016 09:19:48 -0400 Subject: [PATCH] Clean up tutorial docs for installable app pattern with flaskr (#2002) * Clean up tutorial docs for installable app pattern - reading sequentially through the tutorial works. - fixes references to `export FLASK_APP=flaskr.flaskr` * Fixes titles for each section of flaskr tutorial * Revert grammar * Emphasize the Packaging Guide - adds more general packaging resource - removes the emphasis put on setuptools * rephrase and remove note admonitions - expanded on few points - removed note blocks, they are unneccessary * Remove note about reinstalling to update cli - I had mistakenly thought it was necessary to re-install the app to update the cli. - the `--editable` flag detects the change and the cli updates without issue. --- docs/tutorial/css.rst | 2 +- docs/tutorial/dbcon.rst | 2 +- docs/tutorial/index.rst | 2 +- .../{setuptools.rst => packaging.rst} | 47 ++++++++++++------ docs/tutorial/setup.rst | 2 +- docs/tutorial/templates.rst | 2 +- docs/tutorial/testing.rst | 48 +++++++++++-------- docs/tutorial/views.rst | 2 +- 8 files changed, 67 insertions(+), 40 deletions(-) rename docs/tutorial/{setuptools.rst => packaging.rst} (61%) diff --git a/docs/tutorial/css.rst b/docs/tutorial/css.rst index ea461a89..56414657 100644 --- a/docs/tutorial/css.rst +++ b/docs/tutorial/css.rst @@ -1,6 +1,6 @@ .. _tutorial-css: -Step 9: Adding Style +Step 8: Adding Style ==================== Now that everything else works, it's time to add some style to the diff --git a/docs/tutorial/dbcon.rst b/docs/tutorial/dbcon.rst index 9f4428b9..2dd3d7be 100644 --- a/docs/tutorial/dbcon.rst +++ b/docs/tutorial/dbcon.rst @@ -3,7 +3,7 @@ Step 4: Database Connections ---------------------------- -You now have a function for establishing a database connection with +You currently have a function for establishing a database connection with `connect_db`, but by itself, it is not particularly useful. Creating and closing database connections all the time is very inefficient, so you will need to keep it around for longer. Because database connections diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index ccd4e7d2..f0a583e0 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -24,7 +24,7 @@ the `example source`_. folders schema setup - setuptools + packaging dbcon dbinit views diff --git a/docs/tutorial/setuptools.rst b/docs/tutorial/packaging.rst similarity index 61% rename from docs/tutorial/setuptools.rst rename to docs/tutorial/packaging.rst index 306d94d3..8db6531e 100644 --- a/docs/tutorial/setuptools.rst +++ b/docs/tutorial/packaging.rst @@ -1,7 +1,7 @@ -.. _tutorial-setuptools: +.. _tutorial-packaging: -Step 3: Installing flaskr with setuptools -========================================= +Step 3: Installing flaskr as a Package +====================================== Flask is now shipped with built-in support for `Click`_. Click provides Flask with enhanced and extensible command line utilities. Later in this @@ -9,17 +9,21 @@ tutorial you will see exactly how to extend the ``flask`` command line interface (CLI). A useful pattern to manage a Flask application is to install your app -using `setuptools`_. This involves creating a :file:`setup.py` -in the projects root directory. You also need to add an empty -:file:`__init__.py` file to make the :file:`flaskr/flaskr` directory -a package. The code structure at this point should be:: +following the `Python Packaging Guide`_. Presently this involves +creating two new files; :file:`setup.py` and :file:`MANIFEST.in` in the +projects root directory. You also need to add an :file:`__init__.py` +file to make the :file:`flaskr/flaskr` directory a package. After these +changes, your code structure should be:: /flaskr /flaskr __init__.py /static /templates + flaskr.py + schema.sql setup.py + MANIFEST.in The content of the ``setup.py`` file for ``flaskr`` is: @@ -46,22 +50,37 @@ following lines:: graft flaskr/static include flaskr/schema.sql +To simplify locating the application, add the following import statement +into this file, :file:`flaskr/__init__.py`: + +.. sourcecode:: python + + from flaskr import app + +This import statement brings the application instance into the top-level +of the application package. When it is time to run the application, the +Flask development server needs the location of the app instance. This +import statement simplifies the location process. Without it the export +statement a few steps below would need to be +``export FLASK_APP=flaskr.flaskr``. + At this point you should be able to install the application. As usual, it is recommended to install your Flask application within a `virtualenv`_. With that said, go ahead and install the application with:: pip install --editable . -.. note:: The above installation command assumes that it is run within the - projects root directory, `flaskr/`. Also, the `editable` flag allows - editing source code without having to reinstall the Flask app each time - you make changes. +The above installation command assumes that it is run within the projects +root directory, `flaskr/`. The `editable` flag allows editing +source code without having to reinstall the Flask app each time you make +changes. The flaskr app is now installed in your virtualenv (see output +of ``pip freeze``). With that out of the way, you should be able to start up the application. Do this with the following commands:: - export FLASK_APP=flaskr.flaskr - export FLASK_DEBUG=1 + export FLASK_APP=flaskr + export FLASK_DEBUG=true flask run (In case you are on Windows you need to use `set` instead of `export`). @@ -85,5 +104,5 @@ but first, you should get the database working. Continue with :ref:`tutorial-dbcon`. .. _Click: http://click.pocoo.org -.. _setuptools: https://setuptools.readthedocs.io +.. _Python Packaging Guide: https://packaging.python.org .. _virtualenv: https://virtualenv.pypa.io diff --git a/docs/tutorial/setup.rst b/docs/tutorial/setup.rst index 78b6390a..4bedb54c 100644 --- a/docs/tutorial/setup.rst +++ b/docs/tutorial/setup.rst @@ -94,4 +94,4 @@ tuples. In the next section you will see how to run the application. -Continue with :ref:`tutorial-setuptools`. +Continue with :ref:`tutorial-packaging`. diff --git a/docs/tutorial/templates.rst b/docs/tutorial/templates.rst index d6558233..269e8df1 100644 --- a/docs/tutorial/templates.rst +++ b/docs/tutorial/templates.rst @@ -1,6 +1,6 @@ .. _tutorial-templates: -Step 8: The Templates +Step 7: The Templates ===================== Now it is time to start working on the templates. As you may have diff --git a/docs/tutorial/testing.rst b/docs/tutorial/testing.rst index c5ecf7dd..dcf36594 100644 --- a/docs/tutorial/testing.rst +++ b/docs/tutorial/testing.rst @@ -9,10 +9,10 @@ modifications in the future. The application above is used as a basic example of how to perform unit testing in the :ref:`testing` section of the documentation. Go there to see how easy it is to test Flask applications. -Adding Tests to flaskr -====================== +Adding tests to flaskr +---------------------- -Assuming you have seen the testing section above and have either written +Assuming you have seen the :ref:`testing` section and have either written your own tests for ``flaskr`` or have followed along with the examples provided, you might be wondering about ways to organize the project. @@ -24,30 +24,38 @@ One possible and recommended project structure is:: static/ templates/ tests/ - context.py test_flaskr.py setup.py MANIFEST.in -For now go ahead a create the :file:`tests/` directory as well as the -:file:`context.py` and :file:`test_flaskr.py` files, if you haven't -already. The context file is used as an import helper. The contents -of that file are:: +For now go ahead a create the :file:`tests/` directory as well as the +:file:`test_flaskr.py` file. - import sys, os +Running the tests +----------------- - basedir = os.path.dirname(os.path.abspath(__file__)) - sys.path.insert(0, basedir + '/../') +At this point you can run the tests. Here ``pytest`` will be used. - from flaskr import flaskr +.. note:: Make sure that ``pytest`` is installed in the same virtualenv + as flaskr. Otherwise ``pytest`` test will not be able to import the + required components to test the application:: -Testing + Setuptools -==================== + pip install -e . + pip install pytest -One way to handle testing is to integrate it with ``setuptools``. All it -requires is adding a couple of lines to the :file:`setup.py` file and -creating a new file :file:`setup.cfg`. Go ahead and update the -:file:`setup.py` to contain:: +Run and watch the tests pass, within the top-level :file:`flaskr/` +directory as:: + + py.test + +Testing + setuptools +-------------------- + +One way to handle testing is to integrate it with ``setuptools``. Here +that requires adding a couple of lines to the :file:`setup.py` file and +creating a new file :file:`setup.cfg`. One benefit of running the tests +this way is that you do not have to install ``pytest``. Go ahead and +update the :file:`setup.py` file to contain:: from setuptools import setup @@ -58,7 +66,6 @@ creating a new file :file:`setup.cfg`. Go ahead and update the install_requires=[ 'flask', ], - ) setup_requires=[ 'pytest-runner', ], @@ -66,6 +73,7 @@ creating a new file :file:`setup.cfg`. Go ahead and update the 'pytest', ], ) + Now create :file:`setup.cfg` in the project root (alongside :file:`setup.py`):: @@ -85,4 +93,4 @@ found, run, and hopefully pass. This is one possible way to run and manage testing. Here ``pytest`` is used, but there are other options such as ``nose``. Integrating testing with ``setuptools`` is convenient because it is not necessary to actually -download ``pytest`` or any other testing framework one might use. \ No newline at end of file +download ``pytest`` or any other testing framework one might use. diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index d9838073..4364d973 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -1,6 +1,6 @@ .. _tutorial-views: -Step 7: The View Functions +Step 6: The View Functions ========================== Now that the database connections are working, you can start writing the