From a7dd0531b427d8633fc222830f24b737048e9c8a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 30 Mar 2016 05:53:35 -0700 Subject: update installation and glossary --- docs/glossary.rst | 4 ++ docs/tutorials/wiki2/installation.rst | 76 +++++++++++++++++++++++++++++------ 2 files changed, 67 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index 9657d9219..ef90a0f41 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -1091,3 +1091,7 @@ Glossary A technique used when serving a cacheable static asset in order to force a client to query the new version of the asset. See :ref:`cache_busting` for more information. + + pip + The `Python Packaging Authority `_ recommended tool + for installing Python packages. diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 891305bf5..b263ccbd9 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -9,9 +9,9 @@ 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 @@ -72,6 +72,24 @@ Python 3.5: c:\> c:\Python35\Scripts\virtualenv %VENV% +Upgrade pip in the virtual environment +-------------------------------------- + +On UNIX +^^^^^^^ + +.. code-block:: bash + + $ $VENV/bin/pip install --upgrade pip + +On Windows +^^^^^^^^^^ + +.. code-block:: ps1con + + c:\> %VENV%\Scripts\pip install --upgrade pip + + Install Pyramid into the virtual Python environment --------------------------------------------------- @@ -80,26 +98,27 @@ On UNIX .. code-block:: bash - $ $VENV/bin/easy_install pyramid + $ $VENV/bin/pip install pyramid On Windows ^^^^^^^^^^ .. code-block:: ps1con - c:\> %VENV%\Scripts\easy_install pyramid + c:\> %VENV%\Scripts\pip install pyramid Install SQLite3 and its development packages -------------------------------------------- -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. +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. -If you need to install the SQLite3 packages, then, for example, using the -Debian system and ``apt-get``, the command would be the following: +If you need to install the SQLite3 packages, then, for example, using +the Debian system and ``apt-get``, the command would be the following: .. code-block:: bash @@ -168,6 +187,7 @@ On Windows and the project into directories that do not contain spaces in their paths. + .. _installing_project_in_dev_mode: Installing the project in development mode @@ -185,7 +205,7 @@ On UNIX .. code-block:: bash $ cd tutorial - $ $VENV/bin/python setup.py develop + $ $VENV/bin/pip install -e . On Windows ^^^^^^^^^^ @@ -193,7 +213,7 @@ On Windows .. 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 ``setup.py`` checking for packages and installing missing packages. Success executing this command will show a line like the following:: @@ -215,6 +235,8 @@ On UNIX $ $VENV/bin/python setup.py test -q +.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046 + On Windows ^^^^^^^^^^ @@ -222,6 +244,8 @@ On Windows c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q +.. py.test? See https://github.com/Pylons/pyramid/issues/2104#issuecomment-155852046 + For a successful test run, you should see output that ends like this:: .. @@ -310,6 +334,13 @@ initialize our database. 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): @@ -415,6 +446,13 @@ assumptions: - You are willing to use :term:`URL dispatch` to map URLs to code. +- You want to use zope.sqlalchemy_, pyramid_tm_ and the transaction_ package + 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 the tutorial. See :ref:`available_template_system_bindings` for some + options. - You want to use zope.sqlalchemy_, pyramid_tm_ and the transaction_ package to scope sessions to requests. @@ -440,3 +478,15 @@ assumptions: .. _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 -- cgit v1.2.3 From 5562586cd45b994325fce4893dc0f74580eccdea Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:24:43 -0700 Subject: - update links to PyPA site as practical - update various easy_install/setup.py commands to use pip - update to use py35 - other small improvements --- docs/quick_tour.rst | 53 +++++++++++++++++++++++++---------------------------- 1 file changed, 25 insertions(+), 28 deletions(-) (limited to 'docs') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 65310bf4d..3554fc724 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -15,28 +15,29 @@ Installation Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this -Quick Tour, it means `Python `_, a `virtual -environment `_ (or `virtualenv -for Python 2.7 `_), and `setuptools -`_. +Quick Tour, it means `Python `_, `venv +`_ (or `virtualenv for +Python 2.7 `_), +`pip `_, and `setuptools +`_. -As an example, for Python 3.3+ on Linux: +As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ pyvenv env33 - $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python - $ env33/bin/easy_install "pyramid==\ |release|\ " + $ pyvenv env35 + $ env35/bin/pip install pyramid + # or for a specific released version + $ env35/bin/pip install "pyramid==\ |release|\ " For Windows: .. parsed-literal:: - # Use your browser to download: - # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py - c:\\> c:\\Python33\\python -m venv env33 - c:\\> env33\\Scripts\\python ez_setup.py - c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ " + c:\\> c:\\Python35\\python -m venv env35 + c:\\> env35\\Scripts\\pip install pyramid + # or for a specific released version + c:\\> env35\\Scripts\\pip install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production @@ -44,14 +45,8 @@ support for Python 3 in October 2011). .. note:: - Why ``easy_install`` and not ``pip``? Some distributions upon which - Pyramid depends have optional C extensions for performance. ``pip`` cannot - install some binary Python distributions. With ``easy_install``, Windows - users are able to obtain binary Python distributions, so they get the - benefit of the C extensions without needing a C compiler. Also there can - be issues when ``pip`` and ``easy_install`` are used side-by-side in the - same environment, so we chose to recommend ``easy_install`` for the sake of - reducing the complexity of these instructions. + If you use Python 2.6 or 2.7, then you might need to install + ``setuptools``. See references below for more information. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements `, @@ -249,7 +244,7 @@ Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash - $ easy_install pyramid_chameleon + $ env35/bin/pip install pyramid_chameleon With the package installed, we can include the template bindings into our configuration in ``app.py``: @@ -293,7 +288,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash - $ easy_install pyramid_jinja2 + $ env35/bin/pip install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: @@ -502,7 +497,7 @@ We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world - $ python ./setup.py develop + $ $VENV/bin/pip install -e . We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This @@ -617,7 +612,7 @@ It was installed when you previously ran: .. code-block:: bash - $ python ./setup.py develop + $ $VENV/bin/pip install -e . The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` @@ -670,7 +665,7 @@ following: }, We changed ``setup.py`` which means we need to rerun -``python ./setup.py develop``. We can now run all our tests: +``$VENV/bin/pip install -e .``. We can now run all our tests: .. code-block:: bash @@ -746,7 +741,9 @@ These emphasized sections in the configuration file: Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you visit -http://localhost:6543, your console will now show:: +http://localhost:6543, your console will now show: + +.. code-block:: text 2016-01-18 13:55:55,040 DEBUG [hello_world.views:10][waitress] Some Message @@ -827,7 +824,7 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! $ pcreate --scaffold alchemy sqla_demo $ cd sqla_demo - $ python setup.py develop + $ $VENV/bin/pip install -e . We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite -- cgit v1.2.3 From e4995d86ce6570dcfea440cafc92aecc40c421ad Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:28:14 -0700 Subject: - change env35 to just env. --- docs/quick_tour.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 3554fc724..067395218 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -25,19 +25,19 @@ As an example, for Python 3.5+ on Linux: .. parsed-literal:: - $ pyvenv env35 - $ env35/bin/pip install pyramid + $ pyvenv env + $ env/bin/pip install pyramid # or for a specific released version - $ env35/bin/pip install "pyramid==\ |release|\ " + $ env/bin/pip install "pyramid==\ |release|\ " For Windows: .. parsed-literal:: - c:\\> c:\\Python35\\python -m venv env35 - c:\\> env35\\Scripts\\pip install pyramid + c:\\> c:\\Python35\\python -m venv env + c:\\> env\\Scripts\\pip install pyramid # or for a specific released version - c:\\> env35\\Scripts\\pip install "pyramid==\ |release|\ " + c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production @@ -244,7 +244,7 @@ Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash - $ env35/bin/pip install pyramid_chameleon + $ env/bin/pip install pyramid_chameleon With the package installed, we can include the template bindings into our configuration in ``app.py``: @@ -288,7 +288,7 @@ Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash - $ env35/bin/pip install pyramid_jinja2 + $ env/bin/pip install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: -- cgit v1.2.3 From 7725b8ca96ae63f0767145aa192e3d5a67da4a1b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 31 Mar 2016 02:29:40 -0700 Subject: - change $VENV to just env. --- docs/quick_tour.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst index 067395218..32f049d6a 100644 --- a/docs/quick_tour.rst +++ b/docs/quick_tour.rst @@ -497,7 +497,7 @@ We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This @@ -612,7 +612,7 @@ It was installed when you previously ran: .. code-block:: bash - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` @@ -665,7 +665,7 @@ following: }, We changed ``setup.py`` which means we need to rerun -``$VENV/bin/pip install -e .``. We can now run all our tests: +``env/bin/pip install -e .``. We can now run all our tests: .. code-block:: bash @@ -824,7 +824,7 @@ Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! $ pcreate --scaffold alchemy sqla_demo $ cd sqla_demo - $ $VENV/bin/pip install -e . + $ env/bin/pip install -e . We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite -- cgit v1.2.3