From 93a7a14d0abf0a7c1659275dc78ebc15247ca893 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 15:17:52 -0700 Subject: - fix traversal tutorial reference - add intersphinx targets to wiki/* --- docs/tutorials/wiki/installation.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index ff5cac4c9..7861aeeb7 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -1,3 +1,5 @@ +.. _wiki_installation: + ============ Installation ============ -- cgit v1.2.3 From c602245786b829726b55dc5454649834af28d0d1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 16:19:47 -0700 Subject: - update wiki/installation step to use pip - make it consistent with wiki2 --- docs/tutorials/wiki/installation.rst | 303 ++++++++++++++++++++++------------- 1 file changed, 188 insertions(+), 115 deletions(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 7861aeeb7..f7025446b 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -5,15 +5,16 @@ Installation ============ Before you begin -================ +---------------- 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. -* Python interpreter is installed on your operating system -* :term:`setuptools` or :term:`distribute` is installed -* :term:`virtualenv` is installed +* A Python interpreter is installed on your operating system. +* :term:`virtualenv` is installed. +* :term:`pip` will be installed when we create a virtual environment. + Create directory to contain the project --------------------------------------- @@ -23,257 +24,327 @@ We need a workspace for our project files. On UNIX ^^^^^^^ -.. code-block:: text +.. code-block:: bash $ mkdir ~/pyramidtut On Windows ^^^^^^^^^^ -.. code-block:: text +.. code-block:: ps1con c:\> mkdir pyramidtut + Create and use a virtual Python environment ------------------------------------------- -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. +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. On UNIX ^^^^^^^ -.. code-block:: text +.. code-block:: bash $ export VENV=~/pyramidtut $ virtualenv $VENV - New python executable in /home/foo/env/bin/python - Installing setuptools.............done. On Windows ^^^^^^^^^^ -.. code-block:: text +.. code-block:: ps1con c:\> set VENV=c:\pyramidtut -Versions of Python use different paths, so you will need to adjust the +Each version of Python uses different paths, so you will need to adjust the path to the command for your Python version. Python 2.7: -.. code-block:: text +.. code-block:: ps1con c:\> c:\Python27\Scripts\virtualenv %VENV% -Python 3.3: +Python 3.5: -.. code-block:: text +.. code-block:: ps1con - c:\> c:\Python33\Scripts\virtualenv %VENV% + c:\> c:\Python35\Scripts\virtualenv %VENV% -Install Pyramid and tutorial dependencies into the virtual Python environment ------------------------------------------------------------------------------ + +Upgrade ``pip`` in the virtual environment +------------------------------------------ On UNIX ^^^^^^^ -.. code-block:: text +.. code-block:: bash - $ $VENV/bin/easy_install docutils pyramid_tm pyramid_zodbconn \ - pyramid_debugtoolbar nose coverage + $ $VENV/bin/pip install --upgrade pip On Windows ^^^^^^^^^^ -.. code-block:: text +.. code-block:: ps1con + + c:\> %VENV%\Scripts\pip install --upgrade pip - c:\> %VENV%\Scripts\easy_install docutils pyramid_tm pyramid_zodbconn \ - pyramid_debugtoolbar nose coverage -Change Directory to Your Virtual Python Environment +Install Pyramid into the virtual Python environment --------------------------------------------------- -Change directory to the ``pyramidtut`` directory. +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:: text +.. code-block:: bash $ cd pyramidtut On Windows ^^^^^^^^^^ -.. code-block:: text +.. 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 -quickly and easily generate scaffolds, usually with a single command—to -create the scaffold for our project. +: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. +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:: text +.. code-block:: bash $ $VENV/bin/pcreate -s zodb tutorial On Windows ----------- +^^^^^^^^^^ -.. code-block:: text +.. 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. +.. 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. + .. _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 -``setup.py develop`` command. In order to do so, cd to the `tutorial` -directory you created in :ref:`making_a_project`, and run the -``setup.py develop`` 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 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. On UNIX -------- +^^^^^^^ -.. code-block:: text +.. code-block:: bash $ cd tutorial - $ $VENV/bin/python setup.py develop + $ $VENV/bin/pip install -e . On Windows ----------- +^^^^^^^^^^ -.. code-block:: text +.. code-block:: ps1con c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e . + +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 + + +.. _install-testing-requirements_zodb: + +Install testing requirements +---------------------------- -The console will show `setup.py` checking for packages and installing -missing packages. Success executing this command will show a line like -the following:: +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. + +.. literalinclude:: src/installation/setup.py + :language: python + :linenos: + :lineno-start: 22 + :lines: 22-26 + +.. 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]" - Finished processing dependencies for tutorial==0.0 .. _running_tests: Run the tests -============= +------------- -After you've installed the project in development mode, you may run -the tests for the project. +After you've installed the project in development mode as well as the testing +requirements, you may run the tests for the project. On UNIX -------- +^^^^^^^ -.. code-block:: text +.. code-block:: bash - $ $VENV/bin/python setup.py test -q + $ $VENV/bin/py.test tutorial/tests.py -q On Windows ----------- +^^^^^^^^^^ + +.. code-block:: ps1con -.. code-block:: text + c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q - c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q +For a successful test run, you should see output that ends like this: -For a successful test run, you should see output that ends like this:: +.. code-block:: bash + + . + 1 passed in 0.24 seconds - . - ---------------------------------------------------------------------- - Ran 1 test in 0.094s - - OK Expose test coverage information -================================ +-------------------------------- -You can run the ``nosetests`` command to see test coverage -information. This runs the tests in the same way that ``setup.py -test`` does but provides additional "coverage" information, exposing -which lines of your project are "covered" (or not covered) by the +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 tests. +We've already installed the ``pytest-cov`` package into our ``virtualenv``, so +we can run the tests with coverage. + On UNIX -------- +^^^^^^^ -.. code-block:: text +.. code-block:: bash - $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py On Windows ----------- +^^^^^^^^^^ + +.. code-block:: ps1con -.. code-block:: text + c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \ + --cov-report=term-missing tutorial\tests.py - c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ - --cover-erase --with-coverage +If successful, you will see output something like this: -If successful, you will see output something like this:: +.. code-block:: bash - . - Name Stmts Miss Cover Missing - -------------------------------------------------- - tutorial.py 12 7 42% 7-8, 14-18 - tutorial/models.py 10 6 40% 9-14 - tutorial/views.py 4 0 100% - -------------------------------------------------- - TOTAL 26 13 50% - ---------------------------------------------------------------------- - Ran 1 test in 0.392s + ======================== 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 - OK + 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% + + ===================== 1 passed in 0.31 seconds ====================== + +Our package doesn't quite have 100% test coverage. -Looks like our package doesn't quite have 100% test coverage. .. _wiki-start-the-application: Start the application -===================== +--------------------- Start the application. On UNIX -------- +^^^^^^^ -.. code-block:: text +.. code-block:: bash $ $VENV/bin/pserve development.ini --reload On Windows ----------- +^^^^^^^^^^ -.. code-block:: text +.. code-block:: ps1con c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload @@ -290,26 +361,28 @@ If successful, you will see something like this on your console:: 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. + Decisions the ``zodb`` scaffold has made for you -================================================ +------------------------------------------------ Creating a project using the ``zodb`` scaffold makes the following assumptions: -- you are willing to use :term:`ZODB` as persistent storage +- You are willing to use :term:`ZODB` as persistent storage. -- you are willing to use :term:`traversal` to map URLs to code +- You are willing to use :term:`traversal` to map URLs to code. .. note:: -- cgit v1.2.3 From edc20e327b2ca2ee28d936bf43a5a6e3dc373e89 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 9 Apr 2016 17:53:23 -0700 Subject: - fix console message --- docs/tutorials/wiki/installation.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index f7025446b..721ead466 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -353,11 +353,13 @@ On Windows 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:: +If successful, you will see something like this on your console: + +.. code-block:: text Starting subprocess with file monitor Starting server in PID 95736. - serving on http://0.0.0.0:6543 + serving on http://127.0.0.1:6543 This means the server is ready to accept requests. -- cgit v1.2.3 From da6244086a88ccc8db42a48d59e33ed6c94d2e9f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 11 Apr 2016 03:15:35 -0700 Subject: - upgrade setuptools, too, in the two wikis --- docs/tutorials/wiki/installation.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 721ead466..0d006418b 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -74,22 +74,22 @@ Python 3.5: c:\> c:\Python35\Scripts\virtualenv %VENV% -Upgrade ``pip`` in the virtual environment ------------------------------------------- +Upgrade ``pip`` and ``setuptools`` in the virtual environment +------------------------------------------------------------- On UNIX ^^^^^^^ .. code-block:: bash - $ $VENV/bin/pip install --upgrade pip + $ $VENV/bin/pip install --upgrade pip setuptools On Windows ^^^^^^^^^^ .. code-block:: ps1con - c:\> %VENV%\Scripts\pip install --upgrade pip + c:\> %VENV%\Scripts\pip install --upgrade pip setuptools Install Pyramid into the virtual Python environment -- cgit v1.2.3 From db13c844714121e2e6e37382dfd8dbe3716a3bfc Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 11 Apr 2016 21:36:41 -0500 Subject: fix extras_requires to extras_require --- docs/tutorials/wiki/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 0d006418b..2064d3cc8 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -215,7 +215,7 @@ 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 +``extras_require`` stanzas, and by issuing the command below for your operating system. .. literalinclude:: src/installation/setup.py -- cgit v1.2.3 From ebbe68144ad6a6022863aa4a29f5611fde02258f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 04:52:20 -0700 Subject: - use an environment variable and venv. See https://github.com/Pylons/pyramid/pull/2468#discussion_r59311019 - rename stanza from `testing_extras` to `tests_require` - switch from nose to pytest --- docs/tutorials/wiki/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 2064d3cc8..6dd35794f 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -214,7 +214,7 @@ 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 +done through our project's ``setup.py`` file, in the ``tests_require`` and ``extras_require`` stanzas, and by issuing the command below for your operating system. -- cgit v1.2.3 From f573cd2f2986b04d57cc041753e97509fe525e95 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 06:07:31 -0700 Subject: one does not simply "create a virtualenv". one should "create a virtual environment" --- docs/tutorials/wiki/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index 6dd35794f..c50faa2e3 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -8,8 +8,8 @@ Before you begin ---------------- 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. -- cgit v1.2.3 From d67566acebf890a603fad0e9069d5e131dfb5b31 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 06:43:38 -0700 Subject: one does not simply "create a virtualenv". one should "create a virtual environment". - Fixes #2483 --- docs/tutorials/wiki/installation.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'docs/tutorials/wiki/installation.rst') diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst index c50faa2e3..b1b89d117 100644 --- a/docs/tutorials/wiki/installation.rst +++ b/docs/tutorials/wiki/installation.rst @@ -12,8 +12,7 @@ This tutorial assumes that you have already followed the steps in 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 @@ -39,8 +38,8 @@ On Windows Create and use a virtual Python environment ------------------------------------------- -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 +Next let's create a virtual environment workspace for our project. We will use +the ``VENV`` environment variable instead of the absolute path of the virtual environment. On UNIX @@ -49,7 +48,7 @@ On UNIX .. code-block:: bash $ export VENV=~/pyramidtut - $ virtualenv $VENV + $ python3 -m venv $VENV On Windows ^^^^^^^^^^ @@ -71,7 +70,7 @@ Python 3.5: .. code-block:: ps1con - c:\> c:\Python35\Scripts\virtualenv %VENV% + c:\> c:\Python35\Scripts\python -m venv %VENV% Upgrade ``pip`` and ``setuptools`` in the virtual environment @@ -164,8 +163,9 @@ On Windows .. 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. + path. If you experience startup problems, try putting both the virtual + environment and the project into directories that do not contain spaces in + their paths. .. _installing_project_in_dev_mode_zodb: @@ -177,7 +177,7 @@ 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. +command using the virtual environment Python interpreter. On UNIX ^^^^^^^ @@ -283,8 +283,8 @@ 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 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 ^^^^^^^ -- cgit v1.2.3