diff options
Diffstat (limited to 'docs/quick_tutorial')
42 files changed, 470 insertions, 651 deletions
diff --git a/docs/quick_tutorial/cookiecutters.rst b/docs/quick_tutorial/cookiecutters.rst new file mode 100644 index 000000000..8e7048f78 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters.rst @@ -0,0 +1,79 @@ +.. _qtut_cookiecutters: + +================================================= +Prelude: Quick Project Startup with Cookiecutters +================================================= + +To ease the process of getting started on a project, the Pylons Project provides :term:`cookiecutter`\ s that generate sample :app:`Pyramid` projects from project templates. These cookiecutters will install :app:`Pyramid` and its dependencies as well. We will still cover many topics of web application development using :app:`Pyramid`, but it's good to know of this facility. This prelude will demonstrate how to get a working :app:`Pyramid` web application running via ``cookiecutter``. + + +Objectives +========== + +- Use a cookiecutter to make a new project. + +- Start up a :app:`Pyramid` application and visit it in a web browser. + + +Steps +===== + +#. Install cookiecutter into your virtual environment. + + .. code-block:: bash + + $VENV/bin/pip install cookiecutter + +#. Let's use the cookiecutter ``pyramid-cookiecutter-starter`` to create a starter :app:`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 + + 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]: cc_starter`` + #. ``repo_name [scaffold]: cc_starter`` + +#. We then run through the following commands. + + .. code-block:: bash + + # Change directory into your newly created project. + $ cd cc_starter + # Create a new virtual environment... + $ python3 -m venv env + # ...where we upgrade packaging tools... + $ env/bin/pip install --upgrade pip setuptools + # ...and into which we install our project. + $ env/bin/pip install -e . + +#. Start up the application by pointing :app:`Pyramid`'s ``pserve`` command at the + project's (generated) configuration file: + + .. code-block:: bash + + $ env/bin/pserve development.ini --reload + + On start up, ``pserve`` logs some output: + + .. code-block:: text + + Starting subprocess with file monitor + Starting server in PID 73732. + Serving on http://localhost:6543 + Serving on http://localhost:6543 + +#. Open http://localhost:6543/ in your browser. + +Analysis +======== + +Rather than starting from scratch, a cookiecutter can make it easy to get a Python +project containing a working :app:`Pyramid` application. The Pylons Project provides `several cookiecutters <https://github.com/Pylons?q=pyramid-cookiecutter>`_. + +``pserve`` is :app:`Pyramid`'s application runner, separating operational details from +your code. When you install :app:`Pyramid`, a small command program called ``pserve`` +is written to your ``bin`` directory. This program is an executable Python +module. It is passed a configuration file (in this case, ``development.ini``). diff --git a/docs/quick_tutorial/cookiecutters/.coveragerc b/docs/quick_tutorial/cookiecutters/.coveragerc new file mode 100644 index 000000000..1bcbb8c3e --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/.coveragerc @@ -0,0 +1,3 @@ +[run] +source = cc_starter +omit = cc_starter/test* diff --git a/docs/quick_tutorial/cookiecutters/CHANGES.txt b/docs/quick_tutorial/cookiecutters/CHANGES.txt new file mode 100644 index 000000000..14b902fd1 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/CHANGES.txt @@ -0,0 +1,4 @@ +0.0 +--- + +- Initial version. diff --git a/docs/quick_tutorial/cookiecutters/MANIFEST.in b/docs/quick_tutorial/cookiecutters/MANIFEST.in new file mode 100644 index 000000000..79c7ec16c --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt *.ini *.cfg *.rst +recursive-include cc_starter *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml *.jinja2 diff --git a/docs/quick_tutorial/cookiecutters/README.txt b/docs/quick_tutorial/cookiecutters/README.txt new file mode 100644 index 000000000..4b1f31bf3 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/README.txt @@ -0,0 +1,29 @@ +cc_starter +=============================== + +Getting Started +--------------- + +- Change directory into your newly created project. + + cd cc_starter + +- Create a Python virtual environment. + + python3 -m venv env + +- Upgrade packaging tools. + + env/bin/pip install --upgrade pip setuptools + +- Install the project in editable mode with its testing requirements. + + env/bin/pip install -e ".[testing]" + +- Run your project's tests. + + env/bin/pytest + +- Run your project. + + env/bin/pserve development.ini diff --git a/docs/quick_tutorial/scaffolds/scaffolds/__init__.py b/docs/quick_tutorial/cookiecutters/cc_starter/__init__.py index ad5ecbc6f..49dde36d4 100644 --- a/docs/quick_tutorial/scaffolds/scaffolds/__init__.py +++ b/docs/quick_tutorial/cookiecutters/cc_starter/__init__.py @@ -5,7 +5,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(settings=settings) - config.include('pyramid_chameleon') + config.include('pyramid_jinja2') config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('home', '/') config.scan() diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid-16x16.png b/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid-16x16.png Binary files differnew file mode 100644 index 000000000..979203112 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid-16x16.png diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid.png b/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid.png Binary files differnew file mode 100644 index 000000000..4ab837be9 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/static/pyramid.png diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/static/theme.css b/docs/quick_tutorial/cookiecutters/cc_starter/static/theme.css new file mode 100644 index 000000000..0f4b1a4d4 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/static/theme.css @@ -0,0 +1,154 @@ +@import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700); +body { + font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; + font-weight: 300; + color: #ffffff; + background: #bc2131; +} +h1, +h2, +h3, +h4, +h5, +h6 { + font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; + font-weight: 300; +} +p { + font-weight: 300; +} +.font-normal { + font-weight: 400; +} +.font-semi-bold { + font-weight: 600; +} +.font-bold { + font-weight: 700; +} +.starter-template { + margin-top: 250px; +} +.starter-template .content { + margin-left: 10px; +} +.starter-template .content h1 { + margin-top: 10px; + font-size: 60px; +} +.starter-template .content h1 .smaller { + font-size: 40px; + color: #f2b7bd; +} +.starter-template .content .lead { + font-size: 25px; + color: #f2b7bd; +} +.starter-template .content .lead .font-normal { + color: #ffffff; +} +.starter-template .links { + float: right; + right: 0; + margin-top: 125px; +} +.starter-template .links ul { + display: block; + padding: 0; + margin: 0; +} +.starter-template .links ul li { + list-style: none; + display: inline; + margin: 0 10px; +} +.starter-template .links ul li:first-child { + margin-left: 0; +} +.starter-template .links ul li:last-child { + margin-right: 0; +} +.starter-template .links ul li.current-version { + color: #f2b7bd; + font-weight: 400; +} +.starter-template .links ul li a, a { + color: #f2b7bd; + text-decoration: underline; +} +.starter-template .links ul li a:hover, a:hover { + color: #ffffff; + text-decoration: underline; +} +.starter-template .links ul li .icon-muted { + color: #eb8b95; + margin-right: 5px; +} +.starter-template .links ul li:hover .icon-muted { + color: #ffffff; +} +.starter-template .copyright { + margin-top: 10px; + font-size: 0.9em; + color: #f2b7bd; + text-transform: lowercase; + float: right; + right: 0; +} +@media (max-width: 1199px) { + .starter-template .content h1 { + font-size: 45px; + } + .starter-template .content h1 .smaller { + font-size: 30px; + } + .starter-template .content .lead { + font-size: 20px; + } +} +@media (max-width: 991px) { + .starter-template { + margin-top: 0; + } + .starter-template .logo { + margin: 40px auto; + } + .starter-template .content { + margin-left: 0; + text-align: center; + } + .starter-template .content h1 { + margin-bottom: 20px; + } + .starter-template .links { + float: none; + text-align: center; + margin-top: 60px; + } + .starter-template .copyright { + float: none; + text-align: center; + } +} +@media (max-width: 767px) { + .starter-template .content h1 .smaller { + font-size: 25px; + display: block; + } + .starter-template .content .lead { + font-size: 16px; + } + .starter-template .links { + margin-top: 40px; + } + .starter-template .links ul li { + display: block; + margin: 0; + } + .starter-template .links ul li .icon-muted { + display: none; + } + .starter-template .copyright { + margin-top: 20px; + } +} diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/templates/layout.jinja2 b/docs/quick_tutorial/cookiecutters/cc_starter/templates/layout.jinja2 new file mode 100644 index 000000000..20da74879 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/templates/layout.jinja2 @@ -0,0 +1,64 @@ +<!DOCTYPE html> +<html lang="{{request.locale_name}}"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content="pyramid web application"> + <meta name="author" content="Pylons Project"> + <link rel="shortcut icon" href="{{request.static_url('cc_starter:static/pyramid-16x16.png')}}"> + + <title>Cookiecutter Starter project for the Pyramid Web Framework</title> + + <!-- Bootstrap core CSS --> + <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet"> + + <!-- Custom styles for this scaffold --> + <link href="{{request.static_url('cc_starter:static/theme.css')}}" rel="stylesheet"> + + <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> + <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> + <![endif]--> + </head> + + <body> + + <div class="starter-template"> + <div class="container"> + <div class="row"> + <div class="col-md-2"> + <img class="logo img-responsive" src="{{request.static_url('cc_starter:static/pyramid.png') }}" alt="pyramid web framework"> + </div> + <div class="col-md-10"> + {% block content %} + <p>No content</p> + {% endblock content %} + </div> + </div> + <div class="row"> + <div class="links"> + <ul> + <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li> + <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="https://webchat.freenode.net/?channels=pyramid">IRC Channel</a></li> + <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li> + </ul> + </div> + </div> + <div class="row"> + <div class="copyright"> + Copyright © Pylons Project + </div> + </div> + </div> + </div> + + + <!-- Bootstrap core JavaScript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script> + <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script> + </body> +</html> diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/templates/mytemplate.jinja2 b/docs/quick_tutorial/cookiecutters/cc_starter/templates/mytemplate.jinja2 new file mode 100644 index 000000000..979ee5071 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/templates/mytemplate.jinja2 @@ -0,0 +1,8 @@ +{% extends "layout.jinja2" %} + +{% block content %} +<div class="content"> + <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Starter project</span></h1> + <p class="lead">Welcome to <span class="font-normal">cc_starter</span>, a Pyramid application generated by<br><span class="font-normal">Cookiecutter</span>.</p> +</div> +{% endblock content %} diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/tests.py b/docs/quick_tutorial/cookiecutters/cc_starter/tests.py new file mode 100644 index 000000000..2f553bbb4 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/tests.py @@ -0,0 +1,29 @@ +import unittest + +from pyramid import testing + + +class ViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_my_view(self): + from .views import my_view + request = testing.DummyRequest() + info = my_view(request) + self.assertEqual(info['project'], 'cc_starter') + + +class FunctionalTests(unittest.TestCase): + def setUp(self): + from cc_starter import main + app = main({}) + from webtest import TestApp + self.testapp = TestApp(app) + + def test_root(self): + res = self.testapp.get('/', status=200) + self.assertTrue(b'Pyramid' in res.body) diff --git a/docs/quick_tutorial/cookiecutters/cc_starter/views.py b/docs/quick_tutorial/cookiecutters/cc_starter/views.py new file mode 100644 index 000000000..deedd53b8 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/cc_starter/views.py @@ -0,0 +1,6 @@ +from pyramid.view import view_config + + +@view_config(route_name='home', renderer='templates/mytemplate.jinja2') +def my_view(request): + return {'project': 'cc_starter'} diff --git a/docs/quick_tutorial/scaffolds/development.ini b/docs/quick_tutorial/cookiecutters/development.ini index 0f562d0e1..86b54b51d 100644 --- a/docs/quick_tutorial/scaffolds/development.ini +++ b/docs/quick_tutorial/cookiecutters/development.ini @@ -4,14 +4,14 @@ ### [app:main] -use = egg:scaffolds +use = egg:cc_starter pyramid.reload_templates = true pyramid.debug_authorization = false pyramid.debug_notfound = false pyramid.debug_routematch = false pyramid.default_locale_name = en -pyramid.includes = +pyramid.includes = pyramid_debugtoolbar # By default, the toolbar only appears for clients from IP addresses @@ -24,7 +24,7 @@ pyramid.includes = [server:main] use = egg:waitress#main -listen = *:6543 +listen = 127.0.0.1:6543 [::1]:6543 ### # logging configuration @@ -32,7 +32,7 @@ listen = *:6543 ### [loggers] -keys = root, scaffolds +keys = root, cc_starter [handlers] keys = console @@ -44,10 +44,10 @@ keys = generic level = INFO handlers = console -[logger_scaffolds] +[logger_cc_starter] level = DEBUG handlers = -qualname = scaffolds +qualname = cc_starter [handler_console] class = StreamHandler @@ -56,4 +56,4 @@ level = NOTSET formatter = generic [formatter_generic] -format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s +format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s diff --git a/docs/quick_tutorial/scaffolds/production.ini b/docs/quick_tutorial/cookiecutters/production.ini index bf0446a47..e24a065b1 100644 --- a/docs/quick_tutorial/scaffolds/production.ini +++ b/docs/quick_tutorial/cookiecutters/production.ini @@ -4,7 +4,7 @@ ### [app:main] -use = egg:scaffolds +use = egg:cc_starter pyramid.reload_templates = false pyramid.debug_authorization = false @@ -26,7 +26,7 @@ listen = *:6543 ### [loggers] -keys = root, scaffolds +keys = root, cc_starter [handlers] keys = console @@ -38,10 +38,10 @@ keys = generic level = WARN handlers = console -[logger_scaffolds] +[logger_cc_starter] level = WARN handlers = -qualname = scaffolds +qualname = cc_starter [handler_console] class = StreamHandler @@ -50,4 +50,4 @@ level = NOTSET formatter = generic [formatter_generic] -format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s +format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s diff --git a/docs/quick_tutorial/cookiecutters/pytest.ini b/docs/quick_tutorial/cookiecutters/pytest.ini new file mode 100644 index 000000000..a7bd797f0 --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/pytest.ini @@ -0,0 +1,3 @@ +[pytest] +testpaths = cc_starter +python_files = *.py diff --git a/docs/quick_tutorial/cookiecutters/setup.py b/docs/quick_tutorial/cookiecutters/setup.py new file mode 100644 index 000000000..e47cdf8ea --- /dev/null +++ b/docs/quick_tutorial/cookiecutters/setup.py @@ -0,0 +1,51 @@ +import os + +from setuptools import setup, find_packages + +here = os.path.abspath(os.path.dirname(__file__)) +with open(os.path.join(here, 'README.txt')) as f: + README = f.read() +with open(os.path.join(here, 'CHANGES.txt')) as f: + CHANGES = f.read() + +requires = [ + 'pyramid', + 'pyramid_jinja2', + 'pyramid_debugtoolbar', + 'waitress', +] + +tests_require = [ + 'WebTest >= 1.3.1', # py3 compat + 'pytest', + 'pytest-cov', +] + +setup( + name='cc_starter', + version='0.0', + description='cc_starter', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + 'Programming Language :: Python', + 'Framework :: Pyramid', + 'Topic :: Internet :: WWW/HTTP', + 'Topic :: Internet :: WWW/HTTP :: WSGI :: Application', + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + extras_require={ + 'testing': tests_require, + }, + install_requires=requires, + entry_points={ + 'paste.app_factory': [ + 'main = cc_starter:main', + ], + }, +) diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst index c8d87c180..87f2703c7 100644 --- a/docs/quick_tutorial/databases.rst +++ b/docs/quick_tutorial/databases.rst @@ -21,7 +21,7 @@ storage and retrieval for the wiki pages in the previous step. .. note:: - The ``alchemy`` scaffold is really helpful for getting an SQLAlchemy + The ``pyramid-cookiecutter-alchemy`` cookiecutter is really helpful for getting an SQLAlchemy project going, including generation of the console script. Since we want to see all the decisions, we will forgo convenience in this tutorial, and wire it up ourselves. diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst index 56dccde58..2f2515fcd 100644 --- a/docs/quick_tutorial/hello_world.rst +++ b/docs/quick_tutorial/hello_world.rst @@ -11,7 +11,7 @@ Python packages, no ``pip install -e .``, no other machinery. Background ========== -Microframeworks are all the rage these days. "Microframework" is a marketing +Microframeworks were all the rage, until the next shiny thing came along. "Microframework" is a marketing term, not a technical one. They have a low mental overhead: they do so little, the only things you have to worry about are *your things*. @@ -49,7 +49,7 @@ Steps .. code-block:: bash - $ mkdir hello_world; cd hello_world + $ cd ~/projects/quick_tutorial; mkdir hello_world; cd hello_world #. Copy the following into ``hello_world/app.py``: diff --git a/docs/quick_tutorial/index.rst b/docs/quick_tutorial/index.rst index 29b4d8fb7..b5b7b3313 100644 --- a/docs/quick_tutorial/index.rst +++ b/docs/quick_tutorial/index.rst @@ -19,7 +19,7 @@ Contents requirements tutorial_approach - scaffolds + cookiecutters hello_world package ini diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst index 9a65d66d1..96dfc5b5f 100644 --- a/docs/quick_tutorial/ini.rst +++ b/docs/quick_tutorial/ini.rst @@ -136,7 +136,7 @@ Extra credit .. seealso:: :ref:`project_narr`, - :ref:`scaffolding_chapter`, + :ref:`cookiecutters`, :ref:`what_is_this_pserve_thing`, :ref:`environment_chapter`, :ref:`paste_chapter` diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst index cbbf7860e..0a530e91f 100644 --- a/docs/quick_tutorial/logging.rst +++ b/docs/quick_tutorial/logging.rst @@ -15,7 +15,7 @@ It's important to know what is going on inside our web application. In development we might need to collect some output. In production, we might need to detect problems when other people use the site. We need *logging*. -Fortunately Pyramid uses the normal Python approach to logging. The scaffold +Fortunately Pyramid uses the normal Python approach to logging. The project generated in your ``development.ini`` has a number of lines that configure the logging for you to some reasonable defaults. You then see messages sent by Pyramid, for example, when a new request comes in. diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst index 0ac9b4f6d..ece8cdd6f 100644 --- a/docs/quick_tutorial/request_response.rst +++ b/docs/quick_tutorial/request_response.rst @@ -26,7 +26,7 @@ part of a web application, web developers need a robust, mature set of software for web requests and returning web responses. Pyramid has always fit nicely into the existing world of Python web development -(virtual environments, packaging, scaffolding, first to embrace Python 3, and +(virtual environments, packaging, cookiecutters, first to embrace Python 3, and so on). 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>`. diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index 913e08a62..f95dac488 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -172,7 +172,7 @@ time of its release. .. code-block:: bash # Mac and Linux - $VENV/bin/pip install --upgrade pip setuptools + $ $VENV/bin/pip install --upgrade pip setuptools .. code-block:: doscon diff --git a/docs/quick_tutorial/scaffolds.rst b/docs/quick_tutorial/scaffolds.rst deleted file mode 100644 index 8712d64e9..000000000 --- a/docs/quick_tutorial/scaffolds.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. _qtut_cookiecutters: - -============================================= -Prelude: Quick Project Startup with Scaffolds -============================================= - -To ease the process of getting started, Pyramid provides *scaffolds* that -generate sample projects from templates in Pyramid and Pyramid add-ons. - - -Background -========== - -We're going to cover a lot in this tutorial, focusing on one topic at a time -and writing everything from scratch. As a warm up, though, it sure would be -nice to see some pixels on a screen. - -Like other web development frameworks, Pyramid provides a number of "scaffolds" -that generate working Python, template, and CSS code for sample applications. -In this step we'll use a built-in scaffold to let us preview a Pyramid -application, before starting from scratch on Step 1. - - -Objectives -========== - -- Use Pyramid's ``pcreate`` command to list scaffolds and make a new project. - -- Start up a Pyramid application and visit it in a web browser. - - -Steps -===== - -#. Pyramid's ``pcreate`` command can list the available scaffolds: - - .. code-block:: bash - - $ $VENV/bin/pcreate --list - Available scaffolds: - alchemy: Pyramid project using SQLAlchemy, SQLite, URL dispatch, and Jinja2 - starter: Pyramid starter project using URL dispatch and Chameleon - zodb: Pyramid project using ZODB, traversal, and Chameleon - -#. Tell ``pcreate`` to use the ``starter`` scaffold to make our project: - - .. code-block:: bash - - $ $VENV/bin/pcreate --scaffold starter scaffolds - -#. Install our project in editable mode for development in the current - directory: - - .. code-block:: bash - - $ cd scaffolds - $ $VENV/bin/pip install -e . - -#. Start up the application by pointing Pyramid's ``pserve`` command at the - project's (generated) configuration file: - - .. code-block:: bash - - $ $VENV/bin/pserve development.ini --reload - - On start up, ``pserve`` logs some output: - - .. code-block:: bash - - Starting subprocess with file monitor - Starting server in PID 72213. - Starting HTTP server on http://0.0.0.0:6543 - -#. Open http://localhost:6543/ in your browser. - -Analysis -======== - -Rather than starting from scratch, ``pcreate`` can make getting a Python -project containing a Pyramid application a quick matter. Pyramid ships with a -few scaffolds. But installing a Pyramid add-on can give you new scaffolds from -that add-on. - -``pserve`` is Pyramid's application runner, separating operational details from -your code. When you install Pyramid, a small command program called ``pserve`` -is written to your ``bin`` directory. This program is an executable Python -module. It is passed a configuration file (in this case, ``development.ini``). diff --git a/docs/quick_tutorial/scaffolds/CHANGES.txt b/docs/quick_tutorial/scaffolds/CHANGES.txt deleted file mode 100644 index 35a34f332..000000000 --- a/docs/quick_tutorial/scaffolds/CHANGES.txt +++ /dev/null @@ -1,4 +0,0 @@ -0.0 ---- - -- Initial version diff --git a/docs/quick_tutorial/scaffolds/MANIFEST.in b/docs/quick_tutorial/scaffolds/MANIFEST.in deleted file mode 100644 index 91d3f763b..000000000 --- a/docs/quick_tutorial/scaffolds/MANIFEST.in +++ /dev/null @@ -1,2 +0,0 @@ -include *.txt *.ini *.cfg *.rst -recursive-include scaffolds *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/docs/quick_tutorial/scaffolds/README.txt b/docs/quick_tutorial/scaffolds/README.txt deleted file mode 100644 index 7776dd2d5..000000000 --- a/docs/quick_tutorial/scaffolds/README.txt +++ /dev/null @@ -1 +0,0 @@ -scaffolds README diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico b/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico Binary files differdeleted file mode 100644 index 71f837c9e..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png Binary files differdeleted file mode 100644 index 1fbc873da..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png Binary files differdeleted file mode 100644 index 0596f2020..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css b/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css deleted file mode 100644 index b7c8493d8..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css +++ /dev/null @@ -1,8 +0,0 @@ -* html img, -* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none", -this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')", -this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''), -this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')", -this.runtimeStyle.backgroundImage = "none")),this.pngSet=true) -);} -#wrap{display:table;height:100%} diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png Binary files differdeleted file mode 100644 index 2369cfb7d..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css b/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css deleted file mode 100644 index 4b1c017cd..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css +++ /dev/null @@ -1,372 +0,0 @@ -html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, font, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td -{ - margin: 0; - padding: 0; - border: 0; - outline: 0; - font-size: 100%; /* 16px */ - vertical-align: baseline; - background: transparent; -} - -body -{ - line-height: 1; -} - -ol, ul -{ - list-style: none; -} - -blockquote, q -{ - quotes: none; -} - -blockquote:before, blockquote:after, q:before, q:after -{ - content: ''; - content: none; -} - -:focus -{ - outline: 0; -} - -ins -{ - text-decoration: none; -} - -del -{ - text-decoration: line-through; -} - -table -{ - border-collapse: collapse; - border-spacing: 0; -} - -sub -{ - vertical-align: sub; - font-size: smaller; - line-height: normal; -} - -sup -{ - vertical-align: super; - font-size: smaller; - line-height: normal; -} - -ul, menu, dir -{ - display: block; - list-style-type: disc; - margin: 1em 0; - padding-left: 40px; -} - -ol -{ - display: block; - list-style-type: decimal-leading-zero; - margin: 1em 0; - padding-left: 40px; -} - -li -{ - display: list-item; -} - -ul ul, ul ol, ul dir, ul menu, ul dl, ol ul, ol ol, ol dir, ol menu, ol dl, dir ul, dir ol, dir dir, dir menu, dir dl, menu ul, menu ol, menu dir, menu menu, menu dl, dl ul, dl ol, dl dir, dl menu, dl dl -{ - margin-top: 0; - margin-bottom: 0; -} - -ol ul, ul ul, menu ul, dir ul, ol menu, ul menu, menu menu, dir menu, ol dir, ul dir, menu dir, dir dir -{ - list-style-type: circle; -} - -ol ol ul, ol ul ul, ol menu ul, ol dir ul, ol ol menu, ol ul menu, ol menu menu, ol dir menu, ol ol dir, ol ul dir, ol menu dir, ol dir dir, ul ol ul, ul ul ul, ul menu ul, ul dir ul, ul ol menu, ul ul menu, ul menu menu, ul dir menu, ul ol dir, ul ul dir, ul menu dir, ul dir dir, menu ol ul, menu ul ul, menu menu ul, menu dir ul, menu ol menu, menu ul menu, menu menu menu, menu dir menu, menu ol dir, menu ul dir, menu menu dir, menu dir dir, dir ol ul, dir ul ul, dir menu ul, dir dir ul, dir ol menu, dir ul menu, dir menu menu, dir dir menu, dir ol dir, dir ul dir, dir menu dir, dir dir dir -{ - list-style-type: square; -} - -.hidden -{ - display: none; -} - -p -{ - line-height: 1.5em; -} - -h1 -{ - font-size: 1.75em; - line-height: 1.7em; - font-family: helvetica, verdana; -} - -h2 -{ - font-size: 1.5em; - line-height: 1.7em; - font-family: helvetica, verdana; -} - -h3 -{ - font-size: 1.25em; - line-height: 1.7em; - font-family: helvetica, verdana; -} - -h4 -{ - font-size: 1em; - line-height: 1.7em; - font-family: helvetica, verdana; -} - -html, body -{ - width: 100%; - height: 100%; -} - -body -{ - margin: 0; - padding: 0; - background-color: #fff; - position: relative; - font: 16px/24px NobileRegular, "Lucida Grande", Lucida, Verdana, sans-serif; -} - -a -{ - color: #1b61d6; - text-decoration: none; -} - -a:hover -{ - color: #e88f00; - text-decoration: underline; -} - -body h1, body h2, body h3, body h4, body h5, body h6 -{ - font-family: NeutonRegular, "Lucida Grande", Lucida, Verdana, sans-serif; - font-weight: 400; - color: #373839; - font-style: normal; -} - -#wrap -{ - min-height: 100%; -} - -#header, #footer -{ - width: 100%; - color: #fff; - height: 40px; - position: absolute; - text-align: center; - line-height: 40px; - overflow: hidden; - font-size: 12px; - vertical-align: middle; -} - -#header -{ - background: #000; - top: 0; - font-size: 14px; -} - -#footer -{ - bottom: 0; - background: #000 url(footerbg.png) repeat-x 0 top; - position: relative; - margin-top: -40px; - clear: both; -} - -.header, .footer -{ - width: 750px; - margin-right: auto; - margin-left: auto; -} - -.wrapper -{ - width: 100%; -} - -#top, #top-small, #bottom -{ - width: 100%; -} - -#top -{ - color: #000; - height: 230px; - background: #fff url(headerbg.png) repeat-x 0 top; - position: relative; -} - -#top-small -{ - color: #000; - height: 60px; - background: #fff url(headerbg.png) repeat-x 0 top; - position: relative; -} - -#bottom -{ - color: #222; - background-color: #fff; -} - -.top, .top-small, .middle, .bottom -{ - width: 750px; - margin-right: auto; - margin-left: auto; -} - -.top -{ - padding-top: 40px; -} - -.top-small -{ - padding-top: 10px; -} - -#middle -{ - width: 100%; - height: 100px; - background: url(middlebg.png) repeat-x; - border-top: 2px solid #fff; - border-bottom: 2px solid #b2b2b2; -} - -.app-welcome -{ - margin-top: 25px; -} - -.app-name -{ - color: #000; - font-weight: 700; -} - -.bottom -{ - padding-top: 50px; -} - -#left -{ - width: 350px; - float: left; - padding-right: 25px; -} - -#right -{ - width: 350px; - float: right; - padding-left: 25px; -} - -.align-left -{ - text-align: left; -} - -.align-right -{ - text-align: right; -} - -.align-center -{ - text-align: center; -} - -ul.links -{ - margin: 0; - padding: 0; -} - -ul.links li -{ - list-style-type: none; - font-size: 14px; -} - -form -{ - border-style: none; -} - -fieldset -{ - border-style: none; -} - -input -{ - color: #222; - border: 1px solid #ccc; - font-family: sans-serif; - font-size: 12px; - line-height: 16px; -} - -input[type=text], input[type=password] -{ - width: 205px; -} - -input[type=submit] -{ - background-color: #ddd; - font-weight: 700; -} - -/*Opera Fix*/ -body:before -{ - content: ""; - height: 100%; - float: left; - width: 0; - margin-top: -32767px; -} diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid-small.png b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid-small.png Binary files differdeleted file mode 100644 index a5bc0ade7..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid-small.png +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png Binary files differdeleted file mode 100644 index 347e05549..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif b/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif Binary files differdeleted file mode 100644 index 0341802e5..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif +++ /dev/null diff --git a/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt b/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt deleted file mode 100644 index b43a174e3..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt +++ /dev/null @@ -1,73 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal"> -<head> - <title>The Pyramid Web Framework</title> - <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> - <meta name="keywords" content="python web application" /> - <meta name="description" content="pyramid web application" /> - <link rel="shortcut icon" href="${request.static_url('scaffolds:static/favicon.ico')}" /> - <link rel="stylesheet" href="${request.static_url('scaffolds:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" /> - <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" /> - <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" /> - <!--[if lte IE 6]> - <link rel="stylesheet" href="${request.static_url('scaffolds:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" /> - <![endif]--> -</head> -<body> - <div id="wrap"> - <div id="top"> - <div class="top align-center"> - <div><img src="${request.static_url('scaffolds:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div> - </div> - </div> - <div id="middle"> - <div class="middle align-center"> - <p class="app-welcome"> - Welcome to <span class="app-name">${project}</span>, an application generated by<br/> - the Pyramid Web Framework. - </p> - </div> - </div> - <div id="bottom"> - <div class="bottom"> - <div id="left" class="align-right"> - <h2>Search documentation</h2> - <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/search.html"> - <input type="text" id="q" name="q" value="" /> - <input type="submit" id="x" value="Go" /> - </form> - </div> - <div id="right" class="align-left"> - <h2>Pyramid links</h2> - <ul class="links"> - <li> - <a href="http://pylonsproject.org">Pylons Website</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#narrative-documentation">Narrative Documentation</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#reference-material">API Documentation</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#tutorials">Tutorials</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#detailed-change-history">Change History</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#sample-applications">Sample Applications</a> - </li> - <li> - <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#support-and-development">Support and Development</a> - </li> - <li> - <a href="irc://irc.freenode.net#pyramid">IRC Channel</a> - </li> - </ul> - </div> - </div> - </div> - </div> -</body> -</html> diff --git a/docs/quick_tutorial/scaffolds/scaffolds/tests.py b/docs/quick_tutorial/scaffolds/scaffolds/tests.py deleted file mode 100644 index 4f906ffa9..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/tests.py +++ /dev/null @@ -1,17 +0,0 @@ -import unittest - -from pyramid import testing - - -class ViewTests(unittest.TestCase): - def setUp(self): - self.config = testing.setUp() - - def tearDown(self): - testing.tearDown() - - def test_my_view(self): - from .views import my_view - request = testing.DummyRequest() - info = my_view(request) - self.assertEqual(info['project'], 'scaffolds') diff --git a/docs/quick_tutorial/scaffolds/scaffolds/views.py b/docs/quick_tutorial/scaffolds/scaffolds/views.py deleted file mode 100644 index db90d8364..000000000 --- a/docs/quick_tutorial/scaffolds/scaffolds/views.py +++ /dev/null @@ -1,6 +0,0 @@ -from pyramid.view import view_config - - -@view_config(route_name='home', renderer='templates/mytemplate.pt') -def my_view(request): - return {'project': 'scaffolds'} diff --git a/docs/quick_tutorial/scaffolds/setup.py b/docs/quick_tutorial/scaffolds/setup.py deleted file mode 100644 index ec95946a5..000000000 --- a/docs/quick_tutorial/scaffolds/setup.py +++ /dev/null @@ -1,42 +0,0 @@ -import os - -from setuptools import setup, find_packages - -here = os.path.abspath(os.path.dirname(__file__)) -with open(os.path.join(here, 'README.txt')) as f: - README = f.read() -with open(os.path.join(here, 'CHANGES.txt')) as f: - CHANGES = f.read() - -requires = [ - 'pyramid', - 'pyramid_chameleon', - 'pyramid_debugtoolbar', - 'waitress', - ] - -setup(name='scaffolds', - version='0.0', - description='scaffolds', - long_description=README + '\n\n' + CHANGES, - classifiers=[ - "Programming Language :: Python", - "Framework :: Pyramid", - "Topic :: Internet :: WWW/HTTP", - "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", - ], - author='', - author_email='', - url='', - keywords='web pyramid pylons', - packages=find_packages(), - include_package_data=True, - zip_safe=False, - install_requires=requires, - tests_require=requires, - test_suite="scaffolds", - entry_points="""\ - [paste.app_factory] - main = scaffolds:main - """, - ) diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst index 49a6bfd85..8da9f71b3 100644 --- a/docs/quick_tutorial/tutorial_approach.rst +++ b/docs/quick_tutorial/tutorial_approach.rst @@ -7,25 +7,16 @@ Details, references, and deeper discussions are mentioned in "See also" notes. .. seealso:: This is an example "See also" note. -This "Getting Started" tutorial is broken into independent steps, starting with -the smallest possible "single file WSGI app" example. Each of these steps -introduce a topic and a very small set of concepts via working code. The steps -each correspond to a directory in this repo, where each step/topic/directory is -a Python package. - -To successfully run each step: - -.. code-block:: bash - - $ cd request_response - $ $VENV/bin/pip install -e . - -...and repeat for each step you would like to work on. In most cases we will -start with the results of an earlier step. Directory tree ============== +This "Getting Started" tutorial is broken into independent steps, starting with +the smallest possible "single file WSGI app" example. Each of these steps +introduces a topic and a very small set of concepts via working code. The steps +each correspond to a directory in our workspace, where each step's directory is +a Python package. + As we develop our tutorial, our directory tree will resemble the structure below: @@ -41,7 +32,15 @@ below: │── development.ini `── setup.py -Each of the first-level directories (e.g., ``request_response``) is a *Python +Each of the directories in our ``quick_tutorial`` workspace (e.g., ``request_response``) is a *Python project* (except as noted for the ``hello_world`` step). The ``tutorial`` -directory is a *Python package*. At the end of each step, we copy a previous -directory into a new directory to use as a starting point. +directory is a *Python package*. + +For most steps you will copy the previous step's directory to a new directory, and change your working directory to the new directory, then install your project: + +.. code-block:: bash + + $ cd ..; cp -r package ini; cd ini + $ $VENV/bin/pip install -e . + +For a few steps, you won't copy the previous step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``. |
