Merge branch 'master' of github.com:Pylons/pyramid

Chris McDonough

2013-01-12 3ac960c7d1a77d89d84931c34dbed5ab57cdbe66

Merge branch 'master' of github.com:Pylons/pyramid

 HACKING.txt

@@ -94,7 +94,7 @@
--------------

- To run tests for Pyramid on a single Python version, run ``python setup.py
  test`` against the using the Python interpreter from virtualenv into which
  test`` against the Python interpreter from virtualenv into which
  you've ``setup.py develop``-ed Pyramid.

- To run the full set of Pyramid tests on all platforms, install ``tox``

 docs/api/path.rst

@@ -9,8 +9,7 @@

       A constant used by the constructor of
       :class:`pyramid.path.DottedNameResolver` and
       :class:`pyramid.path.AssetResolver` (see their docstrings for more
       info).
       :class:`pyramid.path.AssetResolver`.

    .. autoclass:: DottedNameResolver
       :members:

 docs/designdefense.rst

@@ -38,7 +38,7 @@

Implementations of these features were *required* to allow the :app:`Pyramid`
authors to build the bread-and-butter CMS-type systems for customers in the
way they were accustomed to building them.  No other system save Zope itself
way they were accustomed to building them.  No other system, save for Zope itself,
had such features.  And Zope itself was beginning to show signs of its age.
We were becoming hampered by consequences of its early design mistakes.
Zope's lack of documentation was also difficult to work around: it was hard
@@ -55,7 +55,7 @@
particular, :term:`URL dispatch` is a more direct mechanism to map URLs to
code.

So although we couldn't find a framework save for Zope that fit our needs,
So, although we couldn't find a framework, save for Zope, that fit our needs,
and while we incorporated a lot of Zope ideas into BFG, we also emulated the
features we found compelling in other frameworks (such as :term:`url
dispatch`).  After the initial public release of BFG, as time went on,
@@ -1536,7 +1536,7 @@
.. code-block:: python
   :linenos:

   from pyramid.response import Response         # explicit response, no TL
   from pyramid.response import Response # explicit response, no thread local
   from wsgiref.simple_server import make_server # explicitly WSGI

   def hello_world(request):  # accepts a request; no request thread local reqd

 docs/glossary.rst

@@ -921,7 +921,7 @@

   PyPy
     PyPy is an "alternative implementation of the Python
     language":http://pypy.org/
     language": http://pypy.org/

   tween
     A bit of code that sits between the Pyramid router's main request

 docs/index.rst

@@ -138,6 +138,11 @@
Sample Applications
===================

.. note::

   These applications run only on Python 2.x, and so do some of their
   dependencies.

`cluegun <https://github.com/Pylons/cluegun>`_ is a simple pastebin
application based on Rocky Burt's `ClueBin
<http://pypi.python.org/pypi/ClueBin/0.2.3>`_.  It demonstrates form

 docs/narr/install.rst

@@ -150,32 +150,21 @@
``import setuptools`` within the Python interpreter you'd like to run
:app:`Pyramid` under.

Here's the output you'll expect if setuptools or distribute is already
installed:
The following command will not display anything if setuptools or distribute is
already installed:

.. code-block:: text

   [chrism@thinko docs]$ python2.7
   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
   [GCC 4.6.3] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import setuptools
   >>> 
   $ python2.7 -c 'import setuptools'

Here's the output you can expect if setuptools or distribute is not already
installed:
Running the same command will yield the following output if setuptools or
distribute is not yet installed:

.. code-block:: text

   [chrism@thinko docs]$ python2.7
   Python 2.7.3 (default, Aug  1 2012, 05:14:39) 
   [GCC 4.6.3] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import setuptools
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ImportError: No module named setuptools
   >>>

If ``import setuptools`` raises an :exc:`ImportError` as it does above, you
will need to install setuptools or distribute manually.  Note that above

 docs/narr/introduction.rst

@@ -101,7 +101,7 @@
framework should be able to be good at both.  Pyramid strives to be that kind
of framework.

To this end, Pyramid provides a set of features, that, combined, are unique
To this end, Pyramid provides a set of features that, combined, are unique
amongst Python web frameworks.  Lots of other frameworks contain some
combination of these features; Pyramid of course actually stole many of them
from those other frameworks.  But Pyramid is the only one that has all of
@@ -475,7 +475,7 @@
and when the route is matched, you can shuffle off the request to one view if
the request method is GET, another view if the request method is POST, etc.
A system known as "view predicates" allows for this.  Request method matching
is the very most basic thing you can do with a view predicate.  You can also
is the most basic thing you can do with a view predicate.  You can also
associate views with other request parameters such as the elements in the
query string, the Accept header, whether the request is an XHR request or
not, and lots of other things.  This feature allows you to keep your

 docs/narr/upgrading.rst

@@ -206,7 +206,7 @@
Upgrading to the Very Latest Pyramid Release
--------------------------------------------

When you upgrade your application to the very most recent Pyramid release,
When you upgrade your application to the most recent Pyramid release,
it's advisable to upgrade step-wise through each most recent minor release,
beginning with the one that you know your application currently runs under,
and ending on the most recent release.  For example, if your application is

 docs/narr/viewconfig.rst

@@ -834,7 +834,7 @@
.. code-block:: python
   :linenos:

   from pyramid.view import view_config
   from pyramid.view import view_defaults
   from pyramid.response import Response
   from pyramid.config import Configurator


 docs/tutorials/wiki2/authorization.rst

@@ -14,7 +14,7 @@

We will also add a login page and a logout link on all the
pages.  The login page will be shown when a user is denied
access to any of the views that require a permission, instead of
access to any of the views that require permission, instead of
a default "403 Forbidden" page.

We will implement the access control with the following steps:
@@ -62,7 +62,7 @@
- If the userid *does not* exist in the system, it will
  return ``None``.

For example, ``groupfinder('editor', request )`` returns ['group:editor'],
For example, ``groupfinder('editor', request )`` returns ``['group:editor']``,
``groupfinder('viewer', request)`` returns [], and ``groupfinder('admin', request)``
returns ``None``.  We will use ``groupfinder()`` as an :term:`authentication policy`
"callback" that will provide the :term:`principal` or principals
@@ -151,12 +151,12 @@

(Only the highlighted lines need to be added.)

We are enabling an ``AuthTktAuthenticationPolicy``, it is based in an
auth ticket that may be included in the request, and an
``ACLAuthorizationPolicy`` that uses an ACL to determine the allow or deny
outcome for a view.
We are enabling an ``AuthTktAuthenticationPolicy``, which is based in an
auth ticket that may be included in the request.
We are also enabling an ``ACLAuthorizationPolicy``, which uses an ACL to
determine the *allow* or *deny* outcome for a view.

Note that the :class:`pyramid.authentication.AuthTktAuthenticationPolicy`
Note that the :class:`~pyramid.authentication.AuthTktAuthenticationPolicy`
constructor accepts two arguments: ``secret`` and ``callback``.  ``secret`` is
a string representing an encryption key used by the "authentication ticket"
machinery represented by this policy: it is required.  The ``callback`` is the
@@ -303,9 +303,8 @@

(Only the highlighted line needs to be added.)

:meth:`~pyramid.security.authenticated_userid()` will return None
if the user is not authenticated, or some user id it the user
is authenticated.
The :meth:`~pyramid.security.authenticated_userid` method will return None
if the user is not authenticated.

Add a "Logout" link when logged in
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 docs/tutorials/wiki2/background.rst

@@ -11,9 +11,8 @@
machine with development tools (Mac OS X with XCode, any Linux or BSD
variant, etc) *or* a Windows system of any kind.

.. warning::
.. note::

  This tutorial has been written for Python 2.  It is unlikely to work
  without modification under Python 3.
  This tutorial runs on both Python 2 and 3 without modification.

Have fun!

 docs/tutorials/wiki2/basiclayout.rst

@@ -97,7 +97,7 @@
``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
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.

 docs/tutorials/wiki2/definingmodels.rst

@@ -31,7 +31,7 @@

(The highlighted lines are the ones that need to be changed.)

The first thing we've done is to do is remove the stock ``MyModel`` class
The first thing we've done is remove the stock ``MyModel`` class
from the generated ``models.py`` file.  The ``MyModel`` class is only a
sample and we're not going to use it.

@@ -77,25 +77,15 @@

(Only the highlighted lines need to be changed.)

Reinitializing the Database
---------------------------
Installing the Project and re-initializing the Database
-------------------------------------------------------

Redo the steps in :ref:`installing_project_in_dev_mode`.

Because our model has changed, in order to reinitialize the database, we need
to rerun the ``initialize_tutorial_db`` command to pick up the changes you've made
to both the models.py file and to the initializedb.py file.  From the root of the
``tutorial`` project, directory execute the following commands.

On UNIX:

.. code-block:: text

   $ ../bin/initialize_tutorial_db development.ini

On Windows:

.. code-block:: text

   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
to both the models.py file and to the initializedb.py file.
See :ref:`initialize_db_wiki2` for instructions.

Success will look something like this::


 docs/tutorials/wiki2/installation.rst

@@ -66,6 +66,9 @@
   startup problems, try putting both the virtualenv and the project
   into directories that do not contain spaces in their paths.


.. _installing_project_in_dev_mode:

Installing the Project in "Development Mode"
============================================

@@ -159,7 +162,7 @@

.. code-block:: text

   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
         --cover-erase --with-coverage

If successful, you will see output something like this::
@@ -181,6 +184,9 @@

Looks like our package doesn't quite have 100% test coverage.


.. _initialize_db_wiki2:

Initializing the Database
=========================


 pyramid/testing.py

@@ -476,7 +476,7 @@
    return config

def tearDown(unhook_zca=True):
    """Undo the effects :func:`pyramid.testing.setUp`.  Use this
    """Undo the effects of :func:`pyramid.testing.setUp`.  Use this
    function in the ``tearDown`` method of a unit test that uses
    :func:`pyramid.testing.setUp` in its ``setUp`` method.