| | |
| | | frameworks, or a pro in a hurry. For more detailed treatment of each topic, |
| | | give the :ref:`quick_tutorial` a try. |
| | | |
| | | If you would prefer to cut and paste the example code in this tour you may browse the source code located in the `Pyramid repository in the directory "docs/quick_tour" <https://github.com/Pylons/pyramid/>`. If you have downloaded the source code, you will find the tour in the same location. |
| | | |
| | | 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 <https://www.python.org/downloads/>`_, `venv |
| | | <https://packaging.python.org/en/latest/projects/#venv>`_ (or `virtualenv for |
| | | Python 2.7 <https://packaging.python.org/en/latest/projects/#virtualenv>`_), |
| | | `pip <https://packaging.python.org/en/latest/projects/#pip>`_, and `setuptools |
| | | <https://packaging.python.org/en/latest/projects/#easy-install>`_. |
| | | Quick Tour, it means `Python <https://www.python.org/downloads/>`_, :mod:`python:venv` (or `virtualenv for |
| | | Python 2.7 <https://virtualenv.pypa.io/en/stable/>`_), |
| | | `pip <https://pypi.org/project/pip/>`_, and `Setuptools |
| | | <https://pypi.org/project/setuptools/>`_. |
| | | |
| | | To save a little bit of typing and to be certain that we use the modules, |
| | | scripts, and packages installed in our virtual environment, we'll set an |
| | | environment variable, too. |
| | | |
| | | As an example, for Python 3.6+ on Linux: |
| | | As an example, for Python 3 on Linux: |
| | | |
| | | .. parsed-literal:: |
| | | |
| | |
| | | # set an environment variable to where you want your virtual environment |
| | | c:\\> set VENV=c:\\env |
| | | # create the virtual environment |
| | | c:\\> %VENV%\\Scripts\\python -m venv %VENV% |
| | | c:\\> python -m venv %VENV% |
| | | # install pyramid |
| | | c:\\> %VENV%\\Scripts\\pip install pyramid |
| | | # or for a specific released version |
| | |
| | | Of course Pyramid runs fine on Python 2.7+, as do the examples in this *Quick |
| | | Tour*. We're showing Python 3 for simplicity. (Pyramid had production support |
| | | for Python 3 in October 2011.) Also for simplicity, the remaining examples will |
| | | show only UNIX commands. |
| | | show only Unix commands. |
| | | |
| | | .. seealso:: See also: |
| | | :ref:`Quick Tutorial section on Requirements <qtut_requirements>`, |
| | |
| | | New to Python web programming? If so, some lines in the module merit |
| | | explanation: |
| | | |
| | | #. *Lines 6-7*. Implement the view code that generates the :term:`response`. |
| | | |
| | | #. *Line 10*. ``if __name__ == '__main__':`` is Python's way of saying "Start |
| | | here when running from the command line". |
| | | |
| | | #. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect :term:`view` |
| | | #. *Lines 11-13*. Use Pyramid's :term:`configurator` in a :term:`context manager` to connect :term:`view` |
| | | code to a particular URL :term:`route`. |
| | | |
| | | #. *Lines 6-7*. Implement the view code that generates the :term:`response`. |
| | | |
| | | #. *Lines 14-16*. Publish a :term:`WSGI` app using an HTTP server. |
| | | |
| | |
| | | for web requests. |
| | | |
| | | Pyramid has always fit nicely into the existing world of Python web development |
| | | (virtual environments, packaging, scaffolding, one of the first to embrace |
| | | (virtual environments, packaging, cookiecutters, one of the first to embrace |
| | | Python 3, etc.). Pyramid turned to the well-regarded :term:`WebOb` Python |
| | | library for request and response handling. In our example above, Pyramid hands |
| | | ``hello_world`` a ``request`` that is :ref:`based on WebOb <webob_chapter>`. |
| | |
| | | |
| | | .. code-block:: text |
| | | |
| | | URL http://localhost:6543/?name=alice with name: alice |
| | | URL http://localhost:6543/?name=alice with name: alice |
| | | |
| | | Finally we set the response's content type, and return the Response. |
| | | |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install pyramid_chameleon |
| | | $VENV/bin/pip install pyramid_chameleon |
| | | |
| | | With the package installed, we can include the template bindings into our |
| | | configuration in ``app.py``: |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install pyramid_jinja2 |
| | | $VENV/bin/pip install pyramid_jinja2 |
| | | |
| | | With the package installed, we can include the template bindings into our |
| | | configuration: |
| | |
| | | packages, no structure. Most Pyramid projects, though, aren't developed this |
| | | way. |
| | | |
| | | To ease the process of getting started, the Pylons Project provides :term:`cookiecutter`\ s that generate sample Pyramid projects from project templates. These cookiecutters will install Pyramid and its dependencies as well. |
| | | To ease the process of getting started, the Pylons Project provides a :term:`cookiecutter` that generates sample Pyramid projects from project templates. This cookiecutter will install Pyramid and its dependencies as well. |
| | | |
| | | First you'll need to install cookiecutter. |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install cookiecutter |
| | | $VENV/bin/pip install cookiecutter |
| | | |
| | | Let's use the cookiecutter ``pyramid-cookiecutter-starter`` to create a starter Pyramid project in the current directory, entering values at the prompts as shown below for the following command. |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/cookiecutter https://github.com/Pylons/pyramid-cookiecutter-starter |
| | | $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | If prompted for the first item, accept the default ``yes`` by hitting return. |
| | | |
| | | #. ``You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. Is it |
| | | okay to delete and re-clone it? [yes]:`` |
| | | #. ``project_name [Pyramid Scaffold]: hello_world`` |
| | | #. ``repo_name [scaffold]: hello_world`` |
| | | .. code-block:: text |
| | | |
| | | You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. |
| | | Is it okay to delete and re-clone it? [yes]: yes |
| | | project_name [Pyramid Scaffold]: hello_world |
| | | repo_name [hello_world]: hello_world |
| | | Select template_language: |
| | | 1 - jinja2 |
| | | 2 - chameleon |
| | | 3 - mako |
| | | Choose from 1, 2, 3 [1]: 1 |
| | | Select backend: |
| | | 1 - none |
| | | 2 - sqlalchemy |
| | | 3 - zodb |
| | | Choose from 1, 2, 3 [1]: 1 |
| | | |
| | | We then run through the following commands. |
| | | |
| | | .. code-block:: bash |
| | | |
| | | # Change directory into your newly created project. |
| | | $ cd hello_world |
| | | cd hello_world |
| | | # Create a new virtual environment... |
| | | $ python3 -m venv env |
| | | python3 -m venv env |
| | | # ...where we upgrade packaging tools... |
| | | $ env/bin/pip install --upgrade pip setuptools |
| | | env/bin/pip install --upgrade pip setuptools |
| | | # ...and into which we install our project and its testing requirements. |
| | | $ env/bin/pip install -e ".[testing]" |
| | | env/bin/pip install -e ".[testing]" |
| | | # Reset our environment variable for a new virtual environment. |
| | | $ export VENV=~/hello_world/env |
| | | export VENV=~/hello_world/env |
| | | |
| | | We are moving in the direction of a full-featured Pyramid project, with a |
| | | proper setup for Python standards (packaging) and Pyramid configuration. This |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pserve development.ini |
| | | $VENV/bin/pserve development.ini |
| | | |
| | | Let's look at ``pserve`` and configuration in more depth. |
| | | |
| | | .. seealso:: See also: |
| | | :ref:`Quick Tutorial Cookiecutters <qtut_cookiecutters>`, |
| | | :ref:`project_narr`, and |
| | | :doc:`../narr/scaffolding` |
| | | :doc:`../narr/cookiecutters` |
| | | |
| | | Application running with ``pserve`` |
| | | =================================== |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pserve development.ini --reload |
| | | $VENV/bin/pserve development.ini --reload |
| | | |
| | | The ``pserve`` command has a number of other options and operations. Most of |
| | | the work, though, comes from your project's wiring, as expressed in the |
| | |
| | | #. *Choice of web server:* ``use = egg:waitress#main`` tells ``pserve`` to |
| | | use the ``waitress`` server. |
| | | |
| | | #. *Interfaces:* ``listen = 127.0.0.1:6543 [::1]:6543`` tells ``waitress`` to listen on all interfaces on port 6543 for both IPv4 and IPv6. |
| | | #. *Interfaces:* ``listen = localhost:6543`` tells ``waitress`` to listen on all interfaces on port 6543 for both IPv4 and IPv6. |
| | | |
| | | Additionally the ``development.ini`` generated by this scaffold wired up |
| | | Additionally the ``development.ini`` generated by this cookiecutter wired up |
| | | Python's standard logging. We'll now see in the console, for example, a log on |
| | | every request that comes in, as well as traceback information. |
| | | |
| | |
| | | available in your browser. Adding it to your project illustrates several points |
| | | about configuration. |
| | | |
| | | The cookiecutter ``pyramid-cookiecutter-starter`` already configured our package to include the |
| | | Our cookiecutter ``pyramid-cookiecutter-starter`` already configured our package to include the |
| | | add-on ``pyramid_debugtoolbar`` in its ``setup.py``: |
| | | |
| | | .. literalinclude:: quick_tour/package/setup.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 11-16 |
| | | :emphasize-lines: 4 |
| | | :lines: 11-17 |
| | | :emphasize-lines: 5 |
| | | |
| | | It was installed when you previously ran: |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/pip install -e ".[testing]" |
| | | $VENV/bin/pip install -e ".[testing]" |
| | | |
| | | The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need |
| | | to include its configuration into our web application. The cookiecutter already took care of this for us in its ``__init__.py``: |
| | | |
| | | .. literalinclude:: quick_tour/package/hello_world/__init__.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 8 |
| | | |
| | | And it uses the ``pyramid.includes`` facility in our ``development.ini``: |
| | | to include its configuration into our web application. The cookiecutter already took care of this for us in its ``development.ini`` using the ``pyramid.includes`` facility: |
| | | |
| | | .. literalinclude:: quick_tour/package/development.ini |
| | | :language: ini |
| | |
| | | :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and |
| | | :ref:`pyramid_debugtoolbar <toolbar:overview>` |
| | | |
| | | Unit tests and ``py.test`` |
| | | ========================== |
| | | Unit tests and ``pytest`` |
| | | ========================= |
| | | |
| | | Yikes! We got this far and we haven't yet discussed tests. This is particularly |
| | | egregious, as Pyramid has had a deep commitment to full test coverage since |
| | |
| | | |
| | | Our ``pyramid-cookiecutter-starter`` cookiecutter generated a ``tests.py`` module with |
| | | one unit test and one functional test in it. It also configured ``setup.py`` with test requirements: |
| | | ``py.test`` as the test runner, ``WebTest`` for running view tests, and the |
| | | ``pytest-cov`` tool which yells at us for code that isn't tested. The |
| | | highlighted lines show this: |
| | | ``pytest`` as the test runner, ``WebTest`` for running view tests, and the |
| | | ``pytest-cov`` tool which yells at us for code that isn't tested: |
| | | |
| | | .. literalinclude:: quick_tour/package/setup.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 18-22 |
| | | :lines: 19-23 |
| | | |
| | | .. literalinclude:: quick_tour/package/setup.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 42-44 |
| | | :lines: 43-45 |
| | | |
| | | We already installed the test requirements when we ran the command ``$VENV/bin/pip install -e ".[testing]"``. We can now run all our tests: |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/py.test --cov --cov-report=term-missing |
| | | $VENV/bin/pytest --cov --cov-report=term-missing |
| | | |
| | | This yields the following output. |
| | | |
| | |
| | | Maybe you would like to log messages in your code? In your Python module, |
| | | import and set up the logging in your ``views.py``: |
| | | |
| | | .. literalinclude:: quick_tour/logging/hello_world/views.py |
| | | .. literalinclude:: quick_tour/logging/hello_world/views/default.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 3-4 |
| | | |
| | | You can now, in your code, log messages: |
| | | |
| | | .. literalinclude:: quick_tour/logging/hello_world/views.py |
| | | .. literalinclude:: quick_tour/logging/hello_world/views/default.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 7-8 |
| | |
| | | .. literalinclude:: quick_tour/sessions/hello_world/__init__.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 10-13 |
| | | :lines: 9-12 |
| | | :emphasize-lines: 2-3 |
| | | |
| | | Pyramid's :term:`request` object now has a ``session`` attribute that we can |
| | | use in our view code in ``views.py``: |
| | | |
| | | .. literalinclude:: quick_tour/sessions/hello_world/views.py |
| | | .. literalinclude:: quick_tour/sessions/hello_world/views/default.py |
| | | :language: python |
| | | :lineno-match: |
| | | :lines: 7- |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ cd ~ |
| | | $ env/bin/cookiecutter https://github.com/Pylons/pyramid-cookiecutter-alchemy |
| | | cd ~ |
| | | env/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout 1.10-branch |
| | | |
| | | If prompted for the first item, accept the default ``yes`` by hitting return. |
| | | |
| | | #. ``You've cloned ~/.cookiecutters/pyramid-cookiecutter-alchemy before. Is it |
| | | okay to delete and re-clone it? [yes]:`` |
| | | #. ``project_name [Pyramid Scaffold]: sqla_demo`` |
| | | #. ``repo_name [scaffold]: sqla_demo`` |
| | | .. code-block:: text |
| | | |
| | | You've cloned ~/.cookiecutters/pyramid-cookiecutter-starter before. |
| | | Is it okay to delete and re-clone it? [yes]: yes |
| | | project_name [Pyramid Scaffold]: sqla_demo |
| | | repo_name [sqla_demo]: sqla_demo |
| | | Select template_language: |
| | | 1 - jinja2 |
| | | 2 - chameleon |
| | | 3 - mako |
| | | Choose from 1, 2, 3 [1]: 1 |
| | | Select backend: |
| | | 1 - none |
| | | 2 - sqlalchemy |
| | | 3 - zodb |
| | | Choose from 1, 2, 3 [1]: 2 |
| | | |
| | | We then run through the following commands as before. |
| | | |
| | | .. code-block:: bash |
| | | |
| | | # Change directory into your newly created project. |
| | | $ cd sqla_demo |
| | | cd sqla_demo |
| | | # Create a new virtual environment... |
| | | $ python3 -m venv env |
| | | python3 -m venv env |
| | | # ...where we upgrade packaging tools... |
| | | $ env/bin/pip install --upgrade pip setuptools |
| | | env/bin/pip install --upgrade pip setuptools |
| | | # ...and into which we install our project and its testing requirements. |
| | | $ env/bin/pip install -e ".[testing]" |
| | | env/bin/pip install -e ".[testing]" |
| | | # Reset our environment variable for a new virtual environment. |
| | | $ export VENV=~/sqla_demo/env |
| | | export VENV=~/sqla_demo/env |
| | | |
| | | We now have a working sample SQLAlchemy application with all dependencies |
| | | installed. The sample project provides a console script to initialize a SQLite |
| | |
| | | |
| | | .. code-block:: bash |
| | | |
| | | $ $VENV/bin/initialize_sqla_demo_db development.ini |
| | | $ $VENV/bin/pserve development.ini |
| | | $VENV/bin/initialize_sqla_demo_db development.ini |
| | | $VENV/bin/pserve development.ini |
| | | |
| | | The ORM eases the mapping of database structures into a programming language. |
| | | SQLAlchemy uses "models" for this mapping. The scaffold generated a sample |
| | | SQLAlchemy uses "models" for this mapping. The cookiecutter generated a sample |
| | | model: |
| | | |
| | | .. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py |
| | |
| | | schemas, and validation. Recent versions of Deform also include a :ref:`retail |
| | | mode <deform:retail>` for gaining Deform features on custom forms. |
| | | |
| | | Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets |
| | | using attractive CSS from Twitter Bootstrap and more powerful widgets from |
| | | Chosen. |
| | | Deform uses attractive CSS from Twitter Bootstrap and more powerful select, checkbox, and date and time widgets. |
| | | |
| | | .. seealso:: See also: |
| | | :ref:`Quick Tutorial Forms <qtut_forms>`, :ref:`Deform <deform:overview>`, |
| | | :ref:`Colander <colander:overview>`, and `deform_bootstrap |
| | | <https://pypi.python.org/pypi/deform_bootstrap>`_. |
| | | :ref:`Quick Tutorial Forms <qtut_forms>`, :ref:`Deform <deform:overview>`, and :ref:`Colander <colander:overview>`. |
| | | |
| | | Conclusion |
| | | ========== |