diff options
Diffstat (limited to 'docs/tutorials/wiki/installation.rst')
| -rw-r--r-- | docs/tutorials/wiki/installation.rst | 181 |
1 files changed, 93 insertions, 88 deletions
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index d0037e584..37e3498b2 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -4,12 +4,13 @@ Installation ============ + Before you begin ---------------- -This tutorial assumes that you have already followed the steps in -:ref:`installing_chapter`, except **do not create a virtual environment or -install Pyramid**. Thereby you will satisfy the following requirements. +This tutorial assumes that you have already followed the steps in :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. * You've satisfied the :ref:`requirements-for-installing-packages`. @@ -17,13 +18,17 @@ install Pyramid**. Thereby you will satisfy the following requirements. 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 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. 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 ^^^^^^^ @@ -33,6 +38,7 @@ On Unix cd ~ cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + On Windows ^^^^^^^^^^ @@ -41,30 +47,33 @@ On Windows cd \ cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master + 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 + You've downloaded ~/.cookiecutters/pyramid-cookiecutter-starter before. + Is it okay to delete and re-download 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 + Choose from 1, 2, 3 [1]: 2 Select backend: 1 - none 2 - sqlalchemy 3 - zodb Choose from 1, 2, 3 [1]: 3 + Change directory into your newly created project ------------------------------------------------ + On Unix ^^^^^^^ @@ -72,6 +81,7 @@ On Unix cd tutorial + On Windows ^^^^^^^^^^ @@ -85,6 +95,7 @@ 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 ^^^^^^^ @@ -92,6 +103,7 @@ On Unix export VENV=~/tutorial + On Windows ^^^^^^^^^^ @@ -103,6 +115,7 @@ On Windows Create a virtual environment ---------------------------- + On Unix ^^^^^^^ @@ -110,17 +123,10 @@ On Unix 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:: doscon - - c:\Python27\Scripts\virtualenv %VENV% - Python 3.7: .. code-block:: doscon @@ -131,6 +137,7 @@ Python 3.7: Upgrade packaging tools in the virtual environment -------------------------------------------------- + On Unix ^^^^^^^ @@ -138,6 +145,7 @@ On Unix $VENV/bin/pip install --upgrade pip setuptools + On Windows ^^^^^^^^^^ @@ -151,7 +159,10 @@ On Windows 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. We will install testing requirements at the same time. We do so with the following command. +In order to work on the project, 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 ^^^^^^^ @@ -160,6 +171,7 @@ On Unix $VENV/bin/pip install -e ".[testing]" + On Windows ^^^^^^^^^^ @@ -167,6 +179,7 @@ On Windows %VENV%\Scripts\pip install -e ".[testing]" + On all operating systems ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -174,16 +187,18 @@ The console will show ``pip`` checking for packages and installing missing packa .. code-block:: bash - 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 + Successfully installed BTrees-4.5.1 Chameleon-3.5 Mako-1.0.7 \ + MarkupSafe-1.1.0 PasteDeploy-1.5.2 Pygments-2.2.0 WebTest-2.0.32 \ + ZConfig-3.3.0 ZEO-5.2.0 ZODB-5.5.1 ZODB3-3.11.0 atomicwrites-1.2.1 \ + attrs-18.2.0 beautifulsoup4-4.6.3 coverage-4.5.2 hupper-1.4.1 \ + more-itertools-4.3.0 persistent-4.4.3 plaster-1.0 plaster-pastedeploy-0.6 \ + pluggy-0.8.0 py-1.7.0 pyramid-1.10.1 pyramid-chameleon-0.3 \ + pyramid-debugtoolbar-4.5 pyramid-mako-1.0.2 pyramid-retry-1.0 \ + pyramid-tm-2.2.1 pyramid-zodbconn-0.8.1 pytest-4.0.0 pytest-cov-2.6.0 \ + repoze.lru-0.7 six-1.11.0 transaction-2.4.0 translationstring-1.3 \ + tutorial venusian-1.1.0 waitress-1.1.0 webob-1.8.4 zc.lockfile-1.4 \ + zdaemon-4.3 zodbpickle-1.0.2 zodburi-2.3.0 zope.deprecation-4.3.0 \ + zope.interface-4.6.0 Testing requirements are defined in our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas. @@ -208,6 +223,7 @@ 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 ^^^^^^^ @@ -215,6 +231,7 @@ On Unix $VENV/bin/pytest -q + On Windows ^^^^^^^^^^ @@ -233,13 +250,11 @@ For a successful test run, you should see output that ends like this: Expose test coverage information -------------------------------- -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. +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. -We've already installed the ``pytest-cov`` package into our virtual -environment, so we can run the tests with coverage. On Unix ^^^^^^^ @@ -248,6 +263,7 @@ On Unix $VENV/bin/pytest --cov --cov-report=term-missing + On Windows ^^^^^^^^^^ @@ -259,23 +275,30 @@ If successful, you will see output something like this: .. code-block:: bash - ======================== 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 + ======================== test session starts ========================= + platform darwin -- Python 3.7.0, pytest-4.0.0, py-1.7.0, pluggy-0.8.0 + rootdir: /Users/stevepiercy/projects/hack-on-pyramid/tutorial, inifile: pytest.ini + plugins: cov-2.6.0 + collected 1 item 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% + [100%] + + ---------- coverage: platform darwin, python 3.7.0-final-0 ----------- + Name Stmts Miss Cover Missing + ----------------------------------------------------------- + tutorial/__init__.py 17 12 29% 7-8, 14-23 + tutorial/models/__init__.py 8 4 50% 9-12 + tutorial/pshell.py 6 6 0% 1-12 + tutorial/routes.py 2 2 0% 1-2 + tutorial/views/__init__.py 0 0 100% + tutorial/views/default.py 4 0 100% + tutorial/views/notfound.py 4 4 0% 1-7 + ----------------------------------------------------------- + TOTAL 41 28 32% + - ===================== 1 passed in 0.31 seconds ====================== + ===================== 1 passed in 0.31 seconds ======================= Our package doesn't quite have 100% test coverage. @@ -285,11 +308,10 @@ Our package doesn't quite have 100% test coverage. 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. +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 ^^^^^^^ @@ -305,13 +327,11 @@ On Windows %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. +``pytest`` follows :ref:`conventions for Python test discovery <pytest:test discovery>`. +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: @@ -319,8 +339,9 @@ coverage. Start the application --------------------- -Start the application. See :ref:`what_is_this_pserve_thing` for more -information on ``pserve``. +Start the application. +See :ref:`what_is_this_pserve_thing` for more information on ``pserve``. + On Unix ^^^^^^^ @@ -329,6 +350,7 @@ On Unix $VENV/bin/pserve development.ini --reload + On Windows ^^^^^^^^^^ @@ -336,10 +358,10 @@ On Windows %VENV%\Scripts\pserve development.ini --reload + .. note:: - Your OS firewall, if any, may pop up a dialog asking for authorization - to allow python to accept incoming network connections. + Your OS firewall, if any, may pop up a dialog asking for authorization to allow python to accept incoming network connections. If successful, you will see something like this on your console: @@ -356,13 +378,12 @@ This means the server is ready to accept requests. Visit the application in a browser ---------------------------------- -In a browser, visit http://localhost:6543/. You will see the generated -application's default page. +In a browser, visit http://localhost:6543/. +You will see the generated application's default page. -One thing you'll notice is the "debug toolbar" icon on right hand side of the -page. You can read more about the purpose of the icon at -:ref:`debug_toolbar`. It allows you to get information about your -application while you develop. +One thing you'll notice is the "debug toolbar" icon on right hand side of the page. +You can read more about the purpose of the icon at :ref:`debug_toolbar`. +It allows you to get information about your application while you develop. Decisions the cookiecutter backend option ``zodb`` has made for you @@ -371,27 +392,11 @@ Decisions the cookiecutter backend option ``zodb`` has made for you 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 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`. +- You want to use `pyramid_zodbconn <https://docs.pylonsproject.org/projects/pyramid-zodbconn/en/latest/>`_, `pyramid_tm <https://docs.pylonsproject.org/projects/pyramid-tm/en/latest/>`_, and the `transaction <https://zodb.readthedocs.io/en/latest/transactions.html>`_ packages to manage connections and transactions with :term:`ZODB`. .. note:: - :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 + :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 will only use :term:`traversal` and :term:`ZODB`. |