diff options
| author | Stephen Martin <lockwood@opperline.com> | 2018-09-09 17:05:27 -0700 |
|---|---|---|
| committer | Stephen Martin <lockwood@opperline.com> | 2018-09-09 17:05:27 -0700 |
| commit | 6b6d0e4c2b4e56523bd41aefd9d462858e03f443 (patch) | |
| tree | 51aa7bdc1dec89a6109f469934379726ea9fb835 /docs | |
| parent | 60ab8c81c0e0cda731792cf1ecd540e2d450cc1d (diff) | |
| download | pyramid-6b6d0e4c2b4e56523bd41aefd9d462858e03f443.tar.gz pyramid-6b6d0e4c2b4e56523bd41aefd9d462858e03f443.tar.bz2 pyramid-6b6d0e4c2b4e56523bd41aefd9d462858e03f443.zip | |
merging cookiecutters
Diffstat (limited to 'docs')
25 files changed, 184 insertions, 133 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index b05344ae9..17b97dd29 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1155,11 +1155,9 @@ 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: + The Pyramid cookiecutter can be found here: - * `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>`_ + * `pyramid-cookiecutter-theonecc <https://github.com/Pylons/pyramid-cookiecutter-theonecc>`_ .. versionadded:: 1.8 diff --git a/docs/narr/advanced-features.rst b/docs/narr/advanced-features.rst index 191996c27..71985e49c 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..811285039 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 our +: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..70c86bcac 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 alchemy backend to 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..4c10229a6 100644 --- a/docs/narr/cookiecutters.rst +++ b/docs/narr/cookiecutters.rst @@ -7,11 +7,9 @@ Pyramid cookiecutters 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. -Pyramid cookiecutters have replaced the now deprecated Pyramid scaffolds, and should be used going forward. Pyramid cookiecutters released under the Pylons Project include: +The Pyramid cookiecutter has replaced the now deprecated Pyramid scaffolds, and should be used going forward and can be found here: -* `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>`_ +* `pyramid-cookiecutter-theonecc <https://github.com/Pylons/pyramid-cookiecutter-theonecc>`_ .. 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..b70f43937 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 make it easy to start a new :app:`Pyramid` project. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 3ee6b5367..cc1ecdbee 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..c3da1e920 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 fb5a241db..f016df7be 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 layout what 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:: @@ -28,37 +28,33 @@ 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 + single: pyramid-cookiecutter-theonecc .. _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 differ in configuration options on a number of axes: -- the persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) +- the persistence mechanism it offers (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) -- the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`) +- the mechanism it uses to map URLs to code (:term:`URL dispatch` or :term:`traversal`) -- templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) +- All include an option of templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) -* `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>`_ +* `pyramid-cookiecutter-theonecc <https://github.com/Pylons/pyramid-cookiecutter-theonecc>`_ -These cookiecutters include: +These configurations include: -``pyramid-cookiecutter-starter`` - :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating +``no persistance`` + :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, and :term:`URL dispatch` for routing -``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 +73,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``. @@ -85,13 +81,13 @@ On all platforms, generate a project using cookiecutter. .. code-block:: bash - cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: myproject repo_name [myproject]: myproject @@ -100,6 +96,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. @@ -262,7 +263,7 @@ Here's sample output from a test run on Unix: .. 2 passed in 0.47 seconds -The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-starter`` cookiecutter, only two sample tests exist. +The tests themselves are found in the ``tests.py`` module in your ``cookiecutter``-generated project. Within a project generated by the ``pyramid-cookiecutter-theonecc`` cookiecutter, only two sample tests exist. .. note:: @@ -434,7 +435,7 @@ browser like what is displayed in the following image: .. image:: project.png This is the page shown by default when you visit an unmodified ``cookiecutter`` -generated ``pyramid-cookiecutter-starter`` application in a browser. +generated ``pyramid-cookiecutter-theonecc`` application in a browser. .. index:: single: debug toolbar @@ -515,7 +516,7 @@ this: The Project Structure --------------------- -The ``pyramid-cookiecutter-starter`` cookiecutter generated a :term:`project` (named ``myproject``), +The ``pyramid-cookiecutter-theonecc`` cookiecutter generated a :term:`project` (named ``myproject``), which contains a Python :term:`package`. The package is *also* named ``myproject``; the cookiecutter generates a project which contains a package that shares its name. @@ -818,6 +819,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 +856,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/scaffolding.rst b/docs/narr/scaffolding.rst index 083d831cc..6f64e391f 100644 --- a/docs/narr/scaffolding.rst +++ b/docs/narr/scaffolding.rst @@ -5,7 +5,7 @@ Creating Pyramid Scaffolds .. deprecated:: 1.8 - Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutters` instead. + Scaffolds and the ``pcreate`` script used to generate :app:`Pyramid` projects from scaffolds have been deprecated. Use :ref:`cookiecutter` instead. You can extend Pyramid by creating a :term:`scaffold` template. A scaffold template is useful if you'd like to distribute a customizable configuration of 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 26195a701..af114d3a2 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. @@ -506,17 +506,17 @@ First you'll need to install cookiecutter. $VENV/bin/pip install cookiecutter -Let's use the cookiecutter ``pyramid-cookiecutter-starter`` to create a starter Pyramid project in the current directory, entering values at the prompts as shown below for the following command. +Let's use the cookiecutter ``pyramid-cookiecutter-theonecc`` to create a starter Pyramid project in the current directory, entering values at the prompts as shown below for the following command. .. code-block:: bash - $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: hello_world repo_name [hello_world]: hello_world @@ -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-theonecc`` already configured our package to include the add-on ``pyramid_debugtoolbar`` in its ``setup.py``: .. literalinclude:: quick_tour/package/setup.py @@ -682,7 +687,7 @@ 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 before its release. -Our ``pyramid-cookiecutter-starter`` cookiecutter generated a ``tests.py`` module with +Our ``pyramid-cookiecutter-theonecc`` 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-cov`` tool which yells at us for code that isn't tested: @@ -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-theonecc --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-theonecc 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..dee301a12 100644 --- a/docs/quick_tutorial/cookiecutters.rst +++ b/docs/quick_tutorial/cookiecutters.rst @@ -24,17 +24,17 @@ Steps $VENV/bin/pip install cookiecutter -#. Let's use the cookiecutter ``pyramid-cookiecutter-starter`` to create a starter :app:`Pyramid` project in the current directory, entering values at the prompts as shown below for the following command. +#. Let's use the cookiecutter ``pyramid-cookiecutter-theonecc`` to create a starter :app:`Pyramid` project in the current directory, entering values at the prompts as shown below for the following command. .. code-block:: bash - $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: cc_starter repo_name [cc_starter]: cc_starter @@ -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. @@ -57,6 +62,17 @@ Steps # ...and into which we install our project. env/bin/pip install -e . + **Note:** If you selected ``sqlalchemy`` in the preceding step, continue. Otherwise, skip to the next step. + + .. code-block:: bash + + # Generate your first revision. + env/bin/alembic -c development.ini revision --autogenerate -m "init" + # Upgrade to that revision. + env/bin/alembic -c development.ini upgrade head + # Load default data. + env/bin/initialize_cc_starter_db development.ini + #. Start up the application by pointing :app:`Pyramid`'s ``pserve`` command at the project's (generated) configuration file: @@ -79,7 +95,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 7d10f2470..7d28f4ba2 100644 --- a/docs/quick_tutorial/databases.rst +++ b/docs/quick_tutorial/databases.rst @@ -21,7 +21,7 @@ storage and retrieval for the wiki pages in the previous step. .. note:: - The ``pyramid-cookiecutter-alchemy`` cookiecutter is really helpful for getting an SQLAlchemy + The Pyramid 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. diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index bcedcbe3d..68e5f106d 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -32,20 +32,20 @@ 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 cd ~ - cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + cookiecutter gh:Pylons/pyramid-cookiecutter-theonecc --checkout master If prompted for the first item, accept the default ``yes`` by hitting return. .. code-block:: text - You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. + You've cloned ~/.cookiecutters/pyramid-cookiecutter-theonecc before. Is it okay to delete and re-clone it? [yes]: yes project_name [Pyramid Scaffold]: myproject repo_name [myproject]: myproject @@ -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..d435e0767 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 the ``zodb`` backend 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..91b90e911 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -99,7 +99,7 @@ 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 +when we originally rendered the ``zodb`` backend 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`` diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 7f914267f..c7047664a 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-theonecc --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-theonecc --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 ``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 ``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. On Unix ^^^^^^^ @@ -354,10 +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 ``zodb`` backend cookiecutter has made for you +------------------------------------------------------------ -Creating a project using the ``zodb`` cookiecutter makes the following +Creating a project using the ``zodb`` backend cookiecutter makes the following assumptions: - You are willing to use :term:`ZODB` for persistent storage. @@ -367,10 +378,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..81b020594 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 as part of the ``zodb`` backend 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``. 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 cookiecutter 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..bb2d4cdcf 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -4,9 +4,9 @@ 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 by the ``sqlalchemy`` backend 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 700a105b1..c75f6d5ba 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 we originally rendered the ``sqlalchemy`` backend 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 the ``sqlalchemy`` backend cookiecutter, 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..133bf75d3 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-theonecc --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-theonecc --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-theonecc 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,10 +519,10 @@ 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 ``sqlalchemy`` backend cookiecutter has made for you +------------------------------------------------------------------ -Creating a project using the ``alchemy`` cookiecutter makes the following +Creating a project using the ``sqlalchemy`` 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..99a594d31 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 as part of the ``sqlalchemy`` backend +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_``. 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``. |
