diff options
| -rw-r--r-- | docs/glossary.rst | 12 | ||||
| -rw-r--r-- | docs/narr/advanced-features.rst | 4 | ||||
| -rw-r--r-- | docs/narr/assets.rst | 4 | ||||
| -rw-r--r-- | docs/narr/commandline.rst | 4 | ||||
| -rw-r--r-- | docs/narr/cookiecutters.rst | 18 | ||||
| -rw-r--r-- | docs/narr/extending.rst | 2 | ||||
| -rw-r--r-- | docs/narr/install.rst | 3 | ||||
| -rw-r--r-- | docs/narr/introduction.rst | 2 | ||||
| -rw-r--r-- | docs/narr/logging.rst | 21 | ||||
| -rw-r--r-- | docs/narr/paste.rst | 4 | ||||
| -rw-r--r-- | docs/narr/project.rst | 61 | ||||
| -rw-r--r-- | docs/narr/webob.rst | 2 | ||||
| -rw-r--r-- | docs/quick_tour.rst | 23 | ||||
| -rw-r--r-- | docs/quick_tutorial/cookiecutters.rst | 9 | ||||
| -rw-r--r-- | docs/quick_tutorial/databases.rst | 8 | ||||
| -rw-r--r-- | docs/tutorials/modwsgi/index.rst | 13 | ||||
| -rw-r--r-- | docs/tutorials/wiki/basiclayout.rst | 7 | ||||
| -rw-r--r-- | docs/tutorials/wiki/definingviews.rst | 4 | ||||
| -rw-r--r-- | docs/tutorials/wiki/installation.rst | 36 | ||||
| -rw-r--r-- | docs/tutorials/wiki/tests.rst | 11 | ||||
| -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 | 29 | ||||
| -rw-r--r-- | docs/tutorials/wiki2/tests.rst | 12 |
24 files changed, 181 insertions, 125 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index ec4cffef2..8f94eeaca 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1155,13 +1155,15 @@ Glossary cookiecutter A command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates), e.g., creating a Python package project from a Python package project template. - Pyramid cookiecutters include: + .. versionadded:: 1.8 + Added cookiecutter support. - * `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_ - * `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_ - * `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_ + .. versionchanged:: 1.10 + Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. - .. versionadded:: 1.8 + .. deprecated:: 1.10 + ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. + Use ``pyramid-cookiecutter-starter`` going forward. .. seealso:: See also :term:`scaffold`. diff --git a/docs/narr/advanced-features.rst b/docs/narr/advanced-features.rst index 191996c27..b169aad95 100644 --- a/docs/narr/advanced-features.rst +++ b/docs/narr/advanced-features.rst @@ -51,7 +51,7 @@ This approach allows you to develop view code that is simpler, more easily under Stop Worrying About Transactions -------------------------------- -:app:`Pyramid`\ 's :term:`cookiecutter`\ s render projects that include a *transaction management* system. When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception. +:app:`Pyramid`\ 's :term:`cookiecutter` renders projects that include a *transaction management* system. When you use this system, you can stop worrying about when to commit your changes, :app:`Pyramid` handles it for you. The system will commit at the end of a request or abort if there was an exception. Why is that a good thing? Imagine a situation where you manually commit a change to your persistence layer. It's very likely that other framework code will run *after* your changes are done. If an error happens in that other code, you can easily wind up with inconsistent data if you're not extremely careful. @@ -327,4 +327,4 @@ Here's an example of using :app:`Pyramid`\ 's :term:`introspector` from within a .. seealso:: - See also :ref:`using_introspection`.
\ No newline at end of file + See also :ref:`using_introspection`. diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 2b0b90b4a..06594dbb7 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -27,8 +27,8 @@ asset: package. The use of assets is quite common in most web development projects. For -example, when you create a :app:`Pyramid` application using one of the -available :term:`cookiecutter`\ s, as described in :ref:`creating_a_project`, the directory +example, when you create a :app:`Pyramid` application using the +:term:`cookiecutter`, as described in :ref:`creating_a_project`, the directory representing the application contains a Python :term:`package`. Within that Python package, there are directories full of files which are static assets. For example, there's a ``static`` directory which contains ``.css``, ``.js``, diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 98e34fea2..f8ca8366b 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -298,8 +298,8 @@ By defining the ``setup`` callable, we will create the module ``myapp.lib.pshell # start a transaction which can be used in the shell request.tm.begin() - # if using the alchemy cookiecutter, the dbsession is connected - # to the transaction manager above + # if using the SQLAlchemy backend from our cookiecutter, the dbsession is + # connected to the transaction manager above env['tm'] = request.tm env['dbsession'] = request.dbsession try: diff --git a/docs/narr/cookiecutters.rst b/docs/narr/cookiecutters.rst index abedb25b9..9883713cb 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -2,16 +2,24 @@ Pyramid cookiecutters ===================== +A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates). + +The Pyramid cookiecutter replaced the deprecated Pyramid scaffolds, and should be used going forward. + +`pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_ .. versionadded:: 1.8 + Added cookiecutter support. -A :term:`cookiecutter` is a command-line utility that creates projects from :ref:`cookiecutters <cookiecutter:readme>` (project templates), e.g., creating a Python package project from a Python package project template. +.. deprecated:: 1.8 + Scaffolds may be removed in a future version of Pyramid. -Pyramid cookiecutters have replaced the now deprecated Pyramid scaffolds, and should be used going forward. Pyramid cookiecutters released under the Pylons Project include: +.. versionchanged:: 1.10 + Merged features from ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` into the single cookiecutter to rule them all, ``pyramid-cookiecutter-starter``. -* `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_ -* `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_ -* `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_ +.. deprecated:: 1.10 + ``pyramid-cookiecutter-alchemy`` and ``pyramid-cookiecutter-zodb`` are no longer supported. + Use ``pyramid-cookiecutter-starter`` going forward. .. seealso:: diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 1a6804792..ccf871ca8 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -190,7 +190,7 @@ The general pattern for extending an existing application looks something like this: - Create a new Python package. The easiest way to do this is to create a new - :app:`Pyramid` application using a :term:`cookiecutter`. See + :app:`Pyramid` application using our :term:`cookiecutter`. See :ref:`creating_a_project` for more information. - In the new package, create Python files containing views and other overridden diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 743cb4abb..dbf5dc2eb 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -262,5 +262,4 @@ What Gets Installed When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy, and others are installed. -Additionally, as chronicled in :ref:`project_narr`, :term:`cookiecutter`\ s will be -used, which make it easy to start a new :app:`Pyramid` project. +Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 9293386f2..dada4e8bd 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -144,7 +144,7 @@ Develop interactively When your application has an error, an interactive debugger allows you to poke around from your browser to find out what happened. -To use the :app:`Pyramid` debug toolbar, build your project with a :app:`Pyramid` :term:`cookiecutter`. +To use the :app:`Pyramid` debug toolbar, build your project with our :term:`cookiecutter`. .. seealso:: diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index ce83cd3ee..7b60beda9 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -9,10 +9,10 @@ to send log messages to loggers that you've configured. .. warning:: - This chapter assumes you've used a :term:`cookiecutter` to create a project + This chapter assumes you've used our :term:`cookiecutter` to create a project which contains ``development.ini`` and ``production.ini`` files which help - configure logging. All of the Pyramid cookiecutters provided by the Pylons Project do - this. If you're not using a cookiecutter, or if you've used a third-party + configure logging. The Pyramid cookiecutter provided by the Pylons Project does + this. If you're not using our cookiecutter, or if you've used a third-party cookiecutter which does not create these files, the configuration information in this chapter may not be applicable. @@ -26,11 +26,11 @@ to send log messages to loggers that you've configured. Logging Configuration --------------------- -A :app:`Pyramid` project created from a :term:`cookiecutter` is configured to allow +A :app:`Pyramid` project created from our :term:`cookiecutter` is configured to allow you to send messages to :mod:`Python standard library logging package <logging>` loggers from within your application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created -when you use a cookiecutter include a basic configuration for the Python +when you use our cookiecutter include a basic configuration for the Python :mod:`logging` package. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser @@ -47,7 +47,7 @@ cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. Default logging configuration is provided in both the default -``development.ini`` and the ``production.ini`` files. If you use ``pyramid-cookiecutter-starter`` to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration +``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration in the ``development.ini`` file is as follows: .. literalinclude:: myproject/development.ini @@ -75,7 +75,7 @@ that ask for a logger (via ``logging.getLogger``) that has a name which begins with anything except your project's package name (e.g., ``myproject``). The logger with the same name as your package name is reserved for your own usage in your :app:`Pyramid` application. Its existence means that you can log to a known -logging location from any :app:`Pyramid` application generated via a cookiecutter. +logging location from any :app:`Pyramid` application generated via our cookiecutter. :app:`Pyramid` and many other libraries (such as Beaker, SQLAlchemy, Paste) log a number of messages to the root logger for debugging purposes. Switching the @@ -88,9 +88,10 @@ root logger level to ``DEBUG`` reveals them: level = DEBUG handlers = console -Some cookiecutters configure additional loggers for additional subsystems they use -(such as SQLALchemy). Take a look at the ``production.ini`` and -``development.ini`` files rendered when you create a project from a cookiecutter. +Some configurations of the :app:`Pyramid` cookiecutter configure additional loggers for +additional subsystems they use (such as SQLAlchemy). Take a look at the +``production.ini`` and ``development.ini`` files rendered when you create a +project from our cookiecutter. Sending Logging Messages ------------------------ diff --git a/docs/narr/paste.rst b/docs/narr/paste.rst index c02036f69..8a0d505b3 100644 --- a/docs/narr/paste.rst +++ b/docs/narr/paste.rst @@ -14,7 +14,7 @@ runner ``pserve``, as well as other commands such as ``pviews``, ``pshell``, PasteDeploy is not a particularly integral part of Pyramid. It's possible to create a Pyramid application which does not use PasteDeploy at all. We show a Pyramid application that doesn't use PasteDeploy in :ref:`firstapp_chapter`. -However, all Pyramid cookiecutters render PasteDeploy configuration files, to +However, the Pyramid cookiecutter renders PasteDeploy configuration files, to provide new developers with a standardized way of setting deployment values, and to provide new users with a standardized way of starting, stopping, and debugging an application. @@ -75,7 +75,7 @@ In English, this entry point can thus be referred to as a "PasteDeploy application factory in the ``myproject`` project which has the entry point named ``main`` where the entry point refers to a ``main`` function in the ``mypackage`` module". Indeed, if you open up the ``__init__.py`` module -generated within any cookiecutter-generated package, you'll see a ``main`` +generated within the cookiecutter-generated package, you'll see a ``main`` function. This is the function called by :term:`PasteDeploy` when the ``pserve`` command is invoked against our application. It accepts a global configuration object and *returns* an instance of our application. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 5efc07e09..84fd8e31f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -5,21 +5,21 @@ Creating a :app:`Pyramid` Project As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid` application completely manually. However, it's usually more convenient to use -a :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`. +our :term:`cookiecutter` to generate a basic :app:`Pyramid` :term:`project`. A project is a directory that contains at least one Python :term:`package`. -You'll use a cookiecutter to create a project, and you'll create your application -logic within a package that lives inside the project. Even if your application -is extremely simple, it is useful to place code that drives the application -within a package, because (1) a package is more easily extended with new code, -and (2) an application that lives inside a package can also be distributed more -easily than one which does not live within a package. +You'll use the :app:`Pyramid` cookiecutter to create a project, and you'll +create your application logic within a package that lives inside the project. +Even if your application is extremely simple, it is useful to place code that +drives the application within a package, because (1) a package is more easily +extended with new code, and (2) an application that lives inside a package can +also be distributed more easily than one which does not live within a package. -The Pylons Project provides several :app:`Pyramid` cookiecutters that you can use to generate a -project. Each cookiecutter makes different configuration assumptions about what -type of application you're trying to construct. +The Pylons Project provides a :app:`Pyramid` cookiecutter that you can use to +generate a project. Our cookiecutter allows several configuration options +to generate the type of application you're trying to construct. -These cookiecutters are rendered using the ``cookiecutter`` command that you may install. +This cookiecutter is rendered using the ``cookiecutter`` command that you may install. .. seealso:: @@ -29,36 +29,34 @@ These cookiecutters are rendered using the ``cookiecutter`` command that you may .. index:: single: cookiecutters single: pyramid-cookiecutter-starter - single: pyramid-cookiecutter-zodb - single: pyramid-cookiecutter-alchemy .. _additional_cookiecutters: :app:`Pyramid` cookiecutters ---------------------------- -Pyramid cookiecutters released under the Pylons Project differ from each other on a number of axes: +The Pyramid cookiecutter released under the Pylons Project offers the following configuration options: -- the persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) +- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) -- the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`) +- the persistence mechanism (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) -- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) +- the mechanism of mapping URLs to code (:term:`URL dispatch` or :term:`traversal`) * `pyramid-cookiecutter-starter <https://github.com/Pylons/pyramid-cookiecutter-starter>`_ -* `pyramid-cookiecutter-alchemy <https://github.com/Pylons/pyramid-cookiecutter-alchemy>`_ -* `pyramid-cookiecutter-zodb <https://github.com/Pylons/pyramid-cookiecutter-zodb>`_ -These cookiecutters include: +All configuration options offer a choice of templating language. + +The configuration of mapping URLs to code (routing) depends on the backend option selected, with additional variations as follows. -``pyramid-cookiecutter-starter`` - :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating +``none`` + :term:`URL dispatch` for routing -``pyramid-cookiecutter-alchemy`` - SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Jinja2` for templating. +``sqlalchemy`` + SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Alembic` for database migrations -``pyramid-cookiecutter-zodb`` - :term:`ZODB` for persistent storage, :term:`traversal` for routing, and :term:`Chameleon` for templating +``zodb`` + :term:`ZODB` for persistent storage and :term:`traversal` for routing .. index:: @@ -77,7 +75,7 @@ In :ref:`installing_chapter`, you created a virtual Python environment via the We assume that you :ref:`previously installed cookiecutter <cookiecutters>`, following its installation instructions. -We'll choose ``pyramid-cookiecutter-starter`` to start the project. When we invoke ``cookiecutter``, it will create a directory that represents our project. +When we invoke ``cookiecutter``, it will create a directory that represents our project. We assume our current working directory is the value of ``VENV``. @@ -100,6 +98,11 @@ If prompted for the first item, accept the default ``yes`` by hitting return. 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. @@ -818,6 +821,8 @@ The ``myproject`` :term:`package` lives inside the ``myproject`` #. A ``tests.py`` module, which contains unit test code for the application. +#. A ``routes.py`` module, which contains routing code for the application. + #. A ``views`` package, which contains view code for the application. #. A ``static`` directory, which contains static files, including images and CSS. @@ -853,7 +858,7 @@ also informs Python that the directory which contains it is a *package*. Within this function, application configuration is performed. - Line 7 creates an instance of a :term:`Configurator`. + Line 7 opens a context manager with an instance of a :term:`Configurator`. Line 8 adds support for Jinja2 templating bindings, allowing us to specify renderers with the ``.jinja2`` extension. diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index e78c524ff..89dc6e0f1 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -345,7 +345,7 @@ against your ``mypackage`` package during application initialization. .. note:: This is only an example. In particular, it is not necessary to cause - ``DBSession.remove`` to be called in an application generated from a + ``DBSession.remove`` to be called in an application generated from the :app:`Pyramid` cookiecutter, because these all use the ``pyramid_tm`` package. The cleanup done by ``DBSession.remove`` is unnecessary when ``pyramid_tm`` :term:`middleware` is configured into the application. diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 1e46aa367..05c2ed7f6 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -498,7 +498,7 @@ So far we have done all of our *Quick Tour* as a single Python file. No Python 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. @@ -525,6 +525,11 @@ If prompted for the first item, accept the default ``yes`` by hitting return. 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 @@ and earlier we showed ``--reload`` for application reloading. 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 @@ -858,16 +863,26 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a cookiecutte .. code-block:: bash cd ~ - env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-alchemy --checkout master + env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master 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. diff --git a/docs/quick_tutorial/cookiecutters.rst b/docs/quick_tutorial/cookiecutters.rst index 045808884..e4a585a33 100644 --- a/docs/quick_tutorial/cookiecutters.rst +++ b/docs/quick_tutorial/cookiecutters.rst @@ -4,7 +4,7 @@ Prelude: Quick Project Startup with Cookiecutters ================================================= -To ease the process of getting started on a project, the Pylons Project provides :term:`cookiecutter`\ s that generate sample :app:`Pyramid` projects from project templates. These cookiecutters will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``. +To ease the process of getting started on a project, the Pylons Project provides a :term:`cookiecutter` that generates sample :app:`Pyramid` projects from project templates. The cookiecutter will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``. Objectives @@ -43,6 +43,11 @@ Steps 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. @@ -79,7 +84,7 @@ Analysis ======== Rather than starting from scratch, a cookiecutter can make it easy to get a Python -project containing a working :app:`Pyramid` application. The Pylons Project provides `several cookiecutters <https://github.com/Pylons?q=pyramid-cookiecutter>`_. +project containing a working :app:`Pyramid` application. ``pserve`` is :app:`Pyramid`'s application runner, separating operational details from your code. When you install :app:`Pyramid`, a small command program called ``pserve`` diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst index 5e318187d..dcf411d23 100644 --- a/docs/quick_tutorial/databases.rst +++ b/docs/quick_tutorial/databases.rst @@ -21,10 +21,10 @@ storage and retrieval for the wiki pages in the previous step. .. note:: - The ``pyramid-cookiecutter-alchemy`` cookiecutter is really helpful for getting an SQLAlchemy - project going, including generation of the console script. Since we want to - see all the decisions, we will forgo convenience in this tutorial, and wire - it up ourselves. + The Pyramid cookiecutter ``pyramid-cookiecutter-starter`` is really + helpful for getting a SQLAlchemy project going, including generation of + the console script. Since we want to see all the decisions, we will forgo + convenience in this tutorial, and wire it up ourselves. Objectives 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..0005ba3cb 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`` 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 639aa0881..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 ------------------------------------------------ @@ -275,10 +285,11 @@ Our package doesn't quite have 100% test coverage. Test and coverage cookiecutter defaults --------------------------------------- -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. +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 ^^^^^^^ @@ -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 6c7f24645..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. 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 b2f1dde4a..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 ------------------------------------------------ @@ -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 fb33fc629..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``. |