| | |
| | | |
| | | 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:: |
| | | |
| | |
| | | .. 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 persistence mechanism they offer (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) |
| | | |
| | | - the mechanism they use to map URLs to code (:term:`URL dispatch` or :term:`traversal`) |
| | | The Pyramid cookiecutter released under the Pylons Project offers the following configuration options: |
| | | |
| | | - templating libraries (:term:`Jinja2`, :term:`Chameleon`, or :term:`Mako`) |
| | | |
| | | - the persistence mechanism (no persistence mechanism, :term:`SQLAlchemy` with SQLite, or :term:`ZODB`) |
| | | |
| | | - 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. |
| | | |
| | | ``pyramid-cookiecutter-starter`` |
| | | :term:`URL dispatch` for routing and either :term:`Jinja2`, :term:`Chameleon`, or :term:`Mako` for templating |
| | | The configuration of mapping URLs to code (routing) depends on the backend option selected, with additional variations as follows. |
| | | |
| | | ``pyramid-cookiecutter-alchemy`` |
| | | SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Jinja2` for templating. |
| | | ``none`` |
| | | :term:`URL dispatch` for routing |
| | | |
| | | ``pyramid-cookiecutter-zodb`` |
| | | :term:`ZODB` for persistent storage, :term:`traversal` for routing, and :term:`Chameleon` for templating |
| | | ``sqlalchemy`` |
| | | SQLite for persistent storage, :term:`SQLAlchemy` for an ORM, :term:`URL dispatch` for routing, and :term:`Alembic` for database migrations |
| | | |
| | | ``zodb`` |
| | | :term:`ZODB` for persistent storage and :term:`traversal` for routing |
| | | |
| | | |
| | | .. index:: |
| | |
| | | |
| | | 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``. |
| | | |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | If prompted for the first item, accept the default ``yes`` by hitting return. |
| | | |
| | |
| | | 1 - jinja2 |
| | | 2 - chameleon |
| | | 3 - mako |
| | | Choose from 1, 2, 3 [1]: 1 |
| | | Select backend: |
| | | 1 - none |
| | | 2 - sqlalchemy |
| | | 3 - zodb |
| | | Choose from 1, 2, 3 [1]: 1 |
| | | |
| | | We then run through the following commands. |
| | |
| | | %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 |
| | | |
| | |
| | | |
| | | .. 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:: |
| | |
| | | #. ``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 |
| | |
| | | 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. |
| | |
| | | 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:: |
| | |
| | | ``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. |
| | | |
| | |
| | | :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`` |
| | |
| | | |
| | | #. 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. |
| | |
| | | |
| | | 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. |
| | |
| | | :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. |