diff options
Diffstat (limited to 'docs/tutorials/wiki2/installation.rst')
| -rw-r--r-- | docs/tutorials/wiki2/installation.rst | 555 |
1 files changed, 418 insertions, 137 deletions
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index bd597b5df..f4676345e 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -1,240 +1,521 @@ +.. _wiki2_installation: + ============ Installation ============ -This tutorial assumes that Python and virtualenv are already installed -and working in your system. If you need help setting this up, you should -refer to the chapters on :ref:`installing_chapter`. +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. + +* A Python interpreter is installed on your operating system. +* You've satisfied the :ref:`requirements-for-installing-packages`. + + +Create directory to contain the project +--------------------------------------- + +We need a workspace for our project files. + +On UNIX +^^^^^^^ + +.. code-block:: bash + + $ mkdir ~/pyramidtut + +On Windows +^^^^^^^^^^ + +.. code-block:: doscon + + c:\> mkdir pyramidtut + + +Create and use a virtual Python environment +------------------------------------------- + +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 +^^^^^^^ + +.. code-block:: bash + + $ export VENV=~/pyramidtut + $ python3 -m venv $VENV + +On Windows +^^^^^^^^^^ + +.. code-block:: doscon + + c:\> set VENV=c:\pyramidtut + +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:: doscon + + c:\> c:\Python27\Scripts\virtualenv %VENV% -Preparation -=========== +Python 3.5: -Please take the following steps to prepare for the tutorial. The -steps are slightly different depending on whether you're using UNIX or -Windows. +.. code-block:: doscon -Preparation, UNIX ------------------ + c:\> c:\Python35\Scripts\python -m venv %VENV% -#. Install SQLite3 and its development packages if you don't already - have them installed. Usually this is via your system's package - manager. For example, on a Debian Linux system, do ``sudo apt-get - install libsqlite3-dev``. -#. Use your Python's virtualenv to make a workspace: +Upgrade ``pip`` and ``setuptools`` in the virtual environment +------------------------------------------------------------- - .. code-block:: text +On UNIX +^^^^^^^ - $ path/to/my/Python-2.6/bin/virtualenv --no-site-packages pyramidtut +.. code-block:: bash -#. Switch to the ``pyramidtut`` directory: + $ $VENV/bin/pip install --upgrade pip setuptools - .. code-block:: text +On Windows +^^^^^^^^^^ - $ cd pyramidtut +.. code-block:: doscon -#. Use ``easy_install`` to get :app:`Pyramid` and its direct - dependencies installed: + c:\> %VENV%\Scripts\pip install --upgrade pip setuptools - .. code-block:: text - $ bin/easy_install pyramid +Install Pyramid into the virtual Python environment +--------------------------------------------------- -#. Use ``easy_install`` to install various packages from PyPI. +On UNIX +^^^^^^^ - .. code-block:: text +.. code-block:: bash - $ bin/easy_install docutils nose coverage zope.sqlalchemy \ - SQLAlchemy repoze.tm2 + $ $VENV/bin/pip install pyramid -Preparation, Windows --------------------- +On Windows +^^^^^^^^^^ -#. Use your Python's virtualenv to make a workspace: +.. code-block:: doscon - .. code-block:: text + c:\> %VENV%\Scripts\pip install pyramid - c:\> c:\Python26\Scripts\virtualenv --no-site-packages pyramidtut -#. Switch to the ``pyramidtut`` directory: +Install SQLite3 and its development packages +-------------------------------------------- - .. code-block:: text +If you used a package manager to install your Python or if you compiled +your Python from source, then you must install SQLite3 and its +development packages. If you downloaded your Python as an installer +from https://www.python.org, then you already have it installed and can skip +this step. - c:\> cd pyramidtut +If you need to install the SQLite3 packages, then, for example, using +the Debian system and ``apt-get``, the command would be the following: -#. Use ``easy_install`` to get :app:`Pyramid` and its direct - dependencies installed: +.. code-block:: bash - .. code-block:: text + $ sudo apt-get install libsqlite3-dev - c:\pyramidtut> Scripts\easy_install pyramid -#. Use ``easy_install`` to install various packages from PyPI. +Change directory to your virtual Python environment +--------------------------------------------------- - .. code-block:: text +Change directory to the ``pyramidtut`` directory, which is both your workspace +and your virtual environment. - c:\pyramidtut> Scripts\easy_install docutils ^ - nose coverage zope.sqlalchemy SQLAlchemy repoze.tm2 +On UNIX +^^^^^^^ + +.. code-block:: bash + + $ cd pyramidtut + +On Windows +^^^^^^^^^^ + +.. code-block:: doscon + + c:\> cd pyramidtut .. _sql_making_a_project: -Making a Project -================ +Making a project +---------------- -Your next step is to create a project. :app:`Pyramid` supplies a -variety of scaffolds to generate sample projects. We will use the -``pyramid_routesalchemy`` scaffold, which generates an application +Your next step is to create a project. For this tutorial we will use +the :term:`scaffold` named ``alchemy`` which generates an application that uses :term:`SQLAlchemy` and :term:`URL dispatch`. -The below instructions assume your current working directory is the -"virtualenv" named "pyramidtut". +: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 ``alchemy`` into the ``pcreate`` command, the script creates the +files needed to use SQLAlchemy. By passing in our application name +``tutorial``, the script inserts that application name into all the required +files. For example, ``pcreate`` creates the ``initialize_tutorial_db`` in the +``pyramidtut/bin`` directory. -On UNIX: +The below instructions assume your current working directory is "pyramidtut". -.. code-block:: text +On UNIX +^^^^^^^ - $ bin/paster create -t pyramid_routesalchemy tutorial +.. code-block:: bash -On Windows: + $ $VENV/bin/pcreate -s alchemy tutorial -.. code-block:: text +On Windows +^^^^^^^^^^ - c:\pyramidtut> Scripts\paster create -t pyramid_routesalchemy tutorial +.. code-block:: doscon -.. note:: If you are using Windows, the ``pyramid_routesalchemy`` - 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. + c:\pyramidtut> %VENV%\Scripts\pcreate -s alchemy tutorial -Installing the Project in "Development Mode" -============================================ +.. note:: If you are using Windows, the ``alchemy`` 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 virtual + environment and the project into directories that do not contain spaces in + their paths. -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:`sql_making_a_project`, and run the -"setup.py develop" command using virtualenv Python interpreter. -On UNIX: +.. _installing_project_in_dev_mode: -.. code-block:: text +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:`sql_making_a_project`, and run the ``pip install -e .`` +command using the virtual environment Python interpreter. + +On UNIX +^^^^^^^ + +.. code-block:: bash $ cd tutorial - $ ../bin/python setup.py develop + $ $VENV/bin/pip install -e . -On Windows: +On Windows +^^^^^^^^^^ -.. code-block:: text +.. code-block:: doscon c:\pyramidtut> cd tutorial - c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop + c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e . -.. _sql_running_tests: +The console will show ``pip`` checking for packages and installing missing +packages. Success executing this command will show a line like the following: -Running the Tests -================= +.. code-block:: bash -After you've installed the project in development mode, you may run -the tests for the project. + Successfully installed Chameleon-2.24 Mako-1.0.4 MarkupSafe-0.23 \ + Pygments-2.1.3 SQLAlchemy-1.0.12 pyramid-chameleon-0.3 \ + pyramid-debugtoolbar-2.4.2 pyramid-mako-1.0.2 pyramid-tm-0.12.1 \ + transaction-1.4.4 tutorial waitress-0.8.10 zope.sqlalchemy-0.7.6 -On UNIX: -.. code-block:: text +.. _install-testing-requirements: - $ ../bin/python setup.py test -q +Install testing requirements +---------------------------- -On Windows: +In order to run tests, we need to install the testing requirements. This is +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. -.. code-block:: text +.. literalinclude:: src/installation/setup.py + :language: python + :linenos: + :lineno-start: 22 + :lines: 22-26 - c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q +.. literalinclude:: src/installation/setup.py + :language: python + :linenos: + :lineno-start: 45 + :lines: 45-47 -Starting the Application -======================== +On UNIX +^^^^^^^ -Start the application. +.. code-block:: bash + + $ $VENV/bin/pip install -e ".[testing]" + +On Windows +^^^^^^^^^^ + +.. code-block:: doscon + + c:\pyramidtut\tutorial> %VENV%\Scripts\pip install -e ".[testing]" + + +.. _sql_running_tests: + +Run the tests +------------- + +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:: bash + + $ $VENV/bin/py.test tutorial/tests.py -q + +On Windows +^^^^^^^^^^ -On UNIX: +.. code-block:: doscon -.. code-block:: text + c:\pyramidtut\tutorial> %VENV%\Scripts\py.test tutorial\tests.py -q - $ ../bin/paster serve development.ini --reload +For a successful test run, you should see output that ends like this: -On Windows: +.. code-block:: bash -.. code-block:: text + .. + 2 passed in 0.44 seconds - c:\pyramidtut\tutorial> ..\Scripts\paster serve development.ini --reload -Exposing Test Coverage Information -================================== +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. -To get this functionality working, we'll need to install a couple of -other packages into our ``virtualenv``: ``nose`` and ``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:: text +.. code-block:: bash - $ ../bin/easy_install nose coverage + $ $VENV/bin/py.test --cov=tutorial --cov-report=term-missing tutorial/tests.py -On Windows: +On Windows +^^^^^^^^^^ -.. code-block:: text +.. code-block:: doscon - c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage + c:\pyramidtut\tutorial> %VENV%\Scripts\py.test --cov=tutorial \ + --cov-report=term-missing tutorial\tests.py -Once ``nose`` and ``coverage`` are installed, we can actually run the -coverage tests. +If successful, you will see output something like this: -On UNIX: +.. code-block:: bash -.. code-block:: text + ======================== 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 2 items - $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage + tutorial/tests.py .. + ------------------ coverage: platform Python 3.5.1 ------------------ + Name Stmts Miss Cover Missing + ---------------------------------------------------------------- + tutorial/__init__.py 8 6 25% 7-12 + tutorial/models/__init__.py 22 0 100% + tutorial/models/meta.py 5 0 100% + tutorial/models/mymodel.py 8 0 100% + tutorial/routes.py 3 3 0% 1-3 + tutorial/scripts/__init__.py 0 0 100% + tutorial/scripts/initializedb.py 26 26 0% 1-45 + tutorial/tests.py 39 0 100% + tutorial/views/__init__.py 0 0 100% + tutorial/views/default.py 12 0 100% + tutorial/views/notfound.py 4 4 0% 1-7 + ---------------------------------------------------------------- + TOTAL 127 39 69% -On Windows: + ===================== 2 passed in 0.57 seconds ====================== -.. code-block:: text +Our package doesn't quite have 100% test coverage. - c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^ - --cover-erase --with-coverage -Looks like our package's ``models`` module doesn't quite have 100% -test coverage. +.. _initialize_db_wiki2: -Visit the Application in a Browser -================================== +Initializing the database +------------------------- -In a browser, visit ``http://localhost:6543/``. You will see the -generated application's default page. +We need to use the ``initialize_tutorial_db`` :term:`console script` to +initialize our database. -Decisions the ``pyramid_routesalchemy`` Scaffold Has Made For You -================================================================= +.. note:: + + The ``initialize_tutorial_db`` command does not perform a migration, but + rather it simply creates missing tables and adds some dummy data. If you + already have a database, you should delete it before running + ``initialize_tutorial_db`` again. + +.. note:: + + The ``initialize_tutorial_db`` command is not performing a migration but + rather simply creating missing tables and adding some dummy data. If you + already have a database, you should delete it before running + ``initialize_tutorial_db`` again. + +Type the following command, making sure you are still in the ``tutorial`` +directory (the directory with a ``development.ini`` in it): + +On UNIX +^^^^^^^ + +.. code-block:: bash + + $ $VENV/bin/initialize_tutorial_db development.ini + +On Windows +^^^^^^^^^^ + +.. code-block:: doscon + + c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini + +The output to your console should be something like this: + +.. code-block:: bash + + 2016-04-09 00:53:37,801 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1 + 2016-04-09 00:53:37,801 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () + 2016-04-09 00:53:37,802 INFO [sqlalchemy.engine.base.Engine:1192][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1 + 2016-04-09 00:53:37,802 INFO [sqlalchemy.engine.base.Engine:1193][MainThread] () + 2016-04-09 00:53:37,802 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] PRAGMA table_info("models") + 2016-04-09 00:53:37,803 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-04-09 00:53:37,803 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] + CREATE TABLE models ( + id INTEGER NOT NULL, + name TEXT, + value INTEGER, + CONSTRAINT pk_models PRIMARY KEY (id) + ) + + + 2016-04-09 00:53:37,803 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-04-09 00:53:37,804 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + 2016-04-09 00:53:37,805 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] CREATE UNIQUE INDEX my_index ON models (name) + 2016-04-09 00:53:37,805 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] () + 2016-04-09 00:53:37,806 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + 2016-04-09 00:53:37,807 INFO [sqlalchemy.engine.base.Engine:646][MainThread] BEGIN (implicit) + 2016-04-09 00:53:37,808 INFO [sqlalchemy.engine.base.Engine:1097][MainThread] INSERT INTO models (name, value) VALUES (?, ?) + 2016-04-09 00:53:37,808 INFO [sqlalchemy.engine.base.Engine:1100][MainThread] ('one', 1) + 2016-04-09 00:53:37,809 INFO [sqlalchemy.engine.base.Engine:686][MainThread] COMMIT + +Success! You should now have a ``tutorial.sqlite`` file in your current +working directory. This is an SQLite database with a single table defined in it +(``models``). + +.. _wiki2-start-the-application: + +Start the application +--------------------- + +Start the application. + +On UNIX +^^^^^^^ + +.. code-block:: bash -Creating a project using the ``pyramid_routesalchemy`` scaffold makes -the following assumptions: + $ $VENV/bin/pserve development.ini --reload -- you are willing to use :term:`SQLAlchemy` as a database access tool +On Windows +^^^^^^^^^^ -- you are willing to use :term:`url dispatch` to map URLs to code. +.. code-block:: doscon -- you want to configure your application *imperatively* (no - :term:`declarative configuration` such as ZCML). + c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload .. note:: - :app:`Pyramid` supports any persistent storage mechanism (e.g. object - database or filesystem files, etc). It also supports an additional - mechanism to map URLs to code (:term:`traversal`). However, for the - purposes of this tutorial, we'll only be using url dispatch and - SQLAlchemy. + 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:: + + Starting subprocess with file monitor + Starting server in PID 82349. + serving on http://127.0.0.1:6543 + +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. + +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 ``alchemy`` scaffold has made for you +--------------------------------------------------- + +Creating a project using the ``alchemy`` scaffold makes the following +assumptions: + +- You are willing to use :term:`SQLAlchemy` as a database access tool. + +- You are willing to use :term:`URL dispatch` to map URLs to code. + +- You want to use zope.sqlalchemy_, pyramid_tm_, and the transaction_ packages + to scope sessions to requests. + +- You want to use pyramid_jinja2_ 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:: + + :app:`Pyramid` supports any persistent storage mechanism (e.g., object + database or filesystem files). It also supports an additional mechanism to + map URLs to code (:term:`traversal`). However, for the purposes of this + tutorial, we'll only be using URL dispatch and SQLAlchemy. + +.. _pyramid_jinja2: + http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/ + +.. _pyramid_tm: + http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/ + +.. _zope.sqlalchemy: + https://pypi.python.org/pypi/zope.sqlalchemy + +.. _transaction: + http://zodb.readthedocs.org/en/latest/transactions.html + +.. _pyramid_jinja2: + http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/ + +.. _pyramid_tm: + http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/ + +.. _zope.sqlalchemy: + https://pypi.python.org/pypi/zope.sqlalchemy +.. _transaction: + http://zodb.readthedocs.org/en/latest/transactions.html |