diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 22 | ||||
| -rw-r--r-- | docs/narr/hooks.rst | 62 | ||||
| -rw-r--r-- | docs/narr/sessions.rst | 45 |
3 files changed, 101 insertions, 28 deletions
diff --git a/docs/Makefile b/docs/Makefile index 546deb30a..411ff35df 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,16 +12,20 @@ PAPEROPT_a4 = -D latex_paper_size=a4 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 @@ epub: @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." diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index b776f99e8..150eca944 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -300,13 +300,38 @@ added as a property and its result is cached per-request by setting ``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 @@ Here is an example of passing a class to ``Configurator.add_request_method``: 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 diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 7e961f5e8..a1319e45f 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -260,19 +260,28 @@ added to the flash queue, and empties the queue. .. 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 @@ flash storage. .. 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 |