diff options
Diffstat (limited to 'docs')
69 files changed, 1060 insertions, 655 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index 7a9c91668..c14729fc4 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -43,19 +43,17 @@ Glossary <http://svn.repoze.org>`_. Pyramid was originally known as :mod:`repoze.bfg`. - setuptools - `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ + Setuptools + `Setuptools <https://setuptools.readthedocs.io/en/latest/>`_ builds on Python's ``distutils`` to provide easier building, - distribution, and installation of libraries and applications. As of - this writing, setuptools runs under Python 2, but not under Python 3. - You can use :term:`distribute` under Python 3 instead. + distribution, and installation of libraries and applications. distribute - `Distribute <https://pypi.org/project/distribute/>`_ is a fork of - :term:`setuptools` which runs on both Python 2 and Python 3. + `Distribute <https://pypi.org/project/distribute/>`_ is a fork of :term:`Setuptools` which runs on both Python 2 and Python 3. + It is now in legacy state because :term:`Setuptools` now runs on both Python 2 and 3. pkg_resources - A module which ships with :term:`setuptools` and :term:`distribute` that + A module which ships with :term:`Setuptools` and :term:`distribute` that provides an API for addressing "asset files" within a Python :term:`package`. Asset files are static files, template files, etc; basically anything non-Python-source that lives in a Python package can @@ -103,7 +101,7 @@ Glossary ``easy_install``. entry point - A :term:`setuptools` indirection, defined within a setuptools + A :term:`Setuptools` indirection, defined within a Setuptools :term:`distribution` setup.py. It is usually a name which refers to a function somewhere in a package which is held by the distribution. @@ -111,7 +109,7 @@ Glossary dotted Python name A reference to a Python object by name using a string, in the form ``path.to.modulename:attributename``. Often used in Pyramid and - setuptools configurations. A variant is used in dotted names within + Setuptools configurations. A variant is used in dotted names within configurator method arguments that name objects (such as the "add_view" method's "view" and "context" attributes): the colon (``:``) is not used; in its place is a dot. @@ -977,7 +975,7 @@ Glossary distutils The standard system for packaging and distributing Python packages. See https://docs.python.org/2/distutils/index.html for more information. - :term:`setuptools` is actually an *extension* of the Distutils. + :term:`Setuptools` is actually an *extension* of the Distutils. exception response A :term:`response` that is generated as the result of a raised exception @@ -1155,13 +1153,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..d1d64f0c3 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``, @@ -735,7 +735,7 @@ feature, a :term:`Configurator` API exists named - A directory of static files served up by an instance of the ``pyramid.static.static_view`` helper class. -- Any other asset (or set of assets) addressed by code that uses the setuptools +- Any other asset (or set of assets) addressed by code that uses the Setuptools :term:`pkg_resources` API. .. index:: diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 98e34fea2..7af6bba43 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: @@ -896,7 +896,7 @@ See :ref:`logging_chapter` for more information on logging within Making Your Script into a Console Script ---------------------------------------- -A "console script" is :term:`setuptools` terminology for a script that gets +A "console script" is :term:`Setuptools` terminology for a script that gets installed into the ``bin`` directory of a Python :term:`virtual environment` (or "base" Python environment) when a :term:`distribution` which houses that script is installed. Because it's installed into the ``bin`` directory of a 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..248b432d3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -117,7 +117,7 @@ following options: ``py`` that allows users to run any installed version of Python. .. warning:: After you install Python on Windows, you might need to add the - directory where Python and other programs—such as pip, setuptools, and + directory where Python and other programs—such as pip, :term:`Setuptools`, and cookiecutter—are installed to your environment's ``Path``. This will make it possible to invoke them from a command prompt. @@ -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..ac8f7fdca 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. @@ -48,7 +48,7 @@ The line in ``[app:main]`` above that says ``use = egg:myproject`` is actually shorthand for a longer spelling: ``use = egg:myproject#main``. The ``#main`` part is omitted for brevity, as ``#main`` is a default defined by PasteDeploy. ``egg:myproject#main`` is a string which has meaning to PasteDeploy. It points -at a :term:`setuptools` :term:`entry point` named ``main`` defined in the +at a :term:`Setuptools` :term:`entry point` named ``main`` defined in the ``myproject`` project. Take a look at the generated ``setup.py`` file for this project. @@ -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..725263407 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. @@ -239,26 +242,26 @@ On Windows: %VENV%\Scripts\pip install -e ".[testing]" Once the testing requirements are installed, then you can run the tests using -the ``py.test`` command that was just installed in the ``bin`` directory of +the ``pytest`` command that was just installed in the ``bin`` directory of your virtual environment. 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 Here's sample output from a test run on Unix: .. code-block:: bash - $VENV/bin/py.test -q + $VENV/bin/pytest -q .. 2 passed in 0.47 seconds @@ -266,28 +269,28 @@ The tests themselves are found in the ``tests.py`` module in your ``cookiecutter .. note:: - The ``-q`` option is passed to the ``py.test`` command to limit the output + The ``-q`` option is passed to the ``pytest`` command to limit the output to a stream of dots. If you don't pass ``-q``, you'll see verbose test result output (which normally isn't very useful). Alternatively, if you'd like to see test coverage, pass the ``--cov`` option -to ``py.test``: +to ``pytest``: .. code-block:: bash - $VENV/bin/py.test --cov -q + $VENV/bin/pytest --cov -q -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. .. code-block:: bash - $VENV/bin/py.test --cov=myproject myproject/tests.py -q + $VENV/bin/pytest --cov=myproject myproject/tests.py -q -.. 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. .. index:: @@ -584,7 +587,7 @@ describe, run, and test your application. #. ``pytest.ini`` is a configuration file for running tests. #. ``setup.py`` is the file you'll use to test and distribute your application. - It is a standard :term:`setuptools` ``setup.py`` file. + It is a standard :term:`Setuptools` ``setup.py`` file. .. index:: single: PasteDeploy @@ -708,7 +711,7 @@ Without the presence of a ``MANIFEST.in`` file or without checking your source code into a version control repository, ``setup.py sdist`` places only *Python source files* (files ending with a ``.py`` extension) into tarballs generated by ``python setup.py sdist``. This means, for example, if your project was not -checked into a setuptools-compatible source control system, and your project +checked into a Setuptools-compatible source control system, and your project directory didn't contain a ``MANIFEST.in`` file that told the ``sdist`` machinery to include ``*.pt`` files, the ``myproject/templates/mytemplate.pt`` file would not be included in the generated tarball. @@ -717,20 +720,20 @@ Projects generated by Pyramid cookiecutters include a default ``MANIFEST.in`` fi The ``MANIFEST.in`` file contains declarations which tell it to include files like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. If you include files with extensions other than the files named in the project's -``MANIFEST.in`` and you don't make use of a setuptools-compatible version +``MANIFEST.in`` and you don't make use of a Setuptools-compatible version control system, you'll need to edit the ``MANIFEST.in`` file and include the statements necessary to include your new files. See https://docs.python.org/2/distutils/sourcedist.html#principle for more information about how to do this. -You can also delete ``MANIFEST.in`` from your project and rely on a setuptools +You can also delete ``MANIFEST.in`` from your project and rely on a :term:`Setuptools` feature which simply causes all files checked into a version control system to be put into the generated tarball. To allow this to happen, check all the files that you'd like to be distributed along with your application's Python files into Subversion. After you do this, when you rerun ``setup.py sdist``, all files checked into the version control system will be included in the tarball. If you don't use Subversion, and instead use a different version -control system, you may need to install a setuptools add-on such as +control system, you may need to install a :term:`Setuptools` add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. .. index:: @@ -739,7 +742,7 @@ control system, you may need to install a setuptools add-on such as ``setup.py`` ~~~~~~~~~~~~ -The ``setup.py`` file is a :term:`setuptools` setup file. It is meant to be +The ``setup.py`` file is a :term:`Setuptools` setup file. It is meant to be used to define requirements for installing dependencies for your package and testing, as well as distributing your application. @@ -757,13 +760,13 @@ Our generated ``setup.py`` looks like this: :language: python :linenos: -The ``setup.py`` file calls the setuptools ``setup`` function, which does +The ``setup.py`` file calls the :term:`Setuptools` ``setup`` function, which does various things depending on the arguments passed to ``pip`` on the command line. Within the arguments to this function call, information about your application is kept. While it's beyond the scope of this documentation to explain -everything about setuptools setup files, we'll provide a whirlwind tour of what +everything about :term:`Setuptools` setup files, we'll provide a whirlwind tour of what exists in this file in this section. Your application's name can be any string; it is specified in the ``name`` @@ -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. @@ -1042,7 +1047,7 @@ The ``tests.py`` module includes tests for your application. :linenos: This sample ``tests.py`` file has one unit test and one functional test defined -within it. These tests are executed when you run ``py.test -q``. You may add +within it. These tests are executed when you run ``pytest -q``. You may add more tests here as you build your application. You are not required to write tests to use :app:`Pyramid`. This file is simply provided for convenience and example. diff --git a/docs/narr/scaffolding.rst b/docs/narr/scaffolding.rst index 083d831cc..47eb2c658 100644 --- a/docs/narr/scaffolding.rst +++ b/docs/narr/scaffolding.rst @@ -21,11 +21,11 @@ Basics A scaffold template is just a bunch of source files and directories on disk. A small definition class points at this directory. It is in turn pointed at by a -:term:`setuptools` "entry point" which registers the scaffold so it can be +:term:`Setuptools` "entry point" which registers the scaffold so it can be found by the ``pcreate`` command. To create a scaffold template, create a Python :term:`distribution` to house -the scaffold which includes a ``setup.py`` that relies on the ``setuptools`` +the scaffold which includes a ``setup.py`` that relies on the :term:`Setuptools` package. See `Packaging and Distributing Projects <https://packaging.python.org/tutorials/packaging-projects/>`_ for more information about how to do this. For example, we'll pretend the distribution you create diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 5bccd6d52..6b6f9a1f1 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -714,14 +714,16 @@ object that implements the following interface: .. code-block:: python :linenos: - class IAuthorizationPolicy(object): + class IAuthorizationPolicy(Interface): """ An object representing a Pyramid authorization policy. """ - def permits(self, context, principals, permission): - """ Return ``True`` if any of the ``principals`` is allowed the - ``permission`` in the current ``context``, else return ``False`` + def permits(context, principals, permission): + """ Return an instance of :class:`pyramid.security.Allowed` if any + of the ``principals`` is allowed the ``permission`` in the current + ``context``, else return an instance of + :class:`pyramid.security.Denied`. """ - def principals_allowed_by_permission(self, context, permission): + def principals_allowed_by_permission(context, permission): """ Return a set of principal identifiers allowed by the ``permission`` in ``context``. This behavior is optional; if you choose to not implement it you should define this method as diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index ad4ba2186..8048ca62c 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -275,7 +275,7 @@ without needing to invoke the actual application configuration implied by its In the above example, we create a ``MyTest`` test case that inherits from :class:`unittest.TestCase`. If it's in our :app:`Pyramid` application, it will -be found when ``py.test`` is run. It has two test methods. +be found when ``pytest`` is run. It has two test methods. The first test method, ``test_view_fn_forbidden`` tests the ``view_fn`` when the authentication policy forbids the current user the ``edit`` permission. Its @@ -365,7 +365,7 @@ Functional tests test your literal application. In Pyramid, functional tests are typically written using the :term:`WebTest` package, which provides APIs for invoking HTTP(S) requests to your application. -We also like ``py.test`` and ``pytest-cov`` to provide simple testing and +We also like ``pytest`` and ``pytest-cov`` to provide simple testing and coverage reports. Regardless of which testing :term:`package` you use, be sure to add a diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index 2ca162c46..07f955de8 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -83,14 +83,11 @@ At the time of a Pyramid version release, each supports all versions of Python through the end of their lifespans. The end-of-life for a given version of Python is when security updates are no longer released. -- `Python 3.2 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ - ends February 2016. -- `Python 3.3 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ - ends September 2017. -- `Python 3.4 Lifespan <https://www.python.org/dev/peps/pep-0429/>`_ TBD. -- `Python 3.5 Lifespan <https://www.python.org/dev/peps/pep-0478/>`_ TBD. -- `Python 3.6 Lifespan <https://www.python.org/dev/peps/pep-0494/#id4>`_ - December 2021. +- `Python 2.7 Lifespan <https://devguide.python.org/#status-of-python-branches>`_ 2020-01-01. +- `Python 3.4 Lifespan <https://devguide.python.org/#status-of-python-branches>`_ 2019-03-16 . +- `Python 3.5 Lifespan <https://devguide.python.org/#status-of-python-branches>`_ 2020-09-13 . +- `Python 3.6 Lifespan <https://devguide.python.org/#status-of-python-branches>`_ 2021-12-23. +- `Python 3.7 Lifespan <https://devguide.python.org/#status-of-python-branches>`_ 2023-06-27 . To determine the Python support for a specific release of Pyramid, view its ``tox.ini`` file at the root of the repository's version. 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..1e2c71cf0 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -19,7 +19,7 @@ Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this Quick Tour, it means `Python <https://www.python.org/downloads/>`_, :mod:`python:venv` (or `virtualenv for Python 2.7 <https://virtualenv.pypa.io/en/stable/>`_), -`pip <https://pypi.org/project/pip/>`_, and `setuptools +`pip <https://pypi.org/project/pip/>`_, and `Setuptools <https://pypi.org/project/setuptools/>`_. To save a little bit of typing and to be certain that we use the modules, @@ -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 @@ -675,8 +680,8 @@ the relevant ``.ini`` configuration file. :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and :ref:`pyramid_debugtoolbar <toolbar:overview>` -Unit tests and ``py.test`` -========================== +Unit tests and ``pytest`` +========================= Yikes! We got this far and we haven't yet discussed tests. This is particularly egregious, as Pyramid has had a deep commitment to full test coverage since @@ -684,7 +689,7 @@ before its release. Our ``pyramid-cookiecutter-starter`` cookiecutter generated a ``tests.py`` module with one unit test and one functional test in it. It also configured ``setup.py`` with test requirements: -``py.test`` as the test runner, ``WebTest`` for running view tests, and the +``pytest`` as the test runner, ``WebTest`` for running view tests, and the ``pytest-cov`` tool which yells at us for code that isn't tested: .. literalinclude:: quick_tour/package/setup.py @@ -701,7 +706,7 @@ We already installed the test requirements when we ran the command ``$VENV/bin/p .. code-block:: bash - $VENV/bin/py.test --cov --cov-report=term-missing + $VENV/bin/pytest --cov --cov-report=term-missing This yields the following output. @@ -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/authentication.rst b/docs/quick_tutorial/authentication.rst index eb9b6b395..cd038ea36 100644 --- a/docs/quick_tutorial/authentication.rst +++ b/docs/quick_tutorial/authentication.rst @@ -39,7 +39,7 @@ Steps .. literalinclude:: authentication/setup.py :language: python - :emphasize-lines: 4 + :emphasize-lines: 6 :linenos: #. We can now install our project in development mode: diff --git a/docs/quick_tutorial/authentication/setup.py b/docs/quick_tutorial/authentication/setup.py index a5117af5a..64366a2df 100644 --- a/docs/quick_tutorial/authentication/setup.py +++ b/docs/quick_tutorial/authentication/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'bcrypt', 'pyramid', @@ -7,10 +9,24 @@ requires = [ 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/authorization/setup.py b/docs/quick_tutorial/authorization/setup.py index a5117af5a..64366a2df 100644 --- a/docs/quick_tutorial/authorization/setup.py +++ b/docs/quick_tutorial/authorization/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'bcrypt', 'pyramid', @@ -7,10 +9,24 @@ requires = [ 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) 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 7d10f2470..db75d70ce 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 @@ -41,108 +41,100 @@ Objectives Steps ===== -#. We are going to use the forms step as our starting point: +#. We are going to use the forms step as our starting point: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r forms databases; cd databases + cd ..; cp -r forms databases; cd databases -#. We need to add some dependencies in ``databases/setup.py`` as well as an - "entry point" for the command-line script: +#. We need to add some dependencies in ``databases/setup.py`` as well as an :term:`entry point` for the command-line script: - .. literalinclude:: databases/setup.py - :linenos: + .. literalinclude:: databases/setup.py + :linenos: + :emphasize-lines: 9-10, 12, 34-36 - .. note:: + .. note:: We aren't yet doing ``$VENV/bin/pip install -e .`` because we need to write a script and update configuration first. - We aren't yet doing ``$VENV/bin/pip install -e .`` as we will change it - later. +#. Our configuration file at ``databases/development.ini`` wires together some new pieces: -#. Our configuration file at ``databases/development.ini`` wires together some - new pieces: + .. literalinclude:: databases/development.ini + :language: ini - .. literalinclude:: databases/development.ini - :language: ini +#. This engine configuration now needs to be read into the application through changes in ``databases/tutorial/__init__.py``: -#. This engine configuration now needs to be read into the application through - changes in ``databases/tutorial/__init__.py``: + .. literalinclude:: databases/tutorial/__init__.py + :linenos: - .. literalinclude:: databases/tutorial/__init__.py - :linenos: +#. Make a command-line script at ``databases/tutorial/initialize_db.py`` to initialize the database: -#. Make a command-line script at ``databases/tutorial/initialize_db.py`` to - initialize the database: + .. literalinclude:: databases/tutorial/initialize_db.py + :linenos: - .. literalinclude:: databases/tutorial/initialize_db.py - :linenos: +#. Now that we've got all the pieces ready, and because we changed ``setup.py``, we now install all the goodies: -#. Since ``setup.py`` changed, we now run it: + .. code-block:: bash - .. code-block:: bash + $VENV/bin/pip install -e . - $VENV/bin/pip install -e . +#. The script references some models in ``databases/tutorial/models.py``: -#. The script references some models in ``databases/tutorial/models.py``: + .. literalinclude:: databases/tutorial/models.py + :linenos: - .. literalinclude:: databases/tutorial/models.py - :linenos: +#. Let's run this console script, thus producing our database and table: -#. Let's run this console script, thus producing our database and table: + .. code-block:: bash - .. code-block:: bash + $VENV/bin/initialize_tutorial_db development.ini - $VENV/bin/initialize_tutorial_db development.ini - - 2016-04-16 13:01:33,055 INFO [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1 - 2016-04-16 13:01:33,055 INFO [sqlalchemy.engine.base.Engine][MainThread] () - 2016-04-16 13:01:33,056 INFO [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1 - 2016-04-16 13:01:33,056 INFO [sqlalchemy.engine.base.Engine][MainThread] () - 2016-04-16 13:01:33,057 INFO [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages") - 2016-04-16 13:01:33,057 INFO [sqlalchemy.engine.base.Engine][MainThread] () - 2016-04-16 13:01:33,058 INFO [sqlalchemy.engine.base.Engine][MainThread] - CREATE TABLE wikipages ( + 2016-04-16 13:01:33,055 INFO [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1 + 2016-04-16 13:01:33,055 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2016-04-16 13:01:33,056 INFO [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1 + 2016-04-16 13:01:33,056 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2016-04-16 13:01:33,057 INFO [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages") + 2016-04-16 13:01:33,057 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2016-04-16 13:01:33,058 INFO [sqlalchemy.engine.base.Engine][MainThread] + CREATE TABLE wikipages ( uid INTEGER NOT NULL, title TEXT, body TEXT, PRIMARY KEY (uid), UNIQUE (title) - ) + ) - 2016-04-16 13:01:33,058 INFO [sqlalchemy.engine.base.Engine][MainThread] () - 2016-04-16 13:01:33,059 INFO [sqlalchemy.engine.base.Engine][MainThread] COMMIT - 2016-04-16 13:01:33,062 INFO [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit) - 2016-04-16 13:01:33,062 INFO [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?) - 2016-04-16 13:01:33,063 INFO [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>') - 2016-04-16 13:01:33,063 INFO [sqlalchemy.engine.base.Engine][MainThread] COMMIT + 2016-04-16 13:01:33,058 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2016-04-16 13:01:33,059 INFO [sqlalchemy.engine.base.Engine][MainThread] COMMIT + 2016-04-16 13:01:33,062 INFO [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit) + 2016-04-16 13:01:33,062 INFO [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?) + 2016-04-16 13:01:33,063 INFO [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>') + 2016-04-16 13:01:33,063 INFO [sqlalchemy.engine.base.Engine][MainThread] COMMIT -#. With our data now driven by SQLAlchemy queries, we need to update our - ``databases/tutorial/views.py``: +#. With our data now driven by SQLAlchemy queries, we need to update our ``databases/tutorial/views.py``: - .. literalinclude:: databases/tutorial/views.py - :linenos: + .. literalinclude:: databases/tutorial/views.py + :linenos: -#. Our tests in ``databases/tutorial/tests.py`` changed to include SQLAlchemy - bootstrapping: +#. Our tests in ``databases/tutorial/tests.py`` changed to include SQLAlchemy bootstrapping: - .. literalinclude:: databases/tutorial/tests.py - :linenos: + .. literalinclude:: databases/tutorial/tests.py + :linenos: -#. Run the tests in your package using ``py.test``: +#. Run the tests in your package using ``pytest``: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q - .. - 2 passed in 1.41 seconds + $VENV/bin/pytest tutorial/tests.py -q + .. + 2 passed in 1.41 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ in a browser. +#. Open http://localhost:6543/ in a browser. Analysis diff --git a/docs/quick_tutorial/databases/setup.py b/docs/quick_tutorial/databases/setup.py index 13d1d6637..c4e4ae2f2 100644 --- a/docs/quick_tutorial/databases/setup.py +++ b/docs/quick_tutorial/databases/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', @@ -10,12 +12,27 @@ requires = [ 'zope.sqlalchemy', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - [console_scripts] - initialize_tutorial_db = tutorial.initialize_db:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + 'console_scripts': [ + 'initialize_tutorial_db = tutorial.initialize_db:main' + ], + }, ) diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst index b49dd1f97..2607c83f2 100644 --- a/docs/quick_tutorial/debugtoolbar.rst +++ b/docs/quick_tutorial/debugtoolbar.rst @@ -32,30 +32,40 @@ Objectives Steps ===== -#. First we copy the results of the previous step, as well as install the - ``pyramid_debugtoolbar`` package: +#. First we copy the results of the previous step. - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r ini debugtoolbar; cd debugtoolbar - $VENV/bin/pip install -e . - $VENV/bin/pip install pyramid_debugtoolbar + cd ..; cp -r ini debugtoolbar; cd debugtoolbar -#. Our ``debugtoolbar/development.ini`` gets a configuration entry for - ``pyramid.includes``: +#. Add ``pyramid_debugtoolbar`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra" for development: - .. literalinclude:: debugtoolbar/development.ini - :language: ini - :linenos: + .. literalinclude:: debugtoolbar/setup.py + :language: python + :linenos: + :emphasize-lines: 10-16, 20-22 -#. Run the WSGI application with: +#. Install our project and its newly added dependency. + Note that we use the extra specifier ``[dev]`` to install development requirements and surround it and the period with double quote marks. - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pip install -e ".[dev]" -#. Open http://localhost:6543/ in your browser. See the handy - toolbar on the right. +#. Our ``debugtoolbar/development.ini`` gets a configuration entry for ``pyramid.includes``: + + .. literalinclude:: debugtoolbar/development.ini + :language: ini + :linenos: + +#. Run the WSGI application with: + + .. code-block:: bash + + $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. + See the handy toolbar on the right. Analysis @@ -87,30 +97,36 @@ experience otherwise inexplicable client-side weirdness, you can shut it off by commenting out the ``pyramid_debugtoolbar`` line in ``pyramid.includes`` temporarily. +Finally we've introduced the concept of :term:`Setuptools` extras. +These are optional or recommended features that may be installed with an "extras" specifier, in this case, ``dev``. +The specifier is the name of a key in a Python dictionary, and is surrounded by square brackets when invoked on the command line, for example, . +The value for the key is a Python list of dependencies. + .. seealso:: See also :ref:`pyramid_debugtoolbar <toolbar:overview>`. Extra credit ============ -#. Why don't we add ``pyramid_debugtoolbar`` to the list of - ``install_requires`` dependencies in ``debugtoolbar/setup.py``? +#. We added ``pyramid_debugtoolbar`` to the list of ``dev_requires`` dependencies in ``debugtoolbar/setup.py``. + We then installed the dependencies via ``pip install -e ".[dev]"`` by virtue of the Setuptools ``extras_require`` value in the Python dictionary. + Why did we add them there instead of in the ``requires`` list? -#. Introduce a bug into your application. Change: +#. Introduce a bug into your application. Change: - .. code-block:: python + .. code-block:: python - def hello_world(request): - return Response('<body><h1>Hello World!</h1></body>') + def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') - to: + to: - .. code-block:: python + .. code-block:: python - def hello_world(request): - return xResponse('<body><h1>Hello World!</h1></body>') + def hello_world(request): + return xResponse('<body><h1>Hello World!</h1></body>') - Save, and visit http://localhost:6543/ again. Notice the nice traceback - display. On the lowest line, click the "screen" icon to the right, and try - typing the variable names ``request`` and ``Response``. What else can you - discover? + Save, and visit http://localhost:6543/ again. + Notice the nice traceback display. + On the lowest line, click the "screen" icon to the right, and try typing the variable names ``request`` and ``Response``. + What else can you discover? diff --git a/docs/quick_tutorial/debugtoolbar/setup.py b/docs/quick_tutorial/debugtoolbar/setup.py index a93cf6a73..53bc0f5c7 100644 --- a/docs/quick_tutorial/debugtoolbar/setup.py +++ b/docs/quick_tutorial/debugtoolbar/setup.py @@ -1,14 +1,28 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst index be745764b..3cd1e26aa 100644 --- a/docs/quick_tutorial/forms.rst +++ b/docs/quick_tutorial/forms.rst @@ -31,77 +31,72 @@ Objectives Steps ===== -#. First we copy the results of the ``view_classes`` step: +#. First we copy the results of the ``view_classes`` step: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r view_classes forms; cd forms + cd ..; cp -r view_classes forms; cd forms -#. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then - pulls in Colander as a dependency: +#. Let's edit ``forms/setup.py`` to declare a dependency on Deform, which in turn pulls in Colander as a dependency: - .. literalinclude:: forms/setup.py - :emphasize-lines: 4 - :linenos: + .. literalinclude:: forms/setup.py + :emphasize-lines: 6 + :linenos: -#. We can now install our project in development mode: +#. We can now install our project in development mode: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e . -#. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS, - JavaScript, etc., as well as our demo wiki page's views: +#. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS, JavaScript, etc., as well as our demo wiki page's views: - .. literalinclude:: forms/tutorial/__init__.py - :linenos: + .. literalinclude:: forms/tutorial/__init__.py + :linenos: -#. Implement the new views, as well as the form schemas and some dummy data, in - ``forms/tutorial/views.py``: +#. Implement the new views, as well as the form schemas and some dummy data, in ``forms/tutorial/views.py``: - .. literalinclude:: forms/tutorial/views.py - :linenos: + .. literalinclude:: forms/tutorial/views.py + :linenos: -#. A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``: +#. A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``: - .. literalinclude:: forms/tutorial/wiki_view.pt - :language: html - :linenos: + .. literalinclude:: forms/tutorial/wiki_view.pt + :language: html + :linenos: -#. Another template for adding/editing in - ``forms/tutorial/wikipage_addedit.pt``: +#. Another template for adding/editing in ``forms/tutorial/wikipage_addedit.pt``: - .. literalinclude:: forms/tutorial/wikipage_addedit.pt - :language: html - :linenos: + .. literalinclude:: forms/tutorial/wikipage_addedit.pt + :language: html + :linenos: -#. Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki - page: +#. Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki page: - .. literalinclude:: forms/tutorial/wikipage_view.pt - :language: html - :linenos: + .. literalinclude:: forms/tutorial/wikipage_view.pt + :language: html + :linenos: -#. Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them: +#. Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them: - .. literalinclude:: forms/tutorial/tests.py - :linenos: + .. literalinclude:: forms/tutorial/tests.py + :linenos: -#. Run the tests: +#. Run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q - .. - 2 passed in 0.45 seconds + $VENV/bin/pytest tutorial/tests.py -q + .. + 6 passed in 0.81 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ in a browser. +#. Open http://localhost:6543/ in a browser. Analysis diff --git a/docs/quick_tutorial/forms/setup.py b/docs/quick_tutorial/forms/setup.py index 968889e74..0e9ea72bc 100644 --- a/docs/quick_tutorial/forms/setup.py +++ b/docs/quick_tutorial/forms/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', @@ -7,10 +9,24 @@ requires = [ 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/forms/tutorial/tests.py b/docs/quick_tutorial/forms/tutorial/tests.py index 5a2c40904..f0e39aa38 100644 --- a/docs/quick_tutorial/forms/tutorial/tests.py +++ b/docs/quick_tutorial/forms/tutorial/tests.py @@ -34,3 +34,33 @@ class TutorialFunctionalTests(unittest.TestCase): def test_home(self): res = self.testapp.get('/', status=200) self.assertIn(b'<title>Wiki: View</title>', res.body) + + def test_add_page(self): + res = self.testapp.get('/add', status=200) + self.assertIn(b'<h1>Wiki</h1>', res.body) + + def test_edit_page(self): + res = self.testapp.get('/101/edit', status=200) + self.assertIn(b'<h1>Wiki</h1>', res.body) + + def test_post_wiki(self): + self.testapp.post('/add', { + "title": "New Title", + "body": "<p>New Body</p>", + "submit": "submit" + }, status=302) + + res = self.testapp.get('/103', status=200) + self.assertIn(b'<h1>New Title</h1>', res.body) + self.assertIn(b'<p>New Body</p>', res.body) + + def test_edit_wiki(self): + self.testapp.post('/102/edit', { + "title": "New Title", + "body": "<p>New Body</p>", + "submit": "submit" + }, status=302) + + res = self.testapp.get('/102', status=200) + self.assertIn(b'<h1>New Title</h1>', res.body) + self.assertIn(b'<p>New Body</p>', res.body) diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst index fa56b4589..054d03761 100644 --- a/docs/quick_tutorial/functional_testing.rst +++ b/docs/quick_tutorial/functional_testing.rst @@ -31,31 +31,40 @@ Objectives Steps ===== -#. First we copy the results of the previous step, as well as install the - ``webtest`` package: +#. First we copy the results of the previous step. - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r unit_testing functional_testing; cd functional_testing - $VENV/bin/pip install -e . - $VENV/bin/pip install webtest + cd ..; cp -r unit_testing functional_testing; cd functional_testing -#. Let's extend ``functional_testing/tutorial/tests.py`` to include a - functional test: +#. Add ``webtest`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra": - .. literalinclude:: functional_testing/tutorial/tests.py - :linenos: + .. literalinclude:: functional_testing/setup.py + :language: python + :linenos: + :emphasize-lines: 16 - Be sure this file is not executable, or ``pytest`` may not include your - tests. +#. Install our project and its newly added dependency. + Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks. + + .. code-block:: bash + + $VENV/bin/pip install -e ".[dev]" + +#. Let's extend ``functional_testing/tutorial/tests.py`` to include a functional test: + + .. literalinclude:: functional_testing/tutorial/tests.py + :linenos: + + Be sure this file is not executable, or ``pytest`` may not include your tests. -#. Now run the tests: +#. Now run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q - .. - 2 passed in 0.25 seconds + $VENV/bin/pytest tutorial/tests.py -q + .. + 2 passed in 0.25 seconds Analysis diff --git a/docs/quick_tutorial/functional_testing/setup.py b/docs/quick_tutorial/functional_testing/setup.py index a93cf6a73..a0fa8217c 100644 --- a/docs/quick_tutorial/functional_testing/setup.py +++ b/docs/quick_tutorial/functional_testing/setup.py @@ -1,14 +1,30 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index ce92914fe..0bb7da1ba 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -11,19 +11,16 @@ simpler, better application running. Background ========== -Pyramid has a first-class concept of :ref:`configuration <configuration_narr>` -distinct from code. This approach is optional, but its presence makes it -distinct from other Python web frameworks. It taps into Python's ``setuptools`` -library, which establishes conventions for installing and providing "entry -points" for Python projects. Pyramid uses an entry point to let a Pyramid -application know where to find the WSGI app. +Pyramid has a first-class concept of :ref:`configuration <configuration_narr>` distinct from code. +This approach is optional, but its presence makes it distinct from other Python web frameworks. +It taps into Python's :term:`Setuptools` library, which establishes conventions for installing and providing ":term:`entry point`\ s" for Python projects. +Pyramid uses an :term:`entry point` to let a Pyramid application know where to find the WSGI app. Objectives ========== -- Modify our ``setup.py`` to have an entry point telling Pyramid the location - of the WSGI app. +- Modify our ``setup.py`` to have an :term:`entry point` telling Pyramid the location of the WSGI app. - Create an application driven by an ``.ini`` file. @@ -35,50 +32,48 @@ Objectives Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the previous step: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r package ini; cd ini + cd ..; cp -r package ini; cd ini -#. Our ``ini/setup.py`` needs a setuptools "entry point" in the ``setup()`` - function: +#. Our ``ini/setup.py`` needs a :term:`Setuptools` :term:`entry point` in the ``setup()`` function: - .. literalinclude:: ini/setup.py - :linenos: + .. literalinclude:: ini/setup.py + :linenos: + :emphasize-lines: 13-17 -#. We can now install our project, thus generating (or re-generating) an "egg" - at ``ini/tutorial.egg-info``: +#. We can now install our project, thus generating (or re-generating) an "egg" at ``ini/tutorial.egg-info``: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e . -#. Let's make a file ``ini/development.ini`` for our configuration: +#. Let's make a file ``ini/development.ini`` for our configuration: - .. literalinclude:: ini/development.ini - :language: ini - :linenos: + .. literalinclude:: ini/development.ini + :language: ini + :linenos: -#. We can refactor our startup code from the previous step's ``app.py`` into - ``ini/tutorial/__init__.py``: +#. We can refactor our startup code from the previous step's ``app.py`` into ``ini/tutorial/__init__.py``: - .. literalinclude:: ini/tutorial/__init__.py - :linenos: + .. literalinclude:: ini/tutorial/__init__.py + :linenos: -#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: +#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: - .. code-block:: bash + .. code-block:: bash - rm tutorial/app.py + rm tutorial/app.py -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/. +#. Open http://localhost:6543/. Analysis ======== @@ -89,8 +84,7 @@ application. Processing then proceeds as described in the Pyramid chapter on - ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial``. -- The projects's ``setup.py`` has defined an "entry point" (lines 10-13) for the - project's "main" entry point of ``tutorial:main``. +- The projects's ``setup.py`` has defined an :term:`entry point` (lines 10-13) for the project's "main" :term:`entry point` of ``tutorial:main``. - The ``tutorial`` package's ``__init__`` has a ``main`` function. @@ -133,8 +127,7 @@ Extra credit #. Can we have multiple ``.ini`` configuration files for a project? Why might you want to do that? -#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when it - declared ``tutorial:main`` function. Why not? +#. The :term:`entry point` in ``setup.py`` didn't mention ``__init__.py`` when it declared ``tutorial:main`` function. Why not? #. What is the purpose of ``**settings``? What does the ``**`` signify? diff --git a/docs/quick_tutorial/ini/setup.py b/docs/quick_tutorial/ini/setup.py index a93cf6a73..f1d06fe75 100644 --- a/docs/quick_tutorial/ini/setup.py +++ b/docs/quick_tutorial/ini/setup.py @@ -1,14 +1,18 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +setup( + name='tutorial', + install_requires=requires, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst index 87122a374..ed9acd955 100644 --- a/docs/quick_tutorial/jinja2.rst +++ b/docs/quick_tutorial/jinja2.rst @@ -22,45 +22,55 @@ Objectives Steps ===== -#. In this step let's start by copying the ``view_class`` step's directory, - and then installing the ``pyramid_jinja2`` add-on. +#. In this step let's start by copying the ``view_class`` step's directory from a few steps ago. - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r view_classes jinja2; cd jinja2 - $VENV/bin/pip install -e . - $VENV/bin/pip install pyramid_jinja2 + cd ..; cp -r view_classes jinja2; cd jinja2 -#. We need to include ``pyramid_jinja2`` in ``jinja2/tutorial/__init__.py``: +#. Add ``pyramid_jinja2`` to our project's dependencies in ``setup.py``: - .. literalinclude:: jinja2/tutorial/__init__.py - :linenos: + .. literalinclude:: jinja2/setup.py + :language: python + :linenos: + :emphasize-lines: 8 -#. Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``: +#. Install our project and its newly added dependency. - .. literalinclude:: jinja2/tutorial/views.py - :linenos: + .. code-block:: bash -#. Add ``jinja2/tutorial/home.jinja2`` as a template: + $VENV/bin/pip install -e . - .. literalinclude:: jinja2/tutorial/home.jinja2 - :language: html +#. We need to include ``pyramid_jinja2`` in ``jinja2/tutorial/__init__.py``: -#. Now run the tests: + .. literalinclude:: jinja2/tutorial/__init__.py + :linenos: - .. code-block:: bash +#. Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``: - $VENV/bin/py.test tutorial/tests.py -q - .... - 4 passed in 0.40 seconds + .. literalinclude:: jinja2/tutorial/views.py + :linenos: -#. Run your Pyramid application with: +#. Add ``jinja2/tutorial/home.jinja2`` as a template: - .. code-block:: bash + .. literalinclude:: jinja2/tutorial/home.jinja2 + :language: html - $VENV/bin/pserve development.ini --reload +#. Now run the tests: -#. Open http://localhost:6543/ in your browser. + .. code-block:: bash + + $VENV/bin/pytest tutorial/tests.py -q + .... + 4 passed in 0.40 seconds + +#. Run your Pyramid application with: + + .. code-block:: bash + + $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. Analysis diff --git a/docs/quick_tutorial/jinja2/setup.py b/docs/quick_tutorial/jinja2/setup.py index a93cf6a73..ea2c59045 100644 --- a/docs/quick_tutorial/jinja2/setup.py +++ b/docs/quick_tutorial/jinja2/setup.py @@ -1,14 +1,32 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_jinja2', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst index 98283424c..44d1de8cb 100644 --- a/docs/quick_tutorial/json.rst +++ b/docs/quick_tutorial/json.rst @@ -54,7 +54,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q ..... 5 passed in 0.47 seconds diff --git a/docs/quick_tutorial/json/setup.py b/docs/quick_tutorial/json/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/json/setup.py +++ b/docs/quick_tutorial/json/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst index ccbb7970f..f4a368bfa 100644 --- a/docs/quick_tutorial/logging.rst +++ b/docs/quick_tutorial/logging.rst @@ -54,7 +54,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .... 4 passed in 0.41 seconds diff --git a/docs/quick_tutorial/logging/setup.py b/docs/quick_tutorial/logging/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/logging/setup.py +++ b/docs/quick_tutorial/logging/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst index 15452e9ae..b7e724dcf 100644 --- a/docs/quick_tutorial/more_view_classes.rst +++ b/docs/quick_tutorial/more_view_classes.rst @@ -53,7 +53,7 @@ Objectives Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the ``templating`` step: .. code-block:: bash @@ -105,7 +105,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .. 2 passed in 0.40 seconds diff --git a/docs/quick_tutorial/more_view_classes/setup.py b/docs/quick_tutorial/more_view_classes/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/more_view_classes/setup.py +++ b/docs/quick_tutorial/more_view_classes/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/package/setup.py b/docs/quick_tutorial/package/setup.py index 77fedee2d..910c552ad 100644 --- a/docs/quick_tutorial/package/setup.py +++ b/docs/quick_tutorial/package/setup.py @@ -1,10 +1,13 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, +setup( + name='tutorial', + install_requires=requires, ) diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst index 098753820..f7753f222 100644 --- a/docs/quick_tutorial/request_response.rst +++ b/docs/quick_tutorial/request_response.rst @@ -61,7 +61,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q ..... 5 passed in 0.30 seconds diff --git a/docs/quick_tutorial/request_response/setup.py b/docs/quick_tutorial/request_response/setup.py index a93cf6a73..e9c068a23 100644 --- a/docs/quick_tutorial/request_response/setup.py +++ b/docs/quick_tutorial/request_response/setup.py @@ -1,14 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', + 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/retail_forms/setup.py b/docs/quick_tutorial/retail_forms/setup.py index 968889e74..dda0a2cc4 100644 --- a/docs/quick_tutorial/retail_forms/setup.py +++ b/docs/quick_tutorial/retail_forms/setup.py @@ -1,5 +1,7 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'deform', 'pyramid', @@ -7,10 +9,12 @@ requires = [ 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +setup( + name='tutorial', + install_requires=requires, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst index 0384892b2..a6538a75f 100644 --- a/docs/quick_tutorial/routing.rst +++ b/docs/quick_tutorial/routing.rst @@ -79,7 +79,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .. 2 passed in 0.39 seconds diff --git a/docs/quick_tutorial/routing/setup.py b/docs/quick_tutorial/routing/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/routing/setup.py +++ b/docs/quick_tutorial/routing/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst index d67a5063a..8a67d6a0f 100644 --- a/docs/quick_tutorial/sessions.rst +++ b/docs/quick_tutorial/sessions.rst @@ -60,7 +60,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .... 4 passed in 0.42 seconds diff --git a/docs/quick_tutorial/sessions/setup.py b/docs/quick_tutorial/sessions/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/sessions/setup.py +++ b/docs/quick_tutorial/sessions/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst index 7a6b5dac3..567328307 100644 --- a/docs/quick_tutorial/static_assets.rst +++ b/docs/quick_tutorial/static_assets.rst @@ -54,7 +54,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .... 5 passed in 0.50 seconds diff --git a/docs/quick_tutorial/static_assets/setup.py b/docs/quick_tutorial/static_assets/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/static_assets/setup.py +++ b/docs/quick_tutorial/static_assets/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst index 3fbef699c..cef54fb6f 100644 --- a/docs/quick_tutorial/templating.rst +++ b/docs/quick_tutorial/templating.rst @@ -42,67 +42,64 @@ Objectives Steps ===== -#. Let's begin by using the previous package as a starting point for a new - project: +#. Let's begin by using the previous package as a starting point for a new project: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r views templating; cd templating + cd ..; cp -r views templating; cd templating -#. This step depends on ``pyramid_chameleon``, so add it as a dependency in - ``templating/setup.py``: +#. This step depends on ``pyramid_chameleon``, so add it as a dependency in ``templating/setup.py``: - .. literalinclude:: templating/setup.py - :linenos: + .. literalinclude:: templating/setup.py + :linenos: + :emphasize-lines: 7 -#. Now we can activate the development-mode distribution: +#. Now we can activate the development-mode distribution: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pip install -e . + $VENV/bin/pip install -e . -#. We need to connect ``pyramid_chameleon`` as a renderer by making a call in - the setup of ``templating/tutorial/__init__.py``: +#. We need to connect ``pyramid_chameleon`` as a renderer by making a call in the setup of ``templating/tutorial/__init__.py``: - .. literalinclude:: templating/tutorial/__init__.py - :linenos: + .. literalinclude:: templating/tutorial/__init__.py + :linenos: -#. Our ``templating/tutorial/views.py`` no longer has HTML in it: +#. Our ``templating/tutorial/views.py`` no longer has HTML in it: - .. literalinclude:: templating/tutorial/views.py - :linenos: + .. literalinclude:: templating/tutorial/views.py + :linenos: -#. Instead we have ``templating/tutorial/home.pt`` as a template: +#. Instead we have ``templating/tutorial/home.pt`` as a template: - .. literalinclude:: templating/tutorial/home.pt - :language: html + .. literalinclude:: templating/tutorial/home.pt + :language: html -#. For convenience, change ``templating/development.ini`` to reload templates - automatically with ``pyramid.reload_templates``: +#. For convenience, change ``templating/development.ini`` to reload templates automatically with ``pyramid.reload_templates``: - .. literalinclude:: templating/development.ini - :language: ini + .. literalinclude:: templating/development.ini + :language: ini -#. Our unit tests in ``templating/tutorial/tests.py`` can focus on data: +#. Our unit tests in ``templating/tutorial/tests.py`` can focus on data: - .. literalinclude:: templating/tutorial/tests.py - :linenos: + .. literalinclude:: templating/tutorial/tests.py + :linenos: -#. Now run the tests: +#. Now run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q - .... - 4 passed in 0.46 seconds + $VENV/bin/pytest tutorial/tests.py -q + .... + 4 passed in 0.46 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. +#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. Analysis diff --git a/docs/quick_tutorial/templating/setup.py b/docs/quick_tutorial/templating/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/templating/setup.py +++ b/docs/quick_tutorial/templating/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst index 7ef28bdb8..a16bce406 100644 --- a/docs/quick_tutorial/tutorial_approach.rst +++ b/docs/quick_tutorial/tutorial_approach.rst @@ -36,11 +36,13 @@ Each of the directories in our ``quick_tutorial`` workspace (e.g., ``request_res project* (except as noted for the ``hello_world`` step). The ``tutorial`` directory is a *Python package*. -For most steps you will copy the previous step's directory to a new directory, and change your working directory to the new directory, then install your project: +For most steps you will copy an earlier step's directory to a new directory, change your working directory to the new directory, then install your project: .. code-block:: bash cd ..; cp -r package ini; cd ini $VENV/bin/pip install -e . -For a few steps, you won't copy the previous step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``. +For a few steps, you won't copy an earlier step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``. + +Finally for a few steps, you might add a dependency to your project in its ``setup.py`` file, and then install both the dependency and the project with either ``$VENV/bin/pip install -e .`` or ``$VENV/bin/pip install -e ".[dev]"``. diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst index 09e3ea197..654925347 100644 --- a/docs/quick_tutorial/unit_testing.rst +++ b/docs/quick_tutorial/unit_testing.rst @@ -43,28 +43,39 @@ Objectives Steps ===== -#. First we copy the results of the previous step, as well as install the - ``pytest`` package: +#. First we copy the results of the previous step. - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r debugtoolbar unit_testing; cd unit_testing - $VENV/bin/pip install -e . - $VENV/bin/pip install pytest + cd ..; cp -r debugtoolbar unit_testing; cd unit_testing -#. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``: +#. Add ``pytest`` to our project's dependencies in ``setup.py`` as a :term:`Setuptools` "extra": - .. literalinclude:: unit_testing/tutorial/tests.py - :linenos: + .. literalinclude:: unit_testing/setup.py + :language: python + :linenos: + :emphasize-lines: 15 -#. Now run the tests: +#. Install our project and its newly added dependency. + Note that we use the extra specifier ``[dev]`` to install testing requirements for development and surround it and the period with double quote marks. - .. code-block:: bash + .. code-block:: bash + $VENV/bin/pip install -e ".[dev]" - $VENV/bin/py.test tutorial/tests.py -q - . - 1 passed in 0.14 seconds +#. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``: + + .. literalinclude:: unit_testing/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $VENV/bin/pytest tutorial/tests.py -q + . + 1 passed in 0.14 seconds Analysis @@ -96,7 +107,7 @@ Extra credit ============ #. Change the test to assert that the response status code should be ``404`` - (meaning, not found). Run ``py.test`` again. Read the error report and see + (meaning, not found). Run ``pytest`` again. Read the error report and see if you can decipher what it is telling you. #. As a more realistic example, put the ``tests.py`` back as you found it, and @@ -114,4 +125,4 @@ Extra credit #. Why do we import the ``hello_world`` view function *inside* the ``test_hello_world`` method instead of at the top of the module? -.. seealso:: See also :ref:`testing_chapter` +.. seealso:: See also :ref:`testing_chapter` and `Setuptools Declaring "Extras" (optional features with their own dependencies) <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_. diff --git a/docs/quick_tutorial/unit_testing/setup.py b/docs/quick_tutorial/unit_testing/setup.py index a93cf6a73..a5f8a250b 100644 --- a/docs/quick_tutorial/unit_testing/setup.py +++ b/docs/quick_tutorial/unit_testing/setup.py @@ -1,14 +1,29 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst index fc7ba5125..1307857b7 100644 --- a/docs/quick_tutorial/view_classes.rst +++ b/docs/quick_tutorial/view_classes.rst @@ -37,41 +37,38 @@ Objectives Steps ===== -#. First we copy the results of the previous step: +#. First we copy the results of the previous step: - .. code-block:: bash + .. code-block:: bash - cd ..; cp -r templating view_classes; cd view_classes - $VENV/bin/pip install -e . + cd ..; cp -r templating view_classes; cd view_classes + $VENV/bin/pip install -e . -#. Our ``view_classes/tutorial/views.py`` now has a view class with our two - views: +#. Our ``view_classes/tutorial/views.py`` now has a view class with our two views: - .. literalinclude:: view_classes/tutorial/views.py - :linenos: + .. literalinclude:: view_classes/tutorial/views.py + :linenos: -#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's - modify them to import the view class, and make an instance before getting a - response: +#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's modify them to import the view class, and make an instance before getting a response: - .. literalinclude:: view_classes/tutorial/tests.py - :linenos: + .. literalinclude:: view_classes/tutorial/tests.py + :linenos: -#. Now run the tests: +#. Now run the tests: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q - .... - 4 passed in 0.34 seconds + $VENV/bin/pytest tutorial/tests.py -q + .... + 4 passed in 0.34 seconds -#. Run your Pyramid application with: +#. Run your Pyramid application with: - .. code-block:: bash + .. code-block:: bash - $VENV/bin/pserve development.ini --reload + $VENV/bin/pserve development.ini --reload -#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. +#. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser. Analysis diff --git a/docs/quick_tutorial/view_classes/setup.py b/docs/quick_tutorial/view_classes/setup.py index 744612371..e9c068a23 100644 --- a/docs/quick_tutorial/view_classes/setup.py +++ b/docs/quick_tutorial/view_classes/setup.py @@ -1,15 +1,31 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'pyramid_chameleon', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, ) diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst index f7fa64719..45bc8518b 100644 --- a/docs/quick_tutorial/views.rst +++ b/docs/quick_tutorial/views.rst @@ -68,7 +68,7 @@ Steps .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py -q + $VENV/bin/pytest tutorial/tests.py -q .... 4 passed in 0.28 seconds diff --git a/docs/quick_tutorial/views/setup.py b/docs/quick_tutorial/views/setup.py index a93cf6a73..a0fa8217c 100644 --- a/docs/quick_tutorial/views/setup.py +++ b/docs/quick_tutorial/views/setup.py @@ -1,14 +1,30 @@ from setuptools import setup +# List of dependencies installed via `pip install -e .` +# by virtue of the Setuptools `install_requires` value below. requires = [ 'pyramid', 'waitress', ] -setup(name='tutorial', - install_requires=requires, - entry_points="""\ - [paste.app_factory] - main = tutorial:main - """, -)
\ No newline at end of file +# List of dependencies installed via `pip install -e ".[dev]"` +# by virtue of the Setuptools `extras_require` value in the Python +# dictionary below. +dev_requires = [ + 'pyramid_debugtoolbar', + 'pytest', + 'webtest', +] + +setup( + name='tutorial', + install_requires=requires, + extras_require={ + 'dev': dev_requires, + }, + entry_points={ + 'paste.app_factory': [ + 'main = tutorial:main' + ], + }, +) 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: diff --git a/docs/typographical-conventions.rst b/docs/typographical-conventions.rst index 76fdf8ace..7f052cbc8 100644 --- a/docs/typographical-conventions.rst +++ b/docs/typographical-conventions.rst @@ -128,7 +128,7 @@ When a command that should be typed on one line is too long to fit on the displa .. code-block:: bash - $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ + $VENV/bin/pytest tutorial/tests.py --cov-report term-missing \ --cov=tutorial -q |