| | |
| | | Generate a Pyramid project from a cookiecutter |
| | | ---------------------------------------------- |
| | | |
| | | We will create a Pyramid project in your home directory for UNIX or at the root for Windows. It is assumed you know the path to where you installed ``cookiecutter``. Issue the following commands and override the defaults in the prompts as follows. |
| | | We will create a Pyramid project in your home directory for Unix or at the root for Windows. It is assumed you know the path to where you installed ``cookiecutter``. Issue the following commands and override the defaults in the prompts as follows. |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ cd ~ |
| | | $ cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout master |
| | | cd ~ |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\> cd \ |
| | | c:\> cookiecutter gh:Pylons/pyramid-cookiecutter-zodb --checkout master |
| | | cd \ |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | On all operating systems |
| | | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| | |
| | | |
| | | .. 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 |
| | | ------------------------------------------------ |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ cd tutorial |
| | | cd tutorial |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\> cd tutorial |
| | | cd tutorial |
| | | |
| | | |
| | | Set and use a ``VENV`` environment variable |
| | |
| | | |
| | | We will set the ``VENV`` environment variable to the absolute path of the virtual environment, and use it going forward. |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ export VENV=~/tutorial |
| | | export VENV=~/tutorial |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> set VENV=c:\tutorial |
| | | set VENV=c:\tutorial |
| | | |
| | | |
| | | Create a virtual environment |
| | | ---------------------------- |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ python3 -m venv $VENV |
| | | python3 -m venv $VENV |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> c:\Python27\Scripts\virtualenv %VENV% |
| | | c:\Python27\Scripts\virtualenv %VENV% |
| | | |
| | | Python 3.6: |
| | | Python 3.7: |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> python -m venv %VENV% |
| | | python -m venv %VENV% |
| | | |
| | | |
| | | Upgrade packaging tools in the virtual environment |
| | | -------------------------------------------------- |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install --upgrade pip setuptools |
| | | $VENV/bin/pip install --upgrade pip setuptools |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> %VENV%\Scripts\pip install --upgrade pip setuptools |
| | | %VENV%\Scripts\pip install --upgrade pip setuptools |
| | | |
| | | |
| | | .. _installing_project_in_dev_mode_zodb: |
| | |
| | | |
| | | In order to do development on the project easily, you must "register" the project as a development egg in your workspace. We will install testing requirements at the same time. We do so with the following command. |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install -e ".[testing]" |
| | | $VENV/bin/pip install -e ".[testing]" |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> %VENV%\Scripts\pip install -e ".[testing]" |
| | | %VENV%\Scripts\pip install -e ".[testing]" |
| | | |
| | | On all operating systems |
| | | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| | |
| | | |
| | | 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 |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/py.test -q |
| | | $VENV/bin/pytest -q |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> %VENV%\Scripts\py.test -q |
| | | %VENV%\Scripts\pytest -q |
| | | |
| | | For a successful test run, you should see output that ends like this: |
| | | |
| | | .. code-block:: bash |
| | | |
| | | . |
| | | 1 passed in 0.24 seconds |
| | | . |
| | | 1 passed in 0.24 seconds |
| | | |
| | | |
| | | 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. |
| | | |
| | | We've already installed the ``pytest-cov`` package into our virtual |
| | | environment, so we can run the tests with coverage. |
| | | |
| | | On UNIX |
| | | 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 |
| | | %VENV%\Scripts\pytest --cov --cov-report=term-missing |
| | | |
| | | If successful, you will see output something like this: |
| | | |
| | |
| | | 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 |
| | | 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 |
| | | |
| | | c:\tutorial> %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: |
| | |
| | | Start the application. See :ref:`what_is_this_pserve_thing` for more |
| | | information on ``pserve``. |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pserve development.ini --reload |
| | | $VENV/bin/pserve development.ini --reload |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | c:\tutorial> %VENV%\Scripts\pserve development.ini --reload |
| | | %VENV%\Scripts\pserve development.ini --reload |
| | | |
| | | .. note:: |
| | | |
| | |
| | | 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. |
| | | |
| | |
| | | |
| | | - 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:: |
| | | |