| | |
| | | ---------------- |
| | | |
| | | This tutorial assumes that you have already followed the steps in |
| | | :ref:`installing_chapter`, except **do not create a virtualenv or install |
| | | Pyramid**. Thereby you will satisfy the following requirements. |
| | | :ref:`installing_chapter`, except **do not create a virtual environment or |
| | | install Pyramid**. Thereby you will satisfy the following requirements. |
| | | |
| | | * A Python interpreter is installed on your operating system. |
| | | * :term:`virtualenv` is installed. |
| | | * :term:`pip` will be installed when we create a virtual environment. |
| | | * You've satisfied the :ref:`requirements-for-installing-packages`. |
| | | |
| | | |
| | | Create directory to contain the project |
| | | --------------------------------------- |
| | | Install cookiecutter |
| | | -------------------- |
| | | We will use a :term:`cookiecutter` to create a Python package project from a Python package project template. See `Cookiecutter Installation <https://cookiecutter.readthedocs.io/en/latest/installation.html>`_ for instructions. |
| | | |
| | | We need a workspace for our project files. |
| | | |
| | | On UNIX |
| | | 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. |
| | | |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ mkdir ~/pyramidtut |
| | | cd ~ |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\> mkdir pyramidtut |
| | | cd \ |
| | | cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | On all operating systems |
| | | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| | | If prompted for the first item, accept the default ``yes`` by hitting return. |
| | | |
| | | .. code-block:: text |
| | | |
| | | 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 |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | cd tutorial |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | cd tutorial |
| | | |
| | | |
| | | Create and use a virtual Python environment |
| | | Set and use a ``VENV`` environment variable |
| | | ------------------------------------------- |
| | | |
| | | Next let's create a ``virtualenv`` workspace for our project. We will use the |
| | | ``VENV`` environment variable instead of the absolute path of the virtual |
| | | environment. |
| | | 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=~/pyramidtut |
| | | $ virtualenv $VENV |
| | | export VENV=~/tutorial |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\> set VENV=c:\pyramidtut |
| | | set VENV=c:\tutorial |
| | | |
| | | Each version of Python uses different paths, so you will need to adjust the |
| | | path to the command for your Python version. |
| | | |
| | | Create a virtual environment |
| | | ---------------------------- |
| | | |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | python3 -m venv $VENV |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | Each version of Python uses different paths, so you might need to adjust the path to the command for your Python version. Recent versions of the Python 3 installer for Windows now install a Python launcher. |
| | | |
| | | Python 2.7: |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\> c:\Python27\Scripts\virtualenv %VENV% |
| | | c:\Python27\Scripts\virtualenv %VENV% |
| | | |
| | | Python 3.5: |
| | | Python 3.7: |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\> c:\Python35\Scripts\virtualenv %VENV% |
| | | python -m venv %VENV% |
| | | |
| | | |
| | | Upgrade ``pip`` in the virtual environment |
| | | ------------------------------------------ |
| | | Upgrade packaging tools in the virtual environment |
| | | -------------------------------------------------- |
| | | |
| | | On UNIX |
| | | On Unix |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install --upgrade pip |
| | | $VENV/bin/pip install --upgrade pip setuptools |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\> %VENV%\Scripts\pip install --upgrade pip |
| | | |
| | | |
| | | Install Pyramid into the virtual Python environment |
| | | --------------------------------------------------- |
| | | |
| | | On UNIX |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install pyramid |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | |
| | | c:\> %VENV%\Scripts\pip install pyramid |
| | | |
| | | Change directory to your virtual Python environment |
| | | --------------------------------------------------- |
| | | |
| | | Change directory to the ``pyramidtut`` directory, which is both your workspace |
| | | and your virtual environment. |
| | | |
| | | On UNIX |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ cd pyramidtut |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | |
| | | c:\> cd pyramidtut |
| | | |
| | | .. _making_a_project: |
| | | |
| | | Making a project |
| | | ---------------- |
| | | |
| | | Your next step is to create a project. For this tutorial, we will use |
| | | the :term:`scaffold` named ``zodb``, which generates an application |
| | | that uses :term:`ZODB` and :term:`traversal`. |
| | | |
| | | :app:`Pyramid` supplies a variety of scaffolds to generate sample projects. We |
| | | will use ``pcreate``, a script that comes with Pyramid, to create our project |
| | | using a scaffold. |
| | | |
| | | By passing ``zodb`` into the ``pcreate`` command, the script creates the files |
| | | needed to use ZODB. By passing in our application name ``tutorial``, the script |
| | | inserts that application name into all the required files. |
| | | |
| | | The below instructions assume your current working directory is "pyramidtut". |
| | | |
| | | On UNIX |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pcreate -s zodb tutorial |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | |
| | | c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial |
| | | |
| | | .. note:: If you are using Windows, the ``zodb`` scaffold may not deal |
| | | gracefully with installation into a location that contains spaces in the |
| | | path. If you experience startup problems, try putting both the virtualenv |
| | | and the project into directories that do not contain spaces in their paths. |
| | | %VENV%\Scripts\pip install --upgrade pip setuptools |
| | | |
| | | |
| | | .. _installing_project_in_dev_mode_zodb: |
| | |
| | | Installing the project in development mode |
| | | ------------------------------------------ |
| | | |
| | | In order to do development on the project easily, you must "register" the |
| | | project as a development egg in your workspace using the ``pip install -e .`` |
| | | command. In order to do so, change directory to the ``tutorial`` directory that |
| | | you created in :ref:`making_a_project`, and run the ``pip install -e .`` |
| | | command using the virtualenv Python interpreter. |
| | | 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 |
| | | |
| | | $ cd tutorial |
| | | $ $VENV/bin/pip install -e . |
| | | $VENV/bin/pip install -e ".[testing]" |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\pyramidtut> cd tutorial |
| | | c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e . |
| | | %VENV%\Scripts\pip install -e ".[testing]" |
| | | |
| | | The console will show ``pip`` checking for packages and installing missing |
| | | packages. Success executing this command will show a line like the following: |
| | | On all operating systems |
| | | ^^^^^^^^^^^^^^^^^^^^^^^^ |
| | | |
| | | The console will show ``pip`` checking for packages and installing missing packages. Success executing this command will show a line like the following: |
| | | |
| | | .. code-block:: bash |
| | | |
| | | Successfully installed BTrees-4.2.0 Chameleon-2.24 Mako-1.0.4 \ |
| | | MarkupSafe-0.23 Pygments-2.1.3 ZConfig-3.1.0 ZEO-4.2.0b1 ZODB-4.2.0 \ |
| | | ZODB3-3.11.0 mock-2.0.0 pbr-1.8.1 persistent-4.1.1 pyramid-chameleon-0.3 \ |
| | | pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \ |
| | | pyramid-zodbconn-0.7 six-1.10.0 transaction-1.4.4 tutorial waitress-0.8.10 \ |
| | | zc.lockfile-1.1.0 zdaemon-4.1.0 zodbpickle-0.6.0 zodburi-2.0 |
| | | Successfully installed BTrees-4.3.1 Chameleon-3.0 Mako-1.0.6 \ |
| | | MarkupSafe-0.23 PasteDeploy-1.5.2 Pygments-2.1.3 WebOb-1.6.3 \ |
| | | WebTest-2.0.23 ZConfig-3.1.0 ZEO-5.0.4 ZODB-5.1.1 ZODB3-3.11.0 \ |
| | | beautifulsoup4-4.5.1 coverage-4.2 mock-2.0.0 pbr-1.10.0 persistent-4.2.2 \ |
| | | py-1.4.31 pyramid-1.7.3 pyramid-chameleon-0.3 pyramid-debugtoolbar-3.0.5 \ |
| | | pyramid-mako-1.0.2 pyramid-tm-1.1.1 pyramid-zodbconn-0.7 pytest-3.0.5 \ |
| | | pytest-cov-2.4.0 repoze.lru-0.6 six-1.10.0 transaction-2.0.3 \ |
| | | translationstring-1.3 tutorial venusian-1.0 waitress-1.0.1 \ |
| | | zc.lockfile-1.2.1 zdaemon-4.2.0 zodbpickle-0.6.0 zodburi-2.0 \ |
| | | zope.deprecation-4.2.0 zope.interface-4.3.3 |
| | | |
| | | |
| | | .. _install-testing-requirements_zodb: |
| | | |
| | | Install testing requirements |
| | | ---------------------------- |
| | | |
| | | In order to run tests, we need to install the testing requirements. This is |
| | | done through our project's ``setup.py`` file, in the ``testing_extras`` and |
| | | ``extras_requires`` stanzas, and by issuing the command below for your |
| | | operating system. |
| | | Testing requirements are defined in our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas. |
| | | |
| | | .. literalinclude:: src/installation/setup.py |
| | | :language: python |
| | | :linenos: |
| | | :lineno-start: 22 |
| | | :lines: 22-26 |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 24-28 |
| | | |
| | | .. literalinclude:: src/installation/setup.py |
| | | :language: python |
| | | :linenos: |
| | | :lineno-start: 45 |
| | | :lines: 45-47 |
| | | |
| | | On UNIX |
| | | ^^^^^^^ |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install -e ".[testing]" |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | |
| | | c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]" |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 48-50 |
| | | |
| | | |
| | | .. _running_tests: |
| | |
| | | ------------- |
| | | |
| | | After you've installed the project in development mode as well as the testing |
| | | requirements, you may run the tests for the project. |
| | | requirements, you may run the tests for the project. The following commands |
| | | 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 tutorial/tests.py -q |
| | | $VENV/bin/pytest -q |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -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 |
| | | "coverage" information, exposing which lines of your project are covered by the |
| | | 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 ``virtualenv``, so |
| | | we can run the tests with coverage. |
| | | 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=tutorial --cov-report=term-missing tutorial/tests.py |
| | | $VENV/bin/pytest --cov --cov-report=term-missing |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \ |
| | | --cov-report=term-missing tutorial\tests.py |
| | | %VENV%\Scripts\pytest --cov --cov-report=term-missing |
| | | |
| | | If successful, you will see output something like this: |
| | | |
| | | .. code-block:: bash |
| | | |
| | | ======================== test session starts ======================== |
| | | platform Python 3.5.1, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 |
| | | rootdir: /Users/stevepiercy/projects/pyramidtut/tutorial, inifile: |
| | | plugins: cov-2.2.1 |
| | | collected 1 items |
| | | ======================== test session starts ======================== |
| | | platform Python 3.6.0, pytest-3.0.5, py-1.4.31, pluggy-0.4.0 |
| | | rootdir: /Users/stevepiercy/tutorial, inifile: |
| | | plugins: cov-2.4.0 |
| | | collected 1 items |
| | | |
| | | tutorial/tests.py . |
| | | ------------------ coverage: platform Python 3.5.1 ------------------ |
| | | Name Stmts Miss Cover Missing |
| | | ---------------------------------------------------- |
| | | tutorial/__init__.py 12 7 42% 7-8, 14-18 |
| | | tutorial/models.py 10 6 40% 9-14 |
| | | tutorial/tests.py 12 0 100% |
| | | tutorial/views.py 4 0 100% |
| | | ---------------------------------------------------- |
| | | TOTAL 38 13 66% |
| | | tutorial/tests.py . |
| | | ------------------ coverage: platform Python 3.6.0 ------------------ |
| | | Name Stmts Miss Cover Missing |
| | | ------------------------------------------------------- |
| | | tutorial/__init__.py 14 9 36% 7-8, 14-20 |
| | | tutorial/models.py 10 6 40% 9-14 |
| | | tutorial/views.py 4 0 100% |
| | | ------------------------------------------------------- |
| | | TOTAL 28 15 46% |
| | | |
| | | ===================== 1 passed in 0.31 seconds ====================== |
| | | ===================== 1 passed in 0.31 seconds ====================== |
| | | |
| | | Our package doesn't quite have 100% test coverage. |
| | | |
| | | |
| | | .. _test_and_coverage_cookiecutter_defaults_zodb: |
| | | |
| | | Test and coverage cookiecutter defaults |
| | | --------------------------------------- |
| | | |
| | | 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/pytest --cov=tutorial tutorial/tests.py -q |
| | | |
| | | On Windows |
| | | ^^^^^^^^^^ |
| | | |
| | | .. code-block:: doscon |
| | | |
| | | %VENV%\Scripts\pytest --cov=tutorial tutorial\tests.py -q |
| | | |
| | | ``pytest`` follows :ref:`conventions for Python test discovery |
| | | <pytest:test discovery>`, and the configuration defaults from the cookiecutter |
| | | tell ``pytest`` where to find the module on which we want to run tests and |
| | | coverage. |
| | | |
| | | .. 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 |
| | | --------------------- |
| | | |
| | | 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:: ps1con |
| | | .. code-block:: doscon |
| | | |
| | | c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload |
| | | %VENV%\Scripts\pserve development.ini --reload |
| | | |
| | | .. note:: |
| | | |
| | |
| | | .. code-block:: text |
| | | |
| | | Starting subprocess with file monitor |
| | | Starting server in PID 95736. |
| | | serving on http://127.0.0.1:6543 |
| | | Starting server in PID 44078. |
| | | Serving on http://localhost:6543 |
| | | Serving on http://localhost:6543 |
| | | |
| | | This means the server is ready to accept requests. |
| | | |
| | |
| | | application while you develop. |
| | | |
| | | |
| | | Decisions the ``zodb`` scaffold has made for you |
| | | ------------------------------------------------ |
| | | Decisions the cookiecutter backend option ``zodb`` has made for you |
| | | ------------------------------------------------------------------- |
| | | |
| | | Creating a project using the ``zodb`` scaffold 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` as persistent storage. |
| | | - You are willing to use :term:`ZODB` for persistent storage. |
| | | |
| | | - You are willing to use :term:`traversal` to map URLs to code. |
| | | |
| | | - You want to use pyramid_zodbconn_, pyramid_tm_, and the transaction_ packages |
| | | to manage connections and transactions with :term:`ZODB`. |
| | | |
| | | .. note:: |
| | | |
| | | :app:`Pyramid` supports any persistent storage mechanism (e.g., a SQL |
| | | database or filesystem files). It also supports an additional |
| | | mechanism to map URLs to code (:term:`URL dispatch`). However, for the |
| | | purposes of this tutorial, we'll only be using traversal and ZODB. |
| | | :app:`Pyramid` supports any persistent storage mechanism (e.g., an SQL |
| | | database or filesystem files). It also supports an additional mechanism to |
| | | map URLs to code (:term:`URL dispatch`). However, for the purposes of this |
| | | tutorial, we'll only be using :term:`traversal` and :term:`ZODB`. |
| | | |
| | | .. _pyramid_chameleon: |
| | | https://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/ |
| | | |
| | | .. _pyramid_tm: |
| | | https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/ |
| | | |
| | | .. _pyramid_zodbconn: |
| | | https://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/ |
| | | |
| | | .. _transaction: |
| | | https://zodb.readthedocs.io/en/latest/transactions.html |