From a735d65d1d28af75371307c3d9bb52b18ee44ef0 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 9 Nov 2011 17:11:03 -0600 Subject: Made pyramid.settings.aslist public. --- docs/api/settings.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api/settings.rst b/docs/api/settings.rst index ac1cd3f9c..6b12c038c 100644 --- a/docs/api/settings.rst +++ b/docs/api/settings.rst @@ -9,4 +9,6 @@ .. autofunction:: asbool + .. autofunction:: aslist + -- cgit v1.2.3 From 0694f092797ddc4a1821e89e776adb17bc89f52d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 18 Nov 2011 10:03:16 -0500 Subject: - Fix ZODB tutorial docs to match ZODB tutorial code (I removed program name from ``scan``). --- docs/tutorials/wiki/authorization.rst | 21 ++++++--------- docs/tutorials/wiki/basiclayout.rst | 30 +++++++++++++--------- docs/tutorials/wiki/definingviews.rst | 2 +- .../wiki/src/basiclayout/tutorial/views.py | 3 +-- docs/tutorials/wiki/src/views/tutorial/views.py | 3 +-- 5 files changed, 29 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index bf88c3bd8..d900f17a3 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -42,7 +42,7 @@ declarative security checking. We need to import the new policies: Then, we'll add those policies to the configuration: .. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 20-25 + :lines: 17-22 :linenos: :language: python @@ -60,10 +60,6 @@ look like so: :linenos: :language: python -.. note:: - (Your ``config.scan('tutorial')`` needs the package name you used - instead of "tutorial", if you used a different name.) - Add ``security.py`` ~~~~~~~~~~~~~~~~~~~ @@ -77,14 +73,13 @@ content: The ``groupfinder`` function defined here is an :term:`authentication policy` "callback"; it is a callable that accepts a userid and a request. If the -userid exists in the system, the callback will -return a sequence of group identifiers (or an empty sequence if the user -isn't a member of any groups). If the userid *does not* exist in the system, -the callback will return ``None``. In a production system, user and group data will -most often come from a database, but here we use "dummy" data to represent -user and groups sources. Note that the ``editor`` user is a member of the -``group:editors`` group in our dummy group data (the ``GROUPS`` data -structure). +userid exists in the system, the callback will return a sequence of group +identifiers (or an empty sequence if the user isn't a member of any groups). +If the userid *does not* exist in the system, the callback will return +``None``. In a production system, user and group data will most often come +from a database, but here we use "dummy" data to represent user and groups +sources. Note that the ``editor`` user is a member of the ``group:editors`` +group in our dummy group data (the ``GROUPS`` data structure). Give Our Root Resource an ACL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 897775428..439da24d9 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -45,16 +45,19 @@ point happens to be the ``main`` function within the file named ``http://localhost:6543/static/`` and below. The first argument is the "name" ``static``, which indicates that the URL path prefix of the view will be ``/static``. the The second argument of this tag is the "path", - which is an :term:`asset specification`, so it finds the resources it - should serve within the ``static`` directory inside the ``tutorial`` - package. + which is a relative :term:`asset specification`, so it finds the resources + it should serve within the ``static`` directory inside the ``tutorial`` + package. The scaffold could have alternately used an *absolute* asset + specification as the path (``tutorial:static``) but it does not. #. *Line 14*. Perform a :term:`scan`. A scan will find :term:`configuration - decoration`, such as view configuration decorators - (e.g. ``@view_config``) in the source code of the ``tutorial`` package and - will take actions based on these decorators. The argument to - :meth:`~pyramid.config.Configurator.scan` is the package name to scan, - which is ``tutorial``. + decoration`, such as view configuration decorators (e.g. ``@view_config``) + in the source code of the ``tutorial`` package and will take actions based + on these decorators. We don't pass any arguments to + :meth:`~pyramid.config.Configurator.scan`, which implies that the scan + should take place in the current package (in this case, ``tutorial``). + The scaffold could have equivalently said ``config.scan('tutorial')`` but + it chose to omit the package name argument. #. *Line 15*. Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method @@ -119,7 +122,7 @@ Let's try to understand the components in this module: decoration` to perform a :term:`view configuration` registration. This view configuration registration will be activated when the application is started. It will be activated by virtue of it being found as the result - of a :term:`scan` (when Line 17 of ``__init__.py`` is run). + of a :term:`scan` (when Line 14 of ``__init__.py`` is run). The ``@view_config`` decorator accepts a number of keyword arguments. We use two keyword arguments here: ``context`` and ``renderer``. @@ -131,12 +134,15 @@ Let's try to understand the components in this module: model, this view callable will be invoked. The ``renderer`` argument names an :term:`asset specification` of - ``tutorial:templates/mytemplate.pt``. This asset specification points at - a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file + ``templates/mytemplate.pt``. This asset specification points at a + :term:`Chameleon` template which lives in the ``mytemplate.pt`` file within the ``templates`` directory of the ``tutorial`` package. And indeed if you look in the ``templates`` directory of this package, you'll see a ``mytemplate.pt`` template file, which renders the default home page - of the generated project. + of the generated project. This asset specification is *relative* (to the + view.py's current package). We could have alternately an used the + absolute asset specification ``tutorial:templates/mytemplate.pt``, but + chose to use the relative version. Since this call to ``@view_config`` doesn't pass a ``name`` argument, the ``my_view`` function which it decorates represents the "default" view diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 15b9f13ab..371cae8eb 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -293,7 +293,7 @@ replicate within the body of this guide, however it is available `online `_. This CSS file will be accessed via -e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to +e.g. ``/static/pylons.css`` by virtue of the call to ``add_static_view`` directive we've made in the ``__init__.py`` file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL. diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py index 9dfdee3f1..4265b6bf7 100644 --- a/docs/tutorials/wiki/src/basiclayout/tutorial/views.py +++ b/docs/tutorials/wiki/src/basiclayout/tutorial/views.py @@ -1,7 +1,6 @@ from pyramid.view import view_config from .models import MyModel -@view_config(context=MyModel, - renderer='templates/mytemplate.pt') +@view_config(context=MyModel, renderer='templates/mytemplate.pt') def my_view(request): return {'project':'tutorial'} diff --git a/docs/tutorials/wiki/src/views/tutorial/views.py b/docs/tutorials/wiki/src/views/tutorial/views.py index 862bd0da9..016f5b6bb 100644 --- a/docs/tutorials/wiki/src/views/tutorial/views.py +++ b/docs/tutorials/wiki/src/views/tutorial/views.py @@ -13,8 +13,7 @@ wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)") def view_wiki(context, request): return HTTPFound(location=request.resource_url(context, 'FrontPage')) -@view_config(context='.models.Page', - renderer='templates/view.pt') +@view_config(context='.models.Page', renderer='templates/view.pt') def view_page(context, request): wiki = context.__parent__ -- cgit v1.2.3 From bb18ff68d0607b1b4a088d56b3df5696eb37f146 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 21 Nov 2011 09:27:53 -0500 Subject: vb --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index c78285840..20236842b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -94,7 +94,7 @@ copyright = '%s, Agendaless Consulting' % datetime.datetime.now().year # other places throughout the built documents. # # The short X.Y version. -version = '1.2' +version = '1.3dev' # The full version, including alpha/beta/rc tags. release = version -- cgit v1.2.3 From 38369531194f8df0273378b73cb58010d89f3524 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 21 Nov 2011 09:42:35 -0500 Subject: degenshi --- docs/glossary.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/glossary.rst b/docs/glossary.rst index fc282b2da..c98637698 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -342,14 +342,13 @@ Glossary file. It was developed by Ian Bicking. Chameleon - `chameleon `_ is an attribute - language template compiler which supports both the :term:`ZPT` and - :term:`Genshi` templating specifications. It is written and - maintained by Malthe Borch. It has several extensions, such as - the ability to use bracketed (Genshi-style) ``${name}`` syntax, - even within ZPT. It is also much faster than the reference - implementations of both ZPT and Genshi. :app:`Pyramid` offers - Chameleon templating out of the box in ZPT and text flavors. + `chameleon `_ is an attribute language + template compiler which supports the :term:`ZPT` templating + specification. It is written and maintained by Malthe Borch. It has + several extensions, such as the ability to use bracketed (Mako-style) + ``${name}`` syntax. It is also much faster than the reference + implementation of ZPT. :app:`Pyramid` offers Chameleon templating out + of the box in ZPT and text flavors. ZPT The `Zope Page Template `_ -- cgit v1.2.3 From 56f1d2ea13f93b46161d12112e75125efee2120b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 21 Nov 2011 12:03:47 -0500 Subject: de-jythonify --- docs/narr/install.rst | 30 +++++------------------------- docs/narr/introduction.rst | 10 +++++----- docs/narr/templates.rst | 8 -------- 3 files changed, 10 insertions(+), 38 deletions(-) (limited to 'docs') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 66bcea706..3de4d6e27 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -9,19 +9,18 @@ Installing :app:`Pyramid` Before You Install ------------------ -You will need `Python `_ version 2.5 or better to +You will need `Python `_ version 2.6 or better to run :app:`Pyramid`. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` has been tested under Python 2.5.5, - Python 2.6.6, and Python 2.7.2. :app:`Pyramid` does not run under any - version of Python before 2.5, and does not yet run under Python 3.X. + As of this writing, :app:`Pyramid` has been tested under Python 2.6.6, + Python 2.7.2, and Python 3.2. :app:`Pyramid` does not run under any + version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, MacOS X, and FreeBSD as well as on Windows platforms. It is also -known to run on Google's App Engine, :term:`PyPy` (1.5 and 1.6), and -:term:`Jython` (2.5.2). +known to run on Google's App Engine, and :term:`PyPy` (1.6+). :app:`Pyramid` installation does not require the compilation of any C code, so you need only a Python interpreter that meets the @@ -325,25 +324,6 @@ Installing :app:`Pyramid` on Google App Engine :ref:`appengine_tutorial` documents the steps required to install a :app:`Pyramid` application on Google App Engine. -.. index:: - single: installing on Jython - -Installing :app:`Pyramid` on Jython --------------------------------------- - -:app:`Pyramid` is known to work under :term:`Jython` version 2.5.1. -Install :term:`Jython`, and then follow the installation steps for -:app:`Pyramid` on your platform described in one of the sections -entitled :ref:`installing_unix` or :ref:`installing_windows` above, -replacing the ``python`` command with ``jython`` as necessary. The -steps are exactly the same except you should use the ``jython`` -command name instead of the ``python`` command name. - -One caveat exists to using :app:`Pyramid` under Jython: the :term:`Chameleon` -templating engine does not work on Jython. However, the :term:`Mako` -templating system, which is also included with Pyramid, does work under -Jython; use it instead. - What Gets Installed ------------------- diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 547f88ef3..2387db6a7 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -808,11 +808,11 @@ Every release of Pyramid has 100% statement coverage via unit and integration tests, as measured by the ``coverage`` tool available on PyPI. It also has greater than 95% decision/condition coverage as measured by the ``instrumental`` tool available on PyPI. It is automatically tested by the -Jenkins tool on Python 2.5, Python 2.6, Python 2.7, Jython and PyPy after -each commit to its GitHub repository. Official Pyramid add-ons are held to a -similar testing standard. We still find bugs in Pyramid and its official -add-ons, but we've noticed we find a lot more of them while working on other -projects that don't have a good testing regime. +Jenkins tool on Python 2.6, Python 2.7, Python 3.2 and PyPy after each commit +to its GitHub repository. Official Pyramid add-ons are held to a similar +testing standard. We still find bugs in Pyramid and its official add-ons, +but we've noticed we find a lot more of them while working on other projects +that don't have a good testing regime. Example: http://jenkins.pylonsproject.org/ diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index fb9dd56c2..11318d9eb 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -403,14 +403,6 @@ The language definition documentation for Chameleon ZPT-style templates is available from `the Chameleon website `_. -.. warning:: - - :term:`Chameleon` only works on :term:`CPython` platforms and - :term:`Google App Engine`. On :term:`Jython` and other non-CPython - platforms, you should use Mako (see :ref:`mako_templates`) or - ``pyramid_jinja2`` instead. See - :ref:`available_template_system_bindings`. - Given a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory in your application named ``templates``, you can render the template as a :term:`renderer` like so: -- cgit v1.2.3 From f1013bebcdd013cd1cb47cf7585c0eaa34ec3b75 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Camguilhem Date: Sat, 19 Nov 2011 16:09:41 +0100 Subject: add bpython support for pshell --- docs/narr/commandline.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 0dc41e919..dc2b75ed6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -111,6 +111,7 @@ For a URL that doesn't match any views, ``pviews`` will simply print out a single: interactive shell single: IPython single: pshell + single: bpython .. _interactive_shell: @@ -284,6 +285,19 @@ standard Python interpreter shell unconditionally. development.ini#MyProject +bpython +~~~~~~~ + +If you have `bpython `_ installed in +the interpreter you use to invoke the ``pshell`` command, ``pshell`` will use +a bpython interactive shell instead of a standard Python if you pass the ``-b`` +or ``--enable-bpython`` flag to the ``pshell`` command. + +.. code-block:: text + + [chrism@vitaminf shellenv]$ ../bin/pshell --enable-bpython \ + development.ini#MyProject + .. index:: pair: routes; printing single: proutes -- cgit v1.2.3 From 2cf5d280866e8936b0fee0952c89ebde164337ee Mon Sep 17 00:00:00 2001 From: Jean-Philippe Camguilhem Date: Tue, 22 Nov 2011 00:20:07 +0100 Subject: add bpython support to pshell with raydeo remarks and design --- docs/narr/commandline.rst | 34 +++++++++++----------------------- 1 file changed, 11 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index dc2b75ed6..0f0e17ca6 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -268,34 +268,22 @@ exposed, and the request is configured to generate urls from the host .. index:: single: IPython + single: bpython -IPython -~~~~~~~ - -If you have `IPython `_ installed in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` will use -an IPython interactive shell instead of a standard Python interpreter shell. -If you don't want this to happen, even if you have IPython installed, you can -pass the ``--disable-ipython`` flag to the ``pshell`` command to use a -standard Python interpreter shell unconditionally. - -.. code-block:: text - - [chrism@vitaminf shellenv]$ ../bin/pshell --disable-ipython \ - development.ini#MyProject - - -bpython -~~~~~~~ +IPython or bpython +~~~~~~~~~~~~~~~~~~ -If you have `bpython `_ installed in -the interpreter you use to invoke the ``pshell`` command, ``pshell`` will use -a bpython interactive shell instead of a standard Python if you pass the ``-b`` -or ``--enable-bpython`` flag to the ``pshell`` command. +If you have `IPython `_ or +`bpython `_ or both installed in +the interpreter you use to invoke the ``pshell`` command, ``pshell`` will +autodiscover them and use the first respectively found in this order : +IPython, bpython, standard Python interpreter. However you could +specifically invoke one of your choice with the ``-p choice`` or +``--python-shell choice`` option. .. code-block:: text - [chrism@vitaminf shellenv]$ ../bin/pshell --enable-bpython \ + [chrism@vitaminf shellenv]$ ../bin/pshell -p ipython | bpython | python \ development.ini#MyProject .. index:: -- cgit v1.2.3 From 3bfb4068c2e17a282b53d1b7f14f653f128cced4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 26 Nov 2011 12:30:39 -0500 Subject: fix to match starter package --- docs/narr/MyProject/myproject/static/pylons.css | 15 +++-- .../MyProject/myproject/templates/mytemplate.pt | 76 +++++++--------------- 2 files changed, 31 insertions(+), 60 deletions(-) (limited to 'docs') diff --git a/docs/narr/MyProject/myproject/static/pylons.css b/docs/narr/MyProject/myproject/static/pylons.css index 33b21ac1a..c54499ddd 100644 --- a/docs/narr/MyProject/myproject/static/pylons.css +++ b/docs/narr/MyProject/myproject/static/pylons.css @@ -23,7 +23,7 @@ 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:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;} +body{margin:0;padding:0;background-color:#ffffff;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, @@ -31,19 +31,20 @@ body h2, body h3, body h4, body h5, -body h6{font-family:"Neuton","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;} +body h6{font-family:"NeutonRegular","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#373839;font-style:normal;} #wrap{min-height:100%;} #header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;vertical-align:middle;} #header{background:#000000;top:0;font-size:14px;} #footer{bottom:0;background:#000000 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,#bottom{width:100%;} -#top{color:#000000;height:230px; -background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;} +#top,#top-small,#bottom{width:100%;} +#top{color:#000000;height:230px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;} +#top-small{color:#000000;height:60px;background:#ffffff url(headerbg.png) repeat-x 0 top;position:relative;} #bottom{color:#222;background-color:#ffffff;} -.top,.middle,.bottom{width:750px;margin-right:auto;margin-left:auto;} +.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 #ffffff;border-bottom:2px solid #b2b2b2;} .app-welcome{margin-top:25px;} .app-name{color:#000000;font-weight:bold;} @@ -58,7 +59,7 @@ 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]{width:205px;} +input[type=text],input[type=password]{width:205px;} input[type=submit]{background-color:#ddd;font-weight:bold;} /*Opera Fix*/ body:before{content:"";height:100%;float:left;width:0;margin-top:-32767px;} diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt index 97f1e1aa3..ab698123e 100644 --- a/docs/narr/MyProject/myproject/templates/mytemplate.pt +++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt @@ -1,42 +1,29 @@ - - + + The Pyramid Web Application Development Framework - - - + + + +
-
- pyramid -
+
pyramid

- Welcome to ${project}, - an application generated by
+ Welcome to ${project}, an application generated by
the Pyramid web application development framework.

@@ -45,62 +32,45 @@

Search documentation

-
- - -
+
+ + +
-- cgit v1.2.3 From 6772a25160b0c996ae6e7baa012199b606407db4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 26 Nov 2011 14:56:29 -0500 Subject: output warning to use populate command to console after alchemy scaffold rendering; emit logging statements when populate is run --- docs/tutorials/wiki/basiclayout.rst | 4 +- docs/tutorials/wiki2/basiclayout.rst | 159 +++++++++++++-------- docs/tutorials/wiki2/definingmodels.rst | 5 + docs/tutorials/wiki2/installation.rst | 148 ++++++++++++++++--- .../wiki2/src/basiclayout/tutorial/__init__.py | 11 +- .../wiki2/src/basiclayout/tutorial/views.py | 12 +- 6 files changed, 245 insertions(+), 94 deletions(-) (limited to 'docs') diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 439da24d9..56f817a85 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -10,8 +10,8 @@ The source code for this tutorial stage can be browsed via `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/ `_. -App Startup with ``__init__.py`` --------------------------------- +Appplication Configuration with ``__init__.py`` +------------------------------------------------ A directory on disk can be turned into a Python :term:`package` by containing an ``__init__.py`` file. Even if empty, this marks a directory as a Python diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index db8ab1fbe..dc5664c5b 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -2,82 +2,96 @@ Basic Layout ============ -The starter files generated by the ``alchemy`` scaffold are -basic, but they provide a good orientation for the high-level patterns common -to most :term:`url dispatch` -based :app:`Pyramid` projects. +The starter files generated by the ``alchemy`` scaffold are very basic, but +they provide a good orientation for the high-level patterns common to most +:term:`url dispatch` -based :app:`Pyramid` projects. The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/basiclayout/ `_. -App Startup with ``__init__.py`` --------------------------------- +Application Configuration with ``__init__.py`` +---------------------------------------------- A directory on disk can be turned into a Python :term:`package` by containing an ``__init__.py`` file. Even if empty, this marks a directory as a Python -package. We use ``__init__.py`` both as a package marker and to contain -configuration code. +package. We use ``__init__.py`` both as a marker indicating the directory +it's contained within is a package, and to contain configuration code. Our +``__init__.py`` file will look like this: -The generated ``development.ini`` file is read by ``pserve`` which looks for -the application module in the ``use`` variable of the ``app:main`` -section. The *entry point* is defined in the Setuptools configuration of this -module, specifically in the ``setup.py`` file. For this tutorial, the *entry -point* is defined as ``tutorial:main`` and points to a function named -``main``. + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :linenos: + :language: py -First we need some imports to support later code: +Let's go over this piece-by-piece. First, we need some imports to support +later code: .. literalinclude:: src/basiclayout/tutorial/__init__.py :end-before: main :linenos: :language: py -Next we define the main function and create a SQLAlchemy database engine from -the ``sqlalchemy.`` prefixed settings in the ``development.ini`` file's -``[app:main]`` section. This will be a URI (something like -``sqlite://``): +``__init__.py`` defines a function named ``main``. Here is the entirety of +the ``main`` function we've defined in our ``__init__.py``: + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :pyobject: main + :linenos: + :language: py + +When you invoke the ``pserve development.ini`` command, the ``main`` function +above is executed. It accepts some settings and returns a :term:`WSGI` +application. You can read :ref:`startup_chapter` for details about *how* +this function is found and called when you run ``pserve``, but for purposes +of brevity, we'll elide the details here. + +The main function first creates a SQLAlchemy database engine using +``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the +``development.ini`` file's ``[app:main]`` section. This will be a URI +(something like ``sqlite://``): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 6-9 + :lines: 9 :linenos: :language: py -We then initialize our SQL database using SQLAlchemy, passing -it the engine: +``main`` then initializes our SQL database using SQLAlchemy, passing it the +engine: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 10 :language: py -The next step is to construct a :term:`Configurator`: +The next step of ``main`` is to construct a :term:`Configurator` object: .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 11 :language: py ``settings`` is passed to the Configurator as a keyword argument with the -dictionary values passed by PasteDeploy as the ``**settings`` argument. This -will be a dictionary of settings parsed from the ``.ini`` file, which -contains deployment-related values such as ``pyramid.reload_templates``, +dictionary values passed as the ``**settings`` argument. This will be a +dictionary of settings parsed from the ``.ini`` file, which contains +deployment-related values such as ``pyramid.reload_templates``, ``db_string``, etc. -We now can call :meth:`pyramid.config.Configurator.add_static_view` with the -arguments ``static`` (the name), and ``tutorial:static`` (the path): +``'main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with +two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py :lines: 12 :language: py -This registers a static resource view which will match any URL that starts with -``/static/``. This will serve up static resources for us from within the -``static`` directory of our ``tutorial`` package, in this case, -via ``http://localhost:6543/static/`` and below. With this declaration, -we're saying that any URL that starts with ``/static`` should go to the -static view; any remainder of its path (e.g. the ``/foo`` in -``/static/foo``) will be used to compose a path to a static file resource, -such as a CSS file. +This registers a static resource view which will match any URL that starts +with the prefix ``/static`` (by virtue of the first argument to add_static +view). This will serve up static resources for us from within the ``static`` +directory of our ``tutorial`` package, in this case, via +``http://localhost:6543/static/`` and below (by virtue of the second argument +to add_static_view). With this declaration, we're saying that any URL that +starts with ``/static`` should go to the static view; any remainder of its +path (e.g. the ``/foo`` in ``/static/foo``) will be used to compose a path to +a static file resource, such as a CSS file. -Using the configurator we can also register a :term:`route configuration` +Using the configurator ``main`` also registers a :term:`route configuration` via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: @@ -88,44 +102,71 @@ used when the URL is ``/``: Since this route has a ``pattern`` equalling ``/`` it is the route that will be matched when the URL ``/`` is visted, e.g. ``http://localhost:6543/``. -Mapping the ``home`` route to code is done by registering a view. You will -use :meth:`pyramid.config.Configurator.add_view` in :term:`URL dispatch` to -register views for the routes, mapping your patterns to code: +``main`` next calls the ``scan`` method of the configurator, which will +recursively scan our ``tutorial`` package, looking for ``@view_config`` (and +other special) decorators. When it finds a ``@view_config`` decorator, a +view configuration will be registered, which will allow one of our +application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 14-15 + :lines: 14 :language: py -The first positional ``add_view`` argument ``tutorial.views.my_view`` is the -dotted name to a *function* we write (generated by the -``alchemy`` scaffold) that is given a ``request`` object and -which returns a response or a dictionary. This view also names a -``renderer``, which is a template which lives in the ``templates`` -subdirectory of the package. When the ``tutorial.views.my_view`` view -returns a dictionary, a :term:`renderer` will use this template to create a -response. - -Finally, we use the :meth:`pyramid.config.Configurator.make_wsgi_app` -method to return a :term:`WSGI` application: +Finally, ``main`` is finished configuring things, so it uses the +:meth:`pyramid.config.Configurator.make_wsgi_app` method to return a +:term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 16 + :lines: 15 :language: py -Our final ``__init__.py`` file will look like this: +View Declarations via ``views.py`` +---------------------------------- - .. literalinclude:: src/basiclayout/tutorial/__init__.py +Mapping a :term:`route` to code that will be executed when that route's +pattern matches is done by registering a :term:`view configuration`. Our +application uses the :meth:`pyramid.view.view_config` decorator to map view +callables to each route, thereby mapping URL patterns to code. + +Here is the code in the ``views.py`` file within our package: + + .. literalinclude:: src/basiclayout/tutorial/views.py :linenos: :language: py +The important part to point out here is the ``@view_config`` decorator. In +fact, ``@view_config`` is so important that we're going to ignore the rest of +the code in the module at this point just to explain it. The +``@view_config`` decorator associates the function it decorates with a +:term:`view configuration`. The view configuration names a ``route_name`` +(``home``), and names a ``renderer``, which is a template which lives in the +``templates`` subdirectory of the package. + +As the result of this view configuration, when the pattern associated with +the view named ``home`` is matched during a request, the function named +``my_view`` will be executed. The the function named ``my_view`` returns a +dictionary; the renderer will use the ``templates/mytemplate.pt`` template to +create a response based on the values in the dictionary. + +Note that the decorated function named ``my_view`` accepts a single argument +named ``request``. This is the standard call signature for a Pyramid +:term:`view callable`. + +Remember in our ``__init__.py`` when we executed the +:meth:`pyramid.config.Configurator.scan` method, e.g. ``config.scan()``? The +purpose of calling the scan method was to find and process this +``@view_config`` decorator in order to create a view configuration within our +application. Without being processed by ``scan``, the decorator effectively +does nothing. ``@view_config`` is inert without being detected via a +:term:`scan`. + Content Models with ``models.py`` --------------------------------- -In a SQLAlchemy-based application, a *model* object is an object -composed by querying the SQL database which backs an application. -SQLAlchemy is an "object relational mapper" (an ORM). The -``models.py`` file is where the ``alchemy`` scaffold -put the classes that implement our models. +In a SQLAlchemy-based application, a *model* object is an object composed by +querying the SQL database. SQLAlchemy is an "object relational mapper" (an +ORM). The ``models.py`` file is where the ``alchemy`` scaffold put the +classes that implement our models. Let's take a look. First, we need some imports to support later code. diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 083ec0aa8..bc2c2de5f 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -80,6 +80,11 @@ something like this: :linenos: :language: python +Populating the Database +----------------------- + +XXX The ``populate_tutorial`` :term:`console script``. + Viewing the Application in a Browser ------------------------------------ diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 147f7f563..381e0a90f 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -40,13 +40,6 @@ Preparation, UNIX $ bin/easy_install pyramid -#. Use ``easy_install`` to install various packages from PyPI. - - .. code-block:: text - - $ bin/easy_install docutils nose coverage zope.sqlalchemy \ - SQLAlchemy pyramid_tm - Preparation, Windows -------------------- @@ -69,14 +62,6 @@ Preparation, Windows c:\pyramidtut> Scripts\easy_install pyramid -#. Use ``easy_install`` to install various packages from PyPI. - - .. code-block:: text - - c:\pyramidtut> Scripts\easy_install docutils \ - nose coverage zope.sqlalchemy SQLAlchemy pyramid_tm - - .. _sql_making_a_project: Making a Project @@ -108,6 +93,13 @@ On Windows: startup problems, try putting both the virtualenv and the project into directories that do not contain spaces in their paths. +Success executing this command will end with a line to the console something +like:: + + Please run the "populate_tutorial" script to set up the SQL + database before starting the application (e.g. + "$myvirtualenv/bin/populate_tutorial development.ini".) + Installing the Project in "Development Mode" ============================================ @@ -131,6 +123,11 @@ On Windows: c:\pyramidtut> cd tutorial c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop +Success executing this command will end with a line to the console something +like:: + + Finished processing dependencies for tutorial==0.0 + .. _sql_running_tests: Running the Tests @@ -151,6 +148,14 @@ On Windows: c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q +For a successful test run, you should see output like this:: + + . + ---------------------------------------------------------------------- + Ran 1 test in 0.094s + + OK + Exposing Test Coverage Information ================================== @@ -191,8 +196,24 @@ On Windows: 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. +If successful, you will see output something like this:: + + . + Name Stmts Miss Cover Missing + ------------------------------------------------ + tutorial 11 7 36% 9-15 + tutorial.models 17 0 100% + tutorial.scripts 0 0 100% + tutorial.tests 24 0 100% + tutorial.views 6 0 100% + ------------------------------------------------ + TOTAL 58 7 88% + ---------------------------------------------------------------------- + Ran 1 test in 0.459s + + OK + +Looks like our package doesn't quite have 100% test coverage. Starting the Application ======================== @@ -211,11 +232,96 @@ On Windows: c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload -Visit the Application in a Browser -================================== +If successful, you will see something like this on your console:: + + Starting subprocess with file monitor + Starting server in PID 8966. + Starting HTTP server on http://0.0.0.0:6543 + +This means the server is ready to accept requests. + +Populating the Database +======================= + +In a web browser, visit ``http://localhost:6543/``. + +You will see an error page with a title something like this:: + + sqlalchemy.exc.OperationalError + + OperationalError: (OperationalError) no such table: models ... + +Oh no! Something isn't working! + +This happens because we haven't populated the database with any table +information yet. We need to use the ``populate_tutorial`` :term:`console +script` to populate our database before we can see the page render correctly. + +Stop the running Pyramid application by pressing ``ctrl-C`` in the console. +Make sure you're still in the ``tutorial`` directory (the directory with a +``development.ini`` in it) and type the following command: + +On UNIX: + +.. code-block:: text + + $ ../bin/populate_tutorial development.ini + +On Windows: + +.. code-block:: text + + c:\pyramidtut\tutorial> ..\Scripts\populate_tutorial development.ini + +The output to your console should be something like this:: + + 2011-11-26 14:42:25,012 INFO [sqlalchemy.engine.base.Engine][MainThread] + PRAGMA table_info("models") + 2011-11-26 14:42:25,013 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2011-11-26 14:42:25,013 INFO [sqlalchemy.engine.base.Engine][MainThread] + CREATE TABLE models ( + id INTEGER NOT NULL, + name VARCHAR(255), + value INTEGER, + PRIMARY KEY (id), + UNIQUE (name) + ) + 2011-11-26 14:42:25,013 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2011-11-26 14:42:25,135 INFO [sqlalchemy.engine.base.Engine][MainThread] + COMMIT + 2011-11-26 14:42:25,137 INFO [sqlalchemy.engine.base.Engine][MainThread] + BEGIN (implicit) + 2011-11-26 14:42:25,138 INFO [sqlalchemy.engine.base.Engine][MainThread] + INSERT INTO models (name, value) VALUES (?, ?) + 2011-11-26 14:42:25,139 INFO [sqlalchemy.engine.base.Engine][MainThread] + (u'one', 1) + 2011-11-26 14:42:25,140 INFO [sqlalchemy.engine.base.Engine][MainThread] + COMMIT + +Success! You should now have a ``tutorial.db`` file in your current working +directory. This will be a SQLite database with a single table defined in it +(``models``). + +Starting the Application (Again) +================================ + +Start the application again. + +On UNIX: + +.. code-block:: text + + $ ../bin/pserve development.ini --reload + +On Windows: + +.. code-block:: text + + c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload -In a browser, visit ``http://localhost:6543/``. You will see the -generated application's default page. +At this point, when you visit ``http://localhost:6543/`` in your web browser, +you will no longer see an error; instead 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 diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py index b4038de3c..1f2cfd307 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py @@ -1,18 +1,15 @@ from pyramid.config import Configurator from sqlalchemy import engine_from_config -from tutorial.models import initialize_sql +from .models import DBSession def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ engine = engine_from_config(settings, 'sqlalchemy.') - initialize_sql(engine) + DBSession.configure(bind=engine) config = Configurator(settings=settings) - config.add_static_view('static', 'tutorial:static', cache_max_age=3600) + config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('home', '/') - config.add_view('tutorial.views.my_view', route_name='home', - renderer='templates/mytemplate.pt') + config.scan() return config.make_wsgi_app() - - diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py index e550e3257..631af9b6a 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/views.py @@ -1,7 +1,9 @@ -from tutorial.models import DBSession -from tutorial.models import MyModel +from pyramid.view import view_config +from .models import DBSession +from .models import MyModel + +@view_config(route_name='home', renderer='templates/mytemplate.pt') def my_view(request): - dbsession = DBSession() - root = dbsession.query(MyModel).filter(MyModel.name==u'root').first() - return {'root':root, 'project':'tutorial'} + one = DBSession.query(MyModel).filter(MyModel.name==u'root').first() + return {'one':one, 'project':'tutorial'} -- cgit v1.2.3