Merge pull request #3380 from stevepiercy/docs-quick-tutorial-update

Steve Piercy

2018-10-09 05915720f97df868e0b7dcff6e9b8eed964b8a90

Merge pull request #3380 from stevepiercy/docs-quick-tutorial-update

Revise Quick Tutorial `setup.py`s

 docs/quick_tutorial/authentication.rst

@@ -39,7 +39,7 @@

   .. literalinclude:: authentication/setup.py
    :language: python
    :emphasize-lines: 4
    :emphasize-lines: 6
    :linenos:

#. We can now install our project in development mode:

 docs/quick_tutorial/authentication/setup.py

@@ -1,23 +1,32 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'bcrypt',
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/authorization/setup.py

@@ -1,23 +1,32 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'bcrypt',
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/databases.rst

@@ -51,7 +51,7 @@

    .. literalinclude:: databases/setup.py
        :linenos:
        :emphasize-lines: 8-9, 11, 25-26
        :emphasize-lines: 9-10, 12, 34-36

    .. note:: We aren't yet doing ``$VENV/bin/pip install -e .`` because we need to write a script and update configuration first.


 docs/quick_tutorial/databases/setup.py

@@ -1,28 +1,38 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'deform',
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'pyramid_tm',
    'sqlalchemy',
    'waitress',
    'zope.sqlalchemy',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      [console_scripts]
      initialize_tutorial_db = tutorial.initialize_db:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
        'console_scripts': [
            'initialize_tutorial_db = tutorial.initialize_db:main'
        ],
    },
)

 docs/quick_tutorial/debugtoolbar.rst

@@ -38,18 +38,19 @@

        cd ..; cp -r ini debugtoolbar; cd debugtoolbar

#.  Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py``:
#.  Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra" for development:

    .. literalinclude:: debugtoolbar/setup.py
        :language: python
        :linenos:
        :emphasize-lines: 5
        :emphasize-lines: 10-16, 20-22

#.  Install our project and its newly added dependency.
    Note that we use the extra specifier ``[dev]`` to install development requirements and surround it and the period with double quote marks.

    .. code-block:: bash

        $VENV/bin/pip install -e .
        $VENV/bin/pip install -e ".[dev]"

#.  Our ``debugtoolbar/development.ini`` gets a configuration entry for ``pyramid.includes``:

@@ -96,14 +97,20 @@
by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes``
temporarily.

Finally we've introduced the concept of :term:`Setuptools` extras.
These are optional or recommended features that may be installed with an "extras" specifier, in this case, ``dev``.
The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line, for example, .
The value for the key is a Python list of dependencies.

.. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`.


Extra credit
============

#.  We added ``pyramid_debugtoolbar`` to the list of ``install_requires`` dependencies in ``debugtoolbar/setup.py`` because this tutorial is for development and educational purposes only.
    In what cases would you *not* want to add ``pyramid_debugtoolbar`` to your dependencies?
#.  We added ``pyramid_debugtoolbar`` to the list of ``dev_requires`` dependencies in ``debugtoolbar/setup.py``.
    We then installed the dependencies via ``pip install -e ".[dev]"`` by virtue of the Setuptools ``extras_require`` value in the Python dictionary.
    Why did we add them there instead of in the ``requires`` list?

#.  Introduce a bug into your application. Change:


 docs/quick_tutorial/debugtoolbar/setup.py

@@ -1,15 +1,28 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/forms.rst

@@ -40,7 +40,7 @@
#.  Let's edit ``forms/setup.py`` to declare a dependency on Deform, which in turn pulls in Colander as a dependency:

    .. literalinclude:: forms/setup.py
        :emphasize-lines: 4
        :emphasize-lines: 6
        :linenos:

#.  We can now install our project in development mode:

 docs/quick_tutorial/forms/setup.py

@@ -1,23 +1,32 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'deform',
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/functional_testing.rst

@@ -42,14 +42,14 @@
    .. literalinclude:: functional_testing/setup.py
        :language: python
        :linenos:
        :emphasize-lines: 14
        :emphasize-lines: 16

#.  Install our project and its newly added dependency.
    Note that we use the extra specifier ``[test]`` to install testing requirements.
    Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks.

    .. code-block:: bash

        $VENV/bin/pip install -e .[test]
        $VENV/bin/pip install -e ".[dev]"

#.  Let's extend ``functional_testing/tutorial/tests.py`` to include a functional test:


 docs/quick_tutorial/functional_testing/setup.py

@@ -1,21 +1,30 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/ini.rst

@@ -32,49 +32,48 @@
Steps
=====

#. First we copy the results of the previous step:
#.  First we copy the results of the previous step:

   .. code-block:: bash
    .. code-block:: bash

       cd ..; cp -r package ini; cd ini
        cd ..; cp -r package ini; cd ini

#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function:
#.  Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function:

   .. literalinclude:: ini/setup.py
       :linenos:
    .. literalinclude:: ini/setup.py
        :linenos:
        :emphasize-lines: 13-17

#. We can now install our project, thus generating (or re-generating) an "egg"
   at ``ini/tutorial.egg-info``:
#.  We can now install our project, thus generating (or re-generating) an "egg" at ``ini/tutorial.egg-info``:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pip install -e .
        $VENV/bin/pip install -e .

#. Let's make a file ``ini/development.ini`` for our configuration:
#.  Let's make a file ``ini/development.ini`` for our configuration:

   .. literalinclude:: ini/development.ini
       :language: ini
       :linenos:
    .. literalinclude:: ini/development.ini
        :language: ini
        :linenos:

#. We can refactor our startup code from the previous step's ``app.py`` into
   ``ini/tutorial/__init__.py``:
#.  We can refactor our startup code from the previous step's ``app.py`` into ``ini/tutorial/__init__.py``:

   .. literalinclude:: ini/tutorial/__init__.py
       :linenos:
    .. literalinclude:: ini/tutorial/__init__.py
        :linenos:

#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it:
#.  Now that ``ini/tutorial/app.py`` isn't used, let's remove it:

   .. code-block:: bash
    .. code-block:: bash

       rm tutorial/app.py
        rm tutorial/app.py

#. Run your Pyramid application with:
#.  Run your Pyramid application with:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pserve development.ini --reload
        $VENV/bin/pserve development.ini --reload

#. Open http://localhost:6543/.
#.  Open http://localhost:6543/.

Analysis
========

 docs/quick_tutorial/ini/setup.py

@@ -1,14 +1,18 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
setup(
    name='tutorial',
    install_requires=requires,
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/jinja2.rst

@@ -33,7 +33,7 @@
    .. literalinclude:: jinja2/setup.py
        :language: python
        :linenos:
        :emphasize-lines: 7
        :emphasize-lines: 8

#.  Install our project and its newly added dependency.


 docs/quick_tutorial/jinja2/setup.py

@@ -1,23 +1,32 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'pyramid_jinja2',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/json/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/logging/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/more_view_classes/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/package/setup.py

@@ -1,10 +1,13 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      )
setup(
    name='tutorial',
    install_requires=requires,
)

 docs/quick_tutorial/request_response/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/retail_forms/setup.py

@@ -1,5 +1,7 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'deform',
    'pyramid',
@@ -7,10 +9,12 @@
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
setup(
    name='tutorial',
    install_requires=requires,
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/routing/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/sessions/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/static_assets/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/templating.rst

@@ -42,67 +42,64 @@
Steps
=====

#. Let's begin by using the previous package as a starting point for a new
   project:
#.  Let's begin by using the previous package as a starting point for a new project:

   .. code-block:: bash
    .. code-block:: bash

       cd ..; cp -r views templating; cd templating
        cd ..; cp -r views templating; cd templating

#. This step depends on ``pyramid_chameleon``, so add it as a dependency in
   ``templating/setup.py``:
#.  This step depends on ``pyramid_chameleon``, so add it as a dependency in ``templating/setup.py``:

   .. literalinclude:: templating/setup.py
       :linenos:
    .. literalinclude:: templating/setup.py
        :linenos:
        :emphasize-lines: 7

#. Now we can activate the development-mode distribution:
#.  Now we can activate the development-mode distribution:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pip install -e .
        $VENV/bin/pip install -e .

#. We need to connect ``pyramid_chameleon`` as a renderer by making a call in
   the setup of ``templating/tutorial/__init__.py``:
#.  We need to connect ``pyramid_chameleon`` as a renderer by making a call in the setup of ``templating/tutorial/__init__.py``:

   .. literalinclude:: templating/tutorial/__init__.py
       :linenos:
    .. literalinclude:: templating/tutorial/__init__.py
        :linenos:

#. Our ``templating/tutorial/views.py`` no longer has HTML in it:
#.  Our ``templating/tutorial/views.py`` no longer has HTML in it:

   .. literalinclude:: templating/tutorial/views.py
       :linenos:
    .. literalinclude:: templating/tutorial/views.py
        :linenos:

#. Instead we have ``templating/tutorial/home.pt`` as a template:
#.  Instead we have ``templating/tutorial/home.pt`` as a template:

   .. literalinclude:: templating/tutorial/home.pt
       :language: html
    .. literalinclude:: templating/tutorial/home.pt
        :language: html

#. For convenience, change ``templating/development.ini`` to reload templates
   automatically with ``pyramid.reload_templates``:
#.  For convenience, change ``templating/development.ini`` to reload templates automatically with ``pyramid.reload_templates``:

   .. literalinclude:: templating/development.ini
       :language: ini
    .. literalinclude:: templating/development.ini
        :language: ini

#. Our unit tests in ``templating/tutorial/tests.py`` can focus on data:
#.  Our unit tests in ``templating/tutorial/tests.py`` can focus on data:

   .. literalinclude:: templating/tutorial/tests.py
       :linenos:
    .. literalinclude:: templating/tutorial/tests.py
        :linenos:

#. Now run the tests:
#.  Now run the tests:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pytest tutorial/tests.py -q
       ....
       4 passed in 0.46 seconds
        $VENV/bin/pytest tutorial/tests.py -q
        ....
        4 passed in 0.46 seconds

#. Run your Pyramid application with:
#.  Run your Pyramid application with:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pserve development.ini --reload
        $VENV/bin/pserve development.ini --reload

#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
#.  Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.


Analysis

 docs/quick_tutorial/templating/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/tutorial_approach.rst

@@ -36,11 +36,13 @@
project* (except as noted for the ``hello_world`` step). The ``tutorial``
directory is a *Python package*.

For most steps you will copy the previous step's directory to a new directory, and change your working directory to the new directory, then install your project:
For most steps you will copy an earlier step's directory to a new directory, change your working directory to the new directory, then install your project:

.. code-block:: bash

    cd ..; cp -r package ini; cd ini
    $VENV/bin/pip install -e .

For a few steps, you won't copy the previous step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``.
For a few steps, you won't copy an earlier step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``.

Finally for a few steps, you might add a dependency to your project in its ``setup.py`` file, and then install both the dependency and the project with either ``$VENV/bin/pip install -e .`` or ``$VENV/bin/pip install -e ".[dev]"``.

 docs/quick_tutorial/unit_testing.rst

@@ -54,14 +54,14 @@
    .. literalinclude:: unit_testing/setup.py
        :language: python
        :linenos:
        :emphasize-lines: 11-15
        :emphasize-lines: 15

#.  Install our project and its newly added dependency.
    Note that we use the extra specifier ``[test]`` to install testing requirements.
    Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks.

    .. code-block:: bash

        $VENV/bin/pip install -e .[test]
        $VENV/bin/pip install -e ".[dev]"

#.  Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:

@@ -101,11 +101,6 @@
``pyramid.testing.tearDown()`` aren't actually necessary here; they are only
necessary when your test needs to make use of the ``config`` object (it's a
Configurator) to add stuff to the configuration state before calling the view.

Finally we've introduced the concept of :term:`Setuptools` extras.
These are optional or recommended features that may be installed with an "extras" specifier.
The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line.
The value for the key is a Python list of dependencies.


Extra credit

 docs/quick_tutorial/unit_testing/setup.py

@@ -1,20 +1,29 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/view_classes.rst

@@ -37,41 +37,38 @@
Steps
=====

#. First we copy the results of the previous step:
#.  First we copy the results of the previous step:

   .. code-block:: bash
    .. code-block:: bash

       cd ..; cp -r templating view_classes; cd view_classes
       $VENV/bin/pip install -e .
        cd ..; cp -r templating view_classes; cd view_classes
        $VENV/bin/pip install -e .

#. Our ``view_classes/tutorial/views.py`` now has a view class with our two
   views:
#.  Our ``view_classes/tutorial/views.py`` now has a view class with our two views:

   .. literalinclude:: view_classes/tutorial/views.py
       :linenos:
    .. literalinclude:: view_classes/tutorial/views.py
        :linenos:

#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's
   modify them to import the view class, and make an instance before getting a
   response:
#.  Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's modify them to import the view class, and make an instance before getting a response:

   .. literalinclude:: view_classes/tutorial/tests.py
       :linenos:
    .. literalinclude:: view_classes/tutorial/tests.py
        :linenos:

#. Now run the tests:
#.  Now run the tests:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pytest tutorial/tests.py -q
       ....
       4 passed in 0.34 seconds
        $VENV/bin/pytest tutorial/tests.py -q
        ....
        4 passed in 0.34 seconds

#. Run your Pyramid application with:
#.  Run your Pyramid application with:

   .. code-block:: bash
    .. code-block:: bash

       $VENV/bin/pserve development.ini --reload
        $VENV/bin/pserve development.ini --reload

#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
#.  Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.


Analysis

 docs/quick_tutorial/view_classes/setup.py

@@ -1,22 +1,31 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_chameleon',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)

 docs/quick_tutorial/views/setup.py

@@ -1,21 +1,30 @@
from setuptools import setup

# List of dependencies installed via `pip install -e .`
# by virtue of the Setuptools `install_requires` value below.
requires = [
    'pyramid',
    'pyramid_debugtoolbar',
    'waitress',
]

setup(name='tutorial',
      install_requires=requires,
      extras_require={
          'test': [
              'pytest',
              'webtest',
          ],
      },
      entry_points="""\
      [paste.app_factory]
      main = tutorial:main
      """,
      )
# List of dependencies installed via `pip install -e ".[dev]"`
# by virtue of the Setuptools `extras_require` value in the Python
# dictionary below.
dev_requires = [
    'pyramid_debugtoolbar',
    'pytest',
    'webtest',
]

setup(
    name='tutorial',
    install_requires=requires,
    extras_require={
        'dev': dev_requires,
    },
    entry_points={
        'paste.app_factory': [
            'main = tutorial:main'
        ],
    },
)