Merge pull request #3390 from mmerickel/whatsnew-1.10

Michael Merickel

2018-10-16 8eed333343e4e9e7f11f3aee67299030d6bf2783

 docs/quick_tour.rst

@@ -19,14 +19,14 @@
is a breeze. Unfortunately "standard" is not so simple in Python. For this
Quick Tour, it means `Python <https://www.python.org/downloads/>`_, :mod:`python:venv` (or `virtualenv for
Python 2.7 <https://virtualenv.pypa.io/en/stable/>`_),
`pip <https://pypi.org/project/pip/>`_, and `setuptools
`pip <https://pypi.org/project/pip/>`_, and `Setuptools
<https://pypi.org/project/setuptools/>`_.

To save a little bit of typing and to be certain that we use the modules,
scripts, and packages installed in our virtual environment, we'll set an
environment variable, too.

As an example, for Python 3.6+ on Linux:
As an example, for Python 3 on Linux:

.. parsed-literal::

@@ -498,7 +498,7 @@
packages, no structure. Most Pyramid projects, though, aren't developed this
way.

To ease the process of getting started, the Pylons Project provides :term:`cookiecutter`\ s that generate sample Pyramid projects from project templates. These cookiecutters will install Pyramid and its dependencies as well.
To ease the process of getting started, the Pylons Project provides a :term:`cookiecutter` that generates sample Pyramid projects from project templates. This cookiecutter will install Pyramid and its dependencies as well.

First you'll need to install cookiecutter.

@@ -510,7 +510,7 @@

.. code-block:: bash

    $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master
    $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch

If prompted for the first item, accept the default ``yes`` by hitting return.

@@ -524,6 +524,11 @@
    1 - jinja2
    2 - chameleon
    3 - mako
    Choose from 1, 2, 3 [1]: 1
    Select backend:
    1 - none
    2 - sqlalchemy
    3 - zodb
    Choose from 1, 2, 3 [1]: 1

We then run through the following commands.
@@ -641,7 +646,7 @@
available in your browser. Adding it to your project illustrates several points
about configuration.

The cookiecutter ``pyramid-cookiecutter-starter`` already configured our package to include the
Our cookiecutter ``pyramid-cookiecutter-starter`` already configured our package to include the
add-on ``pyramid_debugtoolbar`` in its ``setup.py``:

.. literalinclude:: quick_tour/package/setup.py
@@ -675,8 +680,8 @@
    :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and
    :ref:`pyramid_debugtoolbar <toolbar:overview>`

Unit tests and ``py.test``
==========================
Unit tests and ``pytest``
=========================

Yikes! We got this far and we haven't yet discussed tests. This is particularly
egregious, as Pyramid has had a deep commitment to full test coverage since
@@ -684,7 +689,7 @@

Our ``pyramid-cookiecutter-starter`` cookiecutter generated a ``tests.py`` module with
one unit test and one functional test in it. It also configured ``setup.py`` with test requirements:
``py.test`` as the test runner, ``WebTest`` for running view tests, and the
``pytest`` as the test runner, ``WebTest`` for running view tests, and the
``pytest-cov`` tool which yells at us for code that isn't tested:

.. literalinclude:: quick_tour/package/setup.py
@@ -701,7 +706,7 @@

.. code-block:: bash

    $VENV/bin/py.test --cov --cov-report=term-missing
    $VENV/bin/pytest --cov --cov-report=term-missing

This yields the following output.

@@ -755,14 +760,14 @@
Maybe you would like to log messages in your code? In your Python module,
import and set up the logging in your ``views.py``:

.. literalinclude:: quick_tour/logging/hello_world/views.py
.. literalinclude:: quick_tour/logging/hello_world/views/default.py
    :language: python
    :lineno-match:
    :lines: 3-4

You can now, in your code, log messages:

.. literalinclude:: quick_tour/logging/hello_world/views.py
.. literalinclude:: quick_tour/logging/hello_world/views/default.py
    :language: python
    :lineno-match:
    :lines: 7-8
@@ -819,13 +824,13 @@
.. literalinclude:: quick_tour/sessions/hello_world/__init__.py
    :language: python
    :lineno-match:
    :lines: 10-13
    :lines: 9-12
    :emphasize-lines: 2-3

Pyramid's :term:`request` object now has a ``session`` attribute that we can
use in our view code in ``views.py``:

.. literalinclude:: quick_tour/sessions/hello_world/views.py
.. literalinclude:: quick_tour/sessions/hello_world/views/default.py
    :language: python
    :lineno-match:
    :lines: 7-
@@ -858,16 +863,26 @@
.. code-block:: bash

    cd ~
    env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout master
    env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch

If prompted for the first item, accept the default ``yes`` by hitting return.

.. code-block:: text

    You've cloned ~/.cookiecutters/pyramid-cookiecutter-alchemy before.
    You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before.
    Is it okay to delete and re-clone it? [yes]: yes
    project_name [Pyramid Scaffold]: sqla_demo
    repo_name [sqla_demo]: sqla_demo
    Select template_language:
    1 - jinja2
    2 - chameleon
    3 - mako
    Choose from 1, 2, 3 [1]: 1
    Select backend:
    1 - none
    2 - sqlalchemy
    3 - zodb
    Choose from 1, 2, 3 [1]: 2

We then run through the following commands as before.