From 187104fd81418beeb51592913041d9751bafe08d Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 09:27:43 -0400 Subject: Quick Tutorial: Improve the setup instructions (adapted from Steve Piercy's work), particularly for Windows. Change all the steps to use $VENV/bin prefixes on commands (don't presume that they have done source env/bin/activate). --- docs/quick_tutorial/requirements.rst | 246 +++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 docs/quick_tutorial/requirements.rst (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst new file mode 100644 index 000000000..4c71d0fdd --- /dev/null +++ b/docs/quick_tutorial/requirements.rst @@ -0,0 +1,246 @@ +============ +Requirements +============ + +Let's get our tutorial environment setup. Most of the setup work is in +standard Python development practices (install Python, +make an isolated environment, and setup packaging tools.) + +.. note:: + + Pyramid encourages standard Python development practices with + packaging tools, virtual environments, logging, and so on. There + are many variations, implementations, and opinions across the Python + community. For consistency, ease of documentation maintenance, + and to minimize confusion, the Pyramid *documentation* has adopted + specific conventions. + +This *Quick Tutorial* is based on: + +* **Python 3.3**. Pyramid fully supports Python 3.2+ and Python 2.6+. + This tutorial uses **Python 3.3** but runs fine under Python 2.7. + +* **pyvenv**. We believe in virtual environments. For this tutorial, + we use Python 3.3's built-in solution, the ``pyvenv`` command. + For Python 2.7, you can install ``virtualenv``. + +* **setuptools and easy_install**. We use + `setuptools `_ + and its ``easy_install`` for package management. + +* **Workspaces, projects, and packages.** Our home directory + will contain a *tutorial workspace* with our Python virtual + environment(s) and *Python projects* (a directory with packaging + information and *Python packages* of working code.) + +* **Unix commands**. Commands in this tutorial use UNIX syntax and + paths. Windows users should adjust commands accordingly. + +.. note:: + + Pyramid was one of the first web frameworks to fully support Python 3 in + October 2011. + +Steps +===== + +#. :ref:`install-python-3.3-or-greater` +#. :ref:`create-a-project-directory-structure` +#. :ref:`set-an-environment-variable` +#. :ref:`create-a-virtual-environment` +#. :ref:`install-setuptools-(python-packaging-tools)` +#. :ref:`install-pyramid` + +.. _install-python-3.3-or-greater: + +Install Python 3.3 or greater +----------------------------- + +Download the latest standard Python 3.3+ release (not development +release) from +`python.org `_. On that page, you +must click the latest version, then scroll down to the "Downloads" section +for your operating system. + +Windows and Mac OS X users can download and run an installer. + +Windows users should also install the `Python for Windows extensions +`_. Carefully read the +``README.txt`` file at the end of the list of builds, and follow its +directions. Make sure you get the proper 32- or 64-bit build and Python +version. + +Linux users can either use their package manager to install Python 3.3 +or may +`build Python 3.3 from source +`_. + + +.. _create-a-project-directory-structure: + +Create a project directory structure +------------------------------------ + +We will arrive at a directory structure of +``workspace->project->package``, with our workspace named +``quick_tutorial``. The following diagram shows how this is structured +and where our virtual environment will reside: + +.. figure:: ../_static/directory_structure_pyramid.png + :alt: Final directory structure + + Final directory structure. + +The commands to do so are as follows: + +.. code-block:: bash + + # Mac and Linux + $ cd ~ + $ mkdir projects + $ cd projects + $ mkdir quick_tutorial + $ cd quick_tutorial + + # Windows + c:\> cd \ + c:\> mkdir projects + c:\> cd projects + c:\> mkdir quick_tutorial + c:\> cd quick_tutorial + +In the above figure, your user home directory is represented by ``~``. In +your home directory, all of your projects are in the ``projects`` directory. +This is a general convention not specific to Pyramid that many developers use. +Windows users will do well to use ``c:\`` as the location for ``projects`` in +order to avoid spaces in any of the path names. + +Next within ``projects`` is your workspace directory, here named +``quick_tutorial``. A workspace is a common term used by integrated +development environments (IDE) like PyCharm and PyDev that stores +isolated Python environments (virtualenvs) and specific project files +and repositories. + + +.. _set-an-environment-variable: + +Set an Environment Variable +--------------------------- + +This tutorial will refer frequently to the location of the virtual +environment. We set an environment variable to save typing later. + +.. code-block:: bash + + # Mac and Linux + $ export VENV=~/projects/quick_tutorial/env33/ + + # Windows + # TODO: This command does not work + c:\> set VENV=c:\projects\quick_tutorial\env33 + + +.. _create-a-virtual-environment: + +Create a Virtual Environment +---------------------------- + +.. warning:: The current state of isolated Python environments using + ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See + http://stackoverflow.com/q/15981111/95735 for a discussion of the issue + and `PEP 453 `_ for a proposed + resolution. + +``pyvenv`` is a tool to create isolated Python 3.3 environments, each +with its own Python binary and independent set of installed Python +packages in its site directories. Let's create one, using the location +we just specified in the environment variable. + +.. code-block:: bash + + # Mac and Linux + $ pyvenv $VENV + + # Windows + c:\> c:\Python33\python -m venv %VENV% + +.. seealso:: See also Python 3's :mod:`venv module `, + Python 2's `virtualenv `_ + package, + :ref:`Installing Pyramid on a Windows System ` + + +.. _install-setuptools-(python-packaging-tools): + +Install ``setuptools`` (Python packaging tools) +----------------------------------------------- + +The following command will download a script to install ``setuptools``, then +pipe it to your environment's version of Python. + +.. code-block:: bash + + # Mac and Linux + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python + + # Windows + # Use your browser to download: + # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.p + # ...into c:\projects\quick_tutorial\ez_setup.py + c:\> %VENV%\Scripts\python ez_setup.py + +If ``wget`` complains with a certificate error, then run this command instead: + +.. code-block:: bash + + # Mac and Linux + $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python + + +.. _install-pyramid: + +Install Pyramid +--------------- + +We have our Python standard prerequisites out of the way. The Pyramid +part is pretty easy: + +.. code-block:: bash + + # Mac and Linux + $ easy_install pyramid + + # Windows + c:\> %VENV%\Scripts\easy_install pyramid + +Our Python virtual environment now has the Pyramid software available. + +You can optionally install some of the extra Python packages used +during this tutorial: + +.. code-block:: bash + + # Mac and Linux + $ easy_install nose webtest deform sqlalchemy + + # Windows + c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy + + + +.. note:: + + Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace + packages which, until recently, ``pip`` didn't permit. Also, Pyramid has + some optional C extensions for performance. With ``easy_install``, Windows + users can get these extensions without needing a C compiler. + +.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your + Python environment for development using Windows or Python 2, see Pyramid's + :ref:`Before You Install `. + + See also Python 3's :mod:`venv module `, the `setuptools` `installation instructions + `_, + and `easy_install help `_. + -- cgit v1.2.3 From a01c2ab67bb36cc1313079b8257bdad98597b0c0 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 10:06:31 -0400 Subject: Oops, need a $VENV path to easy_install --- docs/quick_tutorial/requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 4c71d0fdd..bdab8210e 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -209,7 +209,7 @@ part is pretty easy: .. code-block:: bash # Mac and Linux - $ easy_install pyramid + $ $VENV/bin/easy_install pyramid # Windows c:\> %VENV%\Scripts\easy_install pyramid -- cgit v1.2.3 From 94e72c2fe1ca6acc1dc50ab8c0da48e0e191b4df Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 10:15:26 -0400 Subject: Add some more of the up-front packages. --- docs/quick_tutorial/requirements.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index bdab8210e..31f4d5320 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -222,10 +222,11 @@ during this tutorial: .. code-block:: bash # Mac and Linux - $ easy_install nose webtest deform sqlalchemy + $ $VENV/bin/easy_install nose webtest deform sqlalchemy \ + pyramid_chameleon pyramid_debugtoolbar waitress # Windows - c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy + c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon -- cgit v1.2.3 From 34e974e360184baef873da55f31379697e367f32 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Wed, 25 Sep 2013 12:08:33 -0400 Subject: Get pyramid_chameleon added to the quick tutorial, plus some other fixes for Python 3. --- docs/quick_tutorial/requirements.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 31f4d5320..8afb664d4 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -223,7 +223,8 @@ during this tutorial: # Mac and Linux $ $VENV/bin/easy_install nose webtest deform sqlalchemy \ - pyramid_chameleon pyramid_debugtoolbar waitress + pyramid_chameleon pyramid_debugtoolbar waitress \ + pyramid_jinja2 pyramid_tm zope.sqlalchemy pysqlite # Windows c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon -- cgit v1.2.3 From b731b5fca253d9d95b3307490aa585e194676c01 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Thu, 26 Sep 2013 17:41:44 -0400 Subject: Quick Tour: shorten the setup part and point to Quick Tutorial Requirements for more explanation. Cross link each Quick Tour section with its Quick Tutorial match. --- docs/quick_tutorial/requirements.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 8afb664d4..df63ff912 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -1,3 +1,5 @@ +.. _qtut_requirements: + ============ Requirements ============ -- cgit v1.2.3 From ebca905c2a2e1e796f3840baaf154a6d9d695cc4 Mon Sep 17 00:00:00 2001 From: Paul Everitt Date: Sat, 28 Sep 2013 12:14:13 -0400 Subject: Used a parsed-literal to pin the version number on easy_install. --- docs/quick_tutorial/requirements.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/quick_tutorial/requirements.rst') diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index df63ff912..40e818807 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -94,23 +94,23 @@ and where our virtual environment will reside: Final directory structure. -The commands to do so are as follows: +For Linux, the commands to do so are as follows: .. code-block:: bash # Mac and Linux $ cd ~ - $ mkdir projects - $ cd projects - $ mkdir quick_tutorial - $ cd quick_tutorial + $ mkdir -p projects/quick_tutorial + $ cd projects/quick_tutorial + +For Windows: + +.. code-block:: posh # Windows c:\> cd \ - c:\> mkdir projects - c:\> cd projects - c:\> mkdir quick_tutorial - c:\> cd quick_tutorial + c:\> mkdir projects\quick_tutorial + c:\> cd projects\quick_tutorial In the above figure, your user home directory is represented by ``~``. In your home directory, all of your projects are in the ``projects`` directory. @@ -208,13 +208,13 @@ Install Pyramid We have our Python standard prerequisites out of the way. The Pyramid part is pretty easy: -.. code-block:: bash +.. parsed-literal:: # Mac and Linux - $ $VENV/bin/easy_install pyramid + $ $VENV/bin/easy_install "pyramid==\ |release|\ " # Windows - c:\> %VENV%\Scripts\easy_install pyramid + c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " Our Python virtual environment now has the Pyramid software available. -- cgit v1.2.3