diff options
Diffstat (limited to 'docs/tutorials')
| -rw-r--r-- | docs/tutorials/modwsgi/index.rst | 13 | ||||
| -rw-r--r-- | docs/tutorials/wiki/basiclayout.rst | 9 | ||||
| -rw-r--r-- | docs/tutorials/wiki/definingviews.rst | 4 | ||||
| -rw-r--r-- | docs/tutorials/wiki/installation.rst | 64 | ||||
| -rw-r--r-- | docs/tutorials/wiki/tests.rst | 19 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/basiclayout.rst | 7 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/definingviews.rst | 10 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/installation.rst | 59 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/tests.rst | 16 |
9 files changed, 111 insertions, 90 deletions
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index bcedcbe3d..fa0d4f0cb 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -32,9 +32,9 @@ specific path information for commands and files. <https://code.google.com/archive/p/modwsgi/wikis/InstallationInstructions.wiki>`_ for your platform into your system's Apache installation. -#. Create a :app:`Pyramid` application. For this tutorial we'll use the - ``starter`` :term:`cookiecutter`. See :ref:`project_narr` for more - in-depth information about creating a new project. +#. Create a :app:`Pyramid` application using our :term:`cookiecutter`. See + :ref:`project_narr` for more in-depth information about creating a new + project. .. code-block:: bash @@ -54,6 +54,11 @@ specific path information for commands and files. 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 #. Create a :term:`virtual environment` which we'll use to install our application. It is important to use the same base Python interpreter @@ -119,7 +124,7 @@ specific path information for commands and files. WSGIProcessGroup pyramid Require all granted </Directory> - + #. Restart Apache .. code-block:: bash diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index a0b365a23..49ee6902e 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -4,9 +4,10 @@ Basic Layout ============ -The starter files generated by the ``zodb`` cookiecutter are very basic, but -they provide a good orientation for the high-level patterns common to most -:term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` projects. +The starter files generated by selecting the ``zodb`` backend in the +cookiecutter are very basic, but they provide a good orientation for the +high-level patterns common to most :term:`traversal`-based (and +:term:`ZODB`-based) :app:`Pyramid` projects. Application configuration with ``__init__.py`` @@ -20,7 +21,7 @@ code. When you run the application using the ``pserve`` command using the ``development.ini`` generated configuration file, the application -configuration points at a setuptools *entry point* described as +configuration points at a :term:`Setuptools` :term:`entry point` described as ``egg:tutorial``. In our application, because the application's ``setup.py`` file says so, this entry point happens to be the ``main`` function within the file named ``__init__.py``. diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index e4183b8f2..d584a1b41 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -99,8 +99,8 @@ like the following: We added some imports and created a regular expression to find "WikiWords". We got rid of the ``my_view`` view function and its decorator that was added -when we originally rendered the ``zodb`` cookiecutter. It was only an example and -isn't relevant to our application. +when originally rendered after we selected the ``zodb`` backend option in the +cookiecutter. It was only an example and isn't relevant to our application. Then we added four :term:`view callable` functions to our ``views.py`` module: diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 7f914267f..d0037e584 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -31,7 +31,7 @@ On Unix .. code-block:: bash cd ~ - cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master On Windows ^^^^^^^^^^ @@ -39,7 +39,7 @@ On Windows .. code-block:: doscon cd \ - cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master On all operating systems ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -47,10 +47,20 @@ If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-zodb before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theone before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: myproj repo_name [myproj]: tutorial + 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]: 3 Change directory into your newly created project ------------------------------------------------ @@ -195,22 +205,22 @@ Run the tests After you've installed the project in development mode as well as the testing requirements, you may run the tests for the project. The following commands -provide options to py.test that specify the module for which its tests shall be -run, and to run py.test in quiet mode. +provide options to ``pytest`` that specify the module for which its tests shall be +run, and to run ``pytest`` in quiet mode. On Unix ^^^^^^^ .. code-block:: bash - $VENV/bin/py.test -q + $VENV/bin/pytest -q On Windows ^^^^^^^^^^ .. code-block:: doscon - %VENV%\Scripts\py.test -q + %VENV%\Scripts\pytest -q For a successful test run, you should see output that ends like this: @@ -223,8 +233,8 @@ For a successful test run, you should see output that ends like this: Expose test coverage information -------------------------------- -You can run the ``py.test`` command to see test coverage information. This -runs the tests in the same way that ``py.test`` does, but provides additional +You can run the ``pytest`` command to see test coverage information. This +runs the tests in the same way that ``pytest`` does, but provides additional :term:`coverage` information, exposing which lines of your project are covered by the tests. @@ -236,14 +246,14 @@ On Unix .. code-block:: bash - $VENV/bin/py.test --cov --cov-report=term-missing + $VENV/bin/pytest --cov --cov-report=term-missing On Windows ^^^^^^^^^^ .. code-block:: doscon - %VENV%\Scripts\py.test --cov --cov-report=term-missing + %VENV%\Scripts\pytest --cov --cov-report=term-missing If successful, you will see output something like this: @@ -275,32 +285,33 @@ Our package doesn't quite have 100% test coverage. Test and coverage cookiecutter defaults --------------------------------------- -Cookiecutters include configuration defaults for ``py.test`` and test coverage. -These configuration files are ``pytest.ini`` and ``.coveragerc``, located at -the root of your package. Without these defaults, we would need to specify the -path to the module on which we want to run tests and coverage. +The Pyramid cookiecutter includes configuration defaults for ``pytest`` and +test coverage. These configuration files are ``pytest.ini`` and +``.coveragerc``, located at the root of your package. Without these defaults, +we would need to specify the path to the module on which we want to run tests +and coverage. On Unix ^^^^^^^ .. code-block:: bash - $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q + $VENV/bin/pytest --cov=tutorial tutorial/tests.py -q On Windows ^^^^^^^^^^ .. code-block:: doscon - %VENV%\Scripts\py.test --cov=tutorial tutorial\tests.py -q + %VENV%\Scripts\pytest --cov=tutorial tutorial\tests.py -q -py.test follows :ref:`conventions for Python test discovery +``pytest`` follows :ref:`conventions for Python test discovery <pytest:test discovery>`, and the configuration defaults from the cookiecutter -tell ``py.test`` where to find the module on which we want to run tests and +tell ``pytest`` where to find the module on which we want to run tests and coverage. -.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke - ``py.test -h`` to see its full set of options. +.. seealso:: See ``pytest``'s documentation for :ref:`pytest:usage` or invoke + ``pytest -h`` to see its full set of options. .. _wiki-start-the-application: @@ -354,11 +365,10 @@ page. You can read more about the purpose of the icon at application while you develop. -Decisions the ``zodb`` cookiecutter has made for you ----------------------------------------------------- +Decisions the cookiecutter backend option ``zodb`` has made for you +------------------------------------------------------------------- -Creating a project using the ``zodb`` cookiecutter makes the following -assumptions: +When creating a project and selecting the backend option of ``zodb``, the cookiecutter makes the following assumptions: - You are willing to use :term:`ZODB` for persistent storage. @@ -367,10 +377,6 @@ assumptions: - You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages to manage connections and transactions with :term:`ZODB`. -- You want to use pyramid_chameleon_ to render your templates. Different - templating engines can be used, but we had to choose one to make this - tutorial. See :ref:`available_template_system_bindings` for some options. - .. note:: :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index c3a1ca79a..fdd218add 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -16,16 +16,17 @@ We write tests for the ``model`` classes and the ``appmaker``. Changing we'll write a test class for the ``appmaker``. To do so, we'll retain the ``tutorial.tests.ViewTests`` class that was -generated as part of the ``zodb`` cookiecutter. We'll add three test classes: one -for the ``Page`` model named ``PageModelTests``, one for the ``Wiki`` model -named ``WikiModelTests``, and one for the appmaker named ``AppmakerTests``. +generated from choosing the ``zodb`` backend option. We'll add three test +classes: one for the ``Page`` model named ``PageModelTests``, one for the +``Wiki`` model named ``WikiModelTests``, and one for the appmaker named +``AppmakerTests``. Test the views ============== We'll modify our ``tests.py`` file, adding tests for each view function we -added previously. As a result, we'll delete the ``ViewTests`` class that -the ``zodb`` cookiecutter provided, and add four other test classes: +added previously. As a result, we'll delete the ``ViewTests`` class that the +``zodb`` backend option provided, and add four other test classes: ``ViewWikiTests``, ``ViewPageTests``, ``AddPageTests``, and ``EditPageTests``. These test the ``view_wiki``, ``view_page``, ``add_page``, and ``edit_page`` views. @@ -51,22 +52,22 @@ follows: Running the tests ================= -We can run these tests by using ``py.test`` similarly to how we did in +We can run these tests by using ``pytest`` similarly to how we did in :ref:`running_tests`. Courtesy of the cookiecutter, our testing dependencies have -already been satisfied and ``py.test`` and coverage have already been +already been satisfied and ``pytest`` and coverage have already been configured, so we can jump right to running tests. On Unix: .. code-block:: bash - $VENV/bin/py.test -q + $VENV/bin/pytest -q On Windows: .. code-block:: doscon - %VENV%\Scripts\py.test -q + %VENV%\Scripts\pytest -q The expected result should look like the following: diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 315aca29e..f3a9db223 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -4,9 +4,10 @@ Basic Layout ============ -The starter files generated by the ``alchemy`` cookiecutter are very basic, but -they provide a good orientation for the high-level patterns common to most -:term:`URL dispatch`-based :app:`Pyramid` projects. +The starter files generated from choosing the ``sqlalchemy`` backend option in +the cookiecutter are very basic, but they provide a good orientation for the +high-level patterns common to most :term:`URL dispatch`-based :app:`Pyramid` +projects. Application configuration with ``__init__.py`` diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index fe539eca6..d10d862f5 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -133,9 +133,9 @@ The highlighted lines need to be added or edited. We added some imports, and created a regular expression to find "WikiWords". We got rid of the ``my_view`` view function and its decorator that was added -when we originally rendered the ``alchemy`` cookiecutter. It was only an example -and isn't relevant to our application. We also deleted the ``db_err_msg`` -string. +when originally rendered after we selected the ``sqlalchemy`` backend option in +the cookiecutter. It was only an example and isn't relevant to our +application. We also deleted the ``db_err_msg`` string. Then we added four :term:`view callable` functions to our ``views/default.py`` module, as mentioned in the previous step: @@ -436,8 +436,8 @@ There are several important things to note about this configuration: the view. Finally, we may delete the ``tutorial/templates/mytemplate.jinja2`` template -that was provided by the ``alchemy`` cookiecutter, as we have created our own -templates for the wiki. +that was provided by selecting the backend option of ``sqlalchemy``, as we +have created our own templates for the wiki. .. note:: diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 5f2c6d44e..924927cd4 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -43,7 +43,7 @@ On Unix .. code-block:: bash cd ~ - cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master On Windows ^^^^^^^^^^ @@ -51,7 +51,7 @@ On Windows .. code-block:: doscon cd \ - cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master On all operating systems ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -59,10 +59,21 @@ 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]: myproj repo_name [myproj]: tutorial + 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 + Change directory into your newly created project ------------------------------------------------ @@ -342,22 +353,22 @@ Run the tests After you've installed the project in development mode as well as the testing requirements, you may run the tests for the project. The following commands -provide options to py.test that specify the module for which its tests shall be -run, and to run py.test in quiet mode. +provide options to ``pytest`` that specify the module for which its tests shall be +run, and to run ``pytest`` in quiet mode. On Unix ^^^^^^^ .. code-block:: bash - $VENV/bin/py.test -q + $VENV/bin/pytest -q On Windows ^^^^^^^^^^ .. code-block:: doscon - %VENV%\Scripts\py.test -q + %VENV%\Scripts\pytest -q For a successful test run, you should see output that ends like this: @@ -370,8 +381,8 @@ For a successful test run, you should see output that ends like this: Expose test coverage information -------------------------------- -You can run the ``py.test`` command to see test coverage information. This -runs the tests in the same way that ``py.test`` does, but provides additional +You can run the ``pytest`` command to see test coverage information. This +runs the tests in the same way that ``pytest`` does, but provides additional :term:`coverage` information, exposing which lines of your project are covered by the tests. @@ -383,14 +394,14 @@ On Unix .. code-block:: bash - $VENV/bin/py.test --cov --cov-report=term-missing + $VENV/bin/pytest --cov --cov-report=term-missing On Windows ^^^^^^^^^^ .. code-block:: doscon - c:\tutorial> %VENV%\Scripts\py.test --cov --cov-report=term-missing + c:\tutorial> %VENV%\Scripts\pytest --cov --cov-report=term-missing If successful, you will see output something like this: @@ -429,7 +440,7 @@ Our package doesn't quite have 100% test coverage. Test and coverage cookiecutter defaults --------------------------------------- -Cookiecutters include configuration defaults for ``py.test`` and test coverage. +Cookiecutters include configuration defaults for ``pytest`` and test coverage. These configuration files are ``pytest.ini`` and ``.coveragerc``, located at the root of your package. Without these defaults, we would need to specify the path to the module on which we want to run tests and coverage. @@ -439,22 +450,22 @@ On Unix .. code-block:: bash - $VENV/bin/py.test --cov=tutorial tutorial/tests.py -q + $VENV/bin/pytest --cov=tutorial tutorial/tests.py -q On Windows ^^^^^^^^^^ .. code-block:: doscon - %VENV%\Scripts\py.test --cov=tutorial tutorial\tests.py -q + %VENV%\Scripts\pytest --cov=tutorial tutorial\tests.py -q -py.test follows :ref:`conventions for Python test discovery +pytest follows :ref:`conventions for Python test discovery <pytest:test discovery>`, and the configuration defaults from the cookiecutter -tell ``py.test`` where to find the module on which we want to run tests and +tell ``pytest`` where to find the module on which we want to run tests and coverage. -.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke - ``py.test -h`` to see its full set of options. +.. seealso:: See ``pytest``'s documentation for :ref:`pytest:usage` or invoke + ``pytest -h`` to see its full set of options. .. _wiki2-start-the-application: @@ -508,11 +519,11 @@ page. You can read more about the purpose of the icon at application while you develop. -Decisions the ``alchemy`` cookiecutter has made for you -------------------------------------------------------- +Decisions the cookiecutter backend option ``sqlalchemy`` has made for you +------------------------------------------------------------------------- -Creating a project using the ``alchemy`` cookiecutter makes the following -assumptions: +When creating a project and selecting the backend option of ``sqlalchemy``, the +cookiecutter makes the following assumptions: - You are willing to use SQLite for persistent storage, although almost any SQL database could be used with SQLAlchemy. @@ -527,10 +538,6 @@ assumptions: - You want to use zope.sqlalchemy_, pyramid_tm_, and the transaction_ packages to scope sessions to requests. -- You want to use pyramid_jinja2_ to render your templates. Different - templating engines can be used, but we had to choose one to make this - tutorial. See :ref:`available_template_system_bindings` for some options. - .. note:: :app:`Pyramid` supports any persistent storage mechanism (e.g., object diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index f3f89fe9c..941a50928 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -8,12 +8,12 @@ We will now add tests for the models and views as well as a few functional tests in a new ``tests`` subpackage. Tests ensure that an application works, and that it continues to work when changes are made in the future. -The file ``tests.py`` was generated as part of the ``alchemy`` cookiecutter, but it -is a common practice to put tests into a ``tests`` subpackage, especially as -projects grow in size and complexity. Each module in the test subpackage -should contain tests for its corresponding module in our application. Each -corresponding pair of modules should have the same names, except the test -module should have the prefix ``test_``. +The file ``tests.py`` was generated from choosing the ``sqlalchemy`` backend +option, but it is a common practice to put tests into a ``tests`` +subpackage, especially as projects grow in size and complexity. Each module in +the test subpackage should contain tests for its corresponding module in our +application. Each corresponding pair of modules should have the same names, +except the test module should have the prefix ``test_``. Start by deleting ``tests.py``, then create a new directory to contain our new tests as well as a new empty file ``tests/__init__.py``. @@ -99,14 +99,14 @@ On Unix: .. code-block:: bash rm tutorial.sqlite - $VENV/bin/py.test -q + $VENV/bin/pytest -q On Windows: .. code-block:: doscon del tutorial.sqlite - %VENV%\Scripts\py.test -q + %VENV%\Scripts\pytest -q The expected result should look like the following: |