Merge branch '0.11-maintenance'

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

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

docs/tutorial/index.rst

@@ -24,7 +24,7 @@ the `example source`_.
    folders
    schema
    setup
-   setuptools
+   packaging
    dbcon
    dbinit
    views

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`
+following the `Python Packaging Guide`_.  Presently this involves 
-in the projects root directory.  You also need to add an empty
+creating two new files; :file:`setup.py` and :file:`MANIFEST.in` in the 
-:file:`__init__.py` file to make the :file:`flaskr/flaskr` directory
+projects root directory.  You also need to add an :file:`__init__.py` 
-a package.  The code structure at this point should be::
+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
+The above installation command assumes that it is run within the projects 
-    projects root directory, `flaskr/`.  Also, the `editable` flag allows
+root directory, `flaskr/`.  The `editable` flag allows editing 
-    editing source code without having to reinstall the Flask app each time
+source code without having to reinstall the Flask app each time you make 
-    you make changes.
+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_APP=flaskr
-    export FLASK_DEBUG=1
+    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

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`.

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

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
+:file:`test_flaskr.py` file.
-already. The context file is used as an import helper. The contents
-of that file are::
 
-    import sys, os
+Running the tests
+-----------------
 
-    basedir = os.path.dirname(os.path.abspath(__file__))
+At this point you can run the tests. Here ``pytest`` will be used. 
-    sys.path.insert(0, basedir + '/../')
 
-    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
+Run and watch the tests pass, within the top-level :file:`flaskr/` 
-requires is adding a couple of lines to the :file:`setup.py` file and
+directory as::
-creating a new file :file:`setup.cfg`. Go ahead and update the
+
-:file:`setup.py` to contain::
+    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`)::
 

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

examples/flaskr/README

@@ -19,7 +19,7 @@
 
       3. Instruct flask to use the right application
 
-         export FLASK_APP=flaskr.flaskr
+         export FLASK_APP=flaskr
 
       4. initialize the database with this command:
 

examples/flaskr/flaskr/__init__.py

@@ -0,0 +1 @@
+from flaskr import app

examples/flaskr/tests/context.py

@@ -1,6 +0,0 @@
-import sys, os
-
-basedir = os.path.dirname(os.path.abspath(__file__))
-sys.path.insert(0, basedir + '/../')
-
-from flaskr import flaskr

examples/flaskr/tests/test_flaskr.py

@@ -9,11 +9,11 @@
     :license: BSD, see LICENSE for more details.
 """
 
-import pytest
 import os
 import tempfile
+import pytest
+from flaskr import flaskr
 
-from context import flaskr
 
 @pytest.fixture
 def client(request):

examples/minitwit/.gitignore

@@ -0,0 +1,2 @@
+minitwit.db
+.eggs/

examples/minitwit/MANIFEST.in

@@ -0,0 +1,3 @@
+graft minitwit/templates
+graft minitwit/static
+include minitwit/schema.sql

examples/minitwit/README

@@ -31,5 +31,5 @@
 
     ~ Is it tested?
 
-      You betcha.  Run the `test_minitwit.py` file to
+      You betcha.  Run the `python setup.py test` file to
       see the tests pass.

examples/minitwit/minitwit/__init__.py

@@ -0,0 +1 @@
+from minitwit import app

examples/minitwit/setup.cfg

@@ -0,0 +1,2 @@
+[aliases]
+test=pytest

examples/minitwit/setup.py

@@ -0,0 +1,16 @@
+from setuptools import setup
+
+setup(
+    name='minitwit',
+    packages=['minitwit'],
+    include_package_data=True,
+    install_requires=[
+        'flask',
+    ],
+    setup_requires=[
+        'pytest-runner',
+    ],
+    tests_require=[
+        'pytest',
+    ],
+)

examples/minitwit/tests/test_minitwit.py

@@ -9,9 +9,9 @@
     :license: BSD, see LICENSE for more details.
 """
 import os
-import minitwit
 import tempfile
 import pytest
+from minitwit import minitwit
 
 
 @pytest.fixture

setup.cfg

@@ -5,4 +5,4 @@ release = egg_info -RDb ''
 universal = 1
 
 [pytest]
-norecursedirs = .* *.egg *.egg-info env* artwork docs
+norecursedirs = .* *.egg *.egg-info env* artwork docs examples