Merge pull request #2532 from stevepiercy/1.7-branch

Steve Piercy

2016-04-26 3bf34333034ef7724828570a2bb77f3b12a64bb7

Merge pull request #2532 from stevepiercy/1.7-branch

put doctest into make command

 docs/Makefile

@@ -12,16 +12,20 @@
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
.PHONY: help clean html text web pickle htmlhelp latex latexpdf changes linkcheck epub doctest

help:
    @echo "Please use \`make <target>' where <target> is one of"
    @echo "  html      to make standalone HTML files"
    @echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
    @echo "  htmlhelp  to make HTML files and a HTML help project"
    @echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
    @echo "  changes   to make an overview over all changed/added/deprecated items"
    @echo "  linkcheck to check all external links for integrity"
    @echo "  html       to make standalone HTML files"
    @echo "  text       to make text files"
    @echo "  pickle     to make pickle files (usable by e.g. sphinx-web)"
    @echo "  htmlhelp   to make HTML files and a HTML help project"
    @echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
    @echo "  latexpdf   to make LaTeX files and run them through pdflatex"
    @echo "  changes    to make an overview over all changed/added/deprecated items"
    @echo "  linkcheck  to check all external links for integrity"
    @echo "  epub       to make an epub"
    @echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

clean:
    -rm -rf $(BUILDDIR)/*
@@ -90,3 +94,7 @@
    @echo
    @echo "Build finished. The epub file is in $(BUILDDIR)/epub."

doctest:
    $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
    @echo "Testing of doctests in the sources finished, look at the " \
          "results in $(BUILDDIR)/doctest/output.txt."

 docs/narr/hooks.rst

@@ -300,13 +300,38 @@
``reify=True``. This way, we eliminate the overhead of running the function
multiple times.

.. testsetup:: group1

   from pyramid.config import Configurator


   def total(request, *args):
       return sum(args)


   def prop(request):
       print("getting the property")
       return "the property"



   config = Configurator()
   config.add_request_method(total)
   config.add_request_method(prop, reify=True)
   config.commit()

   from pyramid.scripting import prepare
   request = prepare(registry=config.registry)["request"]

.. doctest:: group1

   >>> request.total(1, 2, 3)
   6
   >>> request.prop
   getting the property
   the property
   'the property'
   >>> request.prop
   the property
   'the property'

To not cache the result of ``request.prop``, set ``property=True`` instead of
``reify=True``.
@@ -338,13 +363,42 @@

We attach and cache an object named ``extra`` to the ``request`` object.

.. testsetup:: group2

   from pyramid.config import Configurator
   from pyramid.decorator import reify

   class ExtraStuff(object):

       def __init__(self, request):
           self.request = request

       def total(self, *args):
           return sum(args)

       # use @property if you don't want to cache the result
       @reify
       def prop(self):
           print("getting the property")
           return "the property"

   config = Configurator()
   config.add_request_method(ExtraStuff, 'extra', reify=True)
   config.commit()

   from pyramid.scripting import prepare
   request = prepare(registry=config.registry)["request"]

.. doctest:: group2

   >>> request.extra.total(1, 2, 3)
   6
   >>> request.extra.prop
   getting the property
   the property
   'the property'
   >>> request.extra.prop
   the property
   'the property'


.. index::
   single: response factory

 docs/narr/sessions.rst

@@ -260,19 +260,28 @@

.. method:: pop_flash(queue='')

>>> request.session.flash('info message')
>>> request.session.pop_flash()
['info message']
.. testsetup::

   from pyramid import testing
   request = testing.DummyRequest()

.. doctest::

   >>> request.session.flash('info message')
   >>> request.session.pop_flash()
   ['info message']

Calling ``session.pop_flash()`` again like above without a corresponding call
to ``session.flash()`` will return an empty list, because the queue has already
been popped.

>>> request.session.flash('info message')
>>> request.session.pop_flash()
['info message']
>>> request.session.pop_flash()
[]
.. doctest::

   >>> request.session.flash('info message')
   >>> request.session.pop_flash()
   ['info message']
   >>> request.session.pop_flash()
   []

.. index::
   single: session.peek_flash
@@ -287,15 +296,17 @@

.. method:: peek_flash(queue='')

>>> request.session.flash('info message')
>>> request.session.peek_flash()
['info message']
>>> request.session.peek_flash()
['info message']
>>> request.session.pop_flash()
['info message']
>>> request.session.peek_flash()
[]
.. doctest::

   >>> request.session.flash('info message')
   >>> request.session.peek_flash()
   ['info message']
   >>> request.session.peek_flash()
   ['info message']
   >>> request.session.pop_flash()
   ['info message']
   >>> request.session.peek_flash()
   []

.. index::
   single: preventing cross-site request forgery attacks

 pyramid/decorator.py

@@ -1,4 +1,4 @@
import functools
from functools import update_wrapper


class reify(object):
@@ -8,28 +8,36 @@
    replacing the function it decorates with an instance variable.  It is, in
    Python parlance, a non-data descriptor.  An example:

    .. code-block:: python
    .. testsetup::

       class Foo(object):
           @reify
           def jammy(self):
               print('jammy called')
               return 1
        from pyramid.decorator import reify

        class Foo(object):
            @reify
            def jammy(self):
                print('jammy called')
                return 1

    And usage of Foo:

    >>> f = Foo()
    >>> v = f.jammy
    'jammy called'
    >>> print(v)
    1
    >>> f.jammy
    1
    >>> # jammy func not called the second time; it replaced itself with 1
    .. doctest::

        >>> f = Foo()
        >>> v = f.jammy
        jammy called
        >>> print(v)
        1
        >>> f.jammy
        1
        >>> # jammy func not called the second time; it replaced itself with 1
        >>> # Note: reassignment is possible
        >>> f.jammy = 2
        >>> f.jammy
        2
    """
    def __init__(self, wrapped):
        self.wrapped = wrapped
        functools.update_wrapper(self, wrapped)
        update_wrapper(self, wrapped)

    def __get__(self, inst, objtype=None):
        if inst is None:

 tox.ini

@@ -57,7 +57,7 @@
whitelist_externals = make
commands =
    pip install pyramid[docs]
    make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E"
    make -C docs doctest html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E"

# we separate coverage into its own testenv because a) "last run wins" wrt
# cobertura jenkins reporting and b) pypy and jython can't handle any