From de3d0c784198796285ddc4c80e45b8082ecab9e2 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 18 Apr 2016 10:15:32 -0500 Subject: replace pyramid.require_default_csrf setting with config.set_default_csrf_options --- docs/narr/extconfig.rst | 1 + docs/narr/introspector.rst | 25 +++++++++++++++ docs/narr/sessions.rst | 76 ++++++++++++++++++++++++---------------------- 3 files changed, 66 insertions(+), 36 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index af7d0a349..babfa0a98 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -261,6 +261,7 @@ Pre-defined Phases - :meth:`pyramid.config.Configurator.add_view_predicate` - :meth:`pyramid.config.Configurator.add_view_deriver` - :meth:`pyramid.config.Configurator.set_authorization_policy` +- :meth:`pyramid.config.Configurator.set_default_csrf_options` - :meth:`pyramid.config.Configurator.set_default_permission` - :meth:`pyramid.config.Configurator.set_view_mapper` diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index 98315ac9f..c9fecd4f4 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -337,6 +337,31 @@ introspectables in categories not described here. The permission name passed to ``set_default_permission``. +``default csrf options`` + + There will be one and only one introspectable in the ``default csrf options`` + category. It represents a call to the + :meth:`pyramid.config.Configurator.set_default_csrf_options` method. It + will have the following data. + + ``require_csrf`` + + The default value for ``require_csrf`` if left unspecified on calls to + :meth:`pyramid.config.Configurator.add_view`. + + ``token`` + + The name of the token searched in ``request.POST`` to find a valid CSRF + token. + + ``header`` + + The name of the request header searched to find a valid CSRF token. + + ``safe_methods`` + + The list of HTTP methods considered safe and exempt from CSRF checks. + ``views`` Each introspectable in the ``views`` category represents a call to diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index 7cf96ac7d..bfc908396 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -396,13 +396,13 @@ named ``X-CSRF-Token``. .. code-block:: python - from pyramid.session import check_csrf_token + from pyramid.session import check_csrf_token - def myview(request): - # Require CSRF Token - check_csrf_token(request) + def myview(request): + # Require CSRF Token + check_csrf_token(request) - # ... + # ... .. _auto_csrf_checking: @@ -414,41 +414,45 @@ Checking CSRF Tokens Automatically :app:`Pyramid` supports automatically checking CSRF tokens on requests with an unsafe method as defined by RFC2616. Any other request may be checked manually. This feature can be turned on globally for an application using the -``pyramid.require_default_csrf`` setting. - -If the ``pyramid.required_default_csrf`` setting is a :term:`truthy string` or -``True`` then the default CSRF token parameter will be ``csrf_token``. If a -different token is desired, it may be passed as the value. Finally, a -:term:`falsey string` or ``False`` will turn off automatic CSRF checking -globally on every request. - -No matter what, CSRF checking may be explicitly enabled or disabled on a -per-view basis using the ``require_csrf`` view option. This option is of the -same format as the ``pyramid.require_default_csrf`` setting, accepting strings -or boolean values. - -If ``require_csrf`` is ``True`` but does not explicitly define a token to -check, then the token name is pulled from whatever was set in the -``pyramid.require_default_csrf`` setting. Finally, if that setting does not -explicitly define a token, then ``csrf_token`` is the token required. This token -name will be required in ``request.POST`` which is the submitted form body. - -It is always possible to pass the token in the ``X-CSRF-Token`` header as well. -There is currently no way to define an alternate name for this header without -performing CSRF checking manually. - -In addition to token based CSRF checks, the automatic CSRF checking will also -check the referrer of the request to ensure that it matches one of the trusted -origins. By default the only trusted origin is the current host, however -additional origins may be configured by setting +:meth:`pyramid.config.Configurator.set_default_csrf_options` directive. +For example: + +.. code-block:: python + + from pyramid.config import Configurator + + config = Configurator() + config.set_default_csrf_options(require_csrf=True) + +CSRF checking may be explicitly enabled or disabled on a per-view basis using +the ``require_csrf`` view option. A value of ``True`` or ``False`` will +override the default set by ``set_default_csrf_options``. For example: + +.. code-block:: python + + @view_config(route_name='hello', require_csrf=False) + def myview(request): + # ... + +When CSRF checking is active, the token and header used to find the +supplied CSRF token will be ``csrf_token`` and ``X-CSRF-Token``, respectively, +unless otherwise overridden by ``set_default_csrf_options``. The token is +checked against the value in ``request.POST`` which is the submitted form body. +If this value is not present, then the header will be checked. + +In addition to token based CSRF checks, if the request is using HTTPS then the +automatic CSRF checking will also check the referrer of the request to ensure +that it matches one of the trusted origins. By default the only trusted origin +is the current host, however additional origins may be configured by setting ``pyramid.csrf_trusted_origins`` to a list of domain names (and ports if they are non standard). If a host in the list of domains starts with a ``.`` then that will allow all subdomains as well as the domain without the ``.``. -If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` exception -will be raised. This exception may be caught and handled by an -:term:`exception view` but, by default, will result in a ``400 Bad Request`` -response being sent to the client. +If CSRF checks fail then a :class:`pyramid.exceptions.BadCSRFToken` or +:class:`pyramid.exceptions.BadCSRFOrigin` exception will be raised. This +exception may be caught and handled by an :term:`exception view` but, by +default, will result in a ``400 Bad Request`` response being sent to the +client. Checking CSRF Tokens with a View Predicate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 1cb30e690a7ba97db212e7ec9002fd83f950b0bd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 23 Apr 2016 02:45:04 -0700 Subject: Fix all the stinky linkie rot via `make linkcheck SPHINXBUILD=$VENV/bin/sphinx-build`, but don't bother with HISTORY.txt or whatsnew-xx --- docs/narr/firstapp.rst | 2 +- docs/narr/i18n.rst | 4 ++-- docs/narr/install.rst | 4 ++-- docs/narr/introduction.rst | 12 +++++------ docs/narr/logging.rst | 3 ++- docs/narr/muchadoabouttraversal.rst | 4 +--- docs/narr/project.rst | 40 ++++++++++++++++++------------------- docs/narr/renderers.rst | 2 +- docs/narr/templates.rst | 2 +- docs/narr/upgrading.rst | 8 +++++--- docs/narr/urldispatch.rst | 7 ++++--- docs/narr/webob.rst | 6 +++--- 12 files changed, 48 insertions(+), 46 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 6a952dec9..a8491eabd 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -197,7 +197,7 @@ method returns a :term:`WSGI` application object that can be used by any WSGI server to present an application to a requestor. :term:`WSGI` is a protocol that allows servers to talk to Python applications. We don't discuss :term:`WSGI` in any depth within this book, but you can learn more about it by -visiting `wsgi.org `_. +reading its `documentation `_. The :app:`Pyramid` application object, in particular, is an instance of a class representing a :app:`Pyramid` :term:`router`. It has a reference to the diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 014f314ad..131832aae 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -343,7 +343,7 @@ This will create a new message catalog ``.po`` file in ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. Once the file is there, it can be worked on by a human translator. One tool -which may help with this is `Poedit `_. +which may help with this is `Poedit `_. Note that :app:`Pyramid` itself ignores the existence of all ``.po`` files. For a running application to have translations available, a ``.mo`` file must @@ -647,7 +647,7 @@ before being rendered: The features represented by attributes of the ``i18n`` namespace of Chameleon will also consult the :app:`Pyramid` translations. See -http://chameleon.readthedocs.org/en/latest/reference.html#id50. +http://chameleon.readthedocs.org/en/latest/reference.html#translation-i18n. .. note:: diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 3e5523262..7d96f4074 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -90,7 +90,7 @@ If You Don't Yet Have a Python Interpreter (Windows) If your Windows system doesn't have a Python interpreter, you'll need to install it by downloading a Python 3.x-series interpreter executable from -`python.org's download section `_ (the files +`python.org's download section `_ (the files labeled "Windows Installer"). Once you've downloaded it, double click on the executable and accept the defaults during the installation process. You may also need to download and install the Python for Windows extensions. @@ -99,7 +99,7 @@ also need to download and install the Python for Windows extensions. Windows ` for full details. .. seealso:: Download and install the `Python for Windows extensions - `_. Carefully read + `_. Carefully read the README.txt file at the end of the list of builds, and follow its directions. Make sure you get the proper 32- or 64-bit build and Python version. diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 24c9f6b93..d92916503 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -221,7 +221,7 @@ send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. Examples: -http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation +http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-ons Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -881,7 +881,7 @@ new-user-friendly. Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on irc.freenode.net in an IRC client) or the pylons-discuss maillist at -http://groups.google.com/group/pylons-discuss/. +https://groups.google.com/forum/#!forum/pylons-discuss. Documentation ~~~~~~~~~~~~~ @@ -903,7 +903,7 @@ What Is The Pylons Project? :app:`Pyramid` is a member of the collection of software published under the Pylons Project. Pylons software is written by a loose-knit community of -contributors. The `Pylons Project website `_ +contributors. The `Pylons Project website `_ includes details about how :app:`Pyramid` relates to the Pylons Project. .. index:: @@ -967,9 +967,9 @@ nor discouraging the decision. Other Python web frameworks advertise themselves as members of a class of web frameworks named `model-view-controller -`_ frameworks. Insofar as -this term has been claimed to represent a class of web frameworks, -:app:`Pyramid` also generally fits into this class. +`_ +frameworks. Insofar as this term has been claimed to represent a class of web +frameworks, :app:`Pyramid` also generally fits into this class. .. sidebar:: You Say :app:`Pyramid` is MVC, but Where's the Controller? diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 9c6e8a319..c7b4b9d6f 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -292,7 +292,8 @@ Logging Exceptions To log or email exceptions generated by your :app:`Pyramid` application, use the :term:`pyramid_exclog` package. Details about its configuration are in its -`documentation `_. +`documentation +`_. .. index:: single: TransLogger diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 3e00a295a..02cd8ee3a 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -8,9 +8,7 @@ Much Ado About Traversal .. note:: - This chapter was adapted, with permission, from a blog post by `Rob Miller - `_, originally published at - http://blog.nonsequitarian.org/2010/much-ado-about-traversal/. + This chapter was adapted, with permission, from a blog post by Rob Miller. Traversal is an alternative to :term:`URL dispatch` which allows :app:`Pyramid` applications to map URLs to code. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 81fc9acf4..56247ee33 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -584,7 +584,7 @@ only (``127.0.0.1``). The sections after ``# logging configuration`` represent Python's standard library :mod:`logging` module configuration for your application. These sections are passed to the `logging module's config file configuration engine -`_ when the +`_ when the ``pserve`` or ``pshell`` commands are executed. The default configuration sends application logging output to the standard error output of your terminal. For more information about logging configuration, see :ref:`logging_chapter`. @@ -628,8 +628,8 @@ setup.py sdist``. Due to the information contained in the default ``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files, ``.ini`` files, ``.rst`` files, graphics files, and template files, as well as ``.py`` files. See -http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template for -more information about the syntax and usage of ``MANIFEST.in``. +https://docs.python.org/2/distutils/sourcedist.html#the-manifest-in-template +for more information about the syntax and usage of ``MANIFEST.in``. Without the presence of a ``MANIFEST.in`` file or without checking your source code into a version control repository, ``setup.py sdist`` places only *Python @@ -647,8 +647,8 @@ files with extensions other than the files named in the project's ``MANIFEST.in`` and you don't make use of a setuptools-compatible version control system, you'll need to edit the ``MANIFEST.in`` file and include the statements necessary to include your new files. See -http://docs.python.org/distutils/sourcedist.html#principle for more information -about how to do this. +https://docs.python.org/2/distutils/sourcedist.html#principle for more +information about how to do this. You can also delete ``MANIFEST.in`` from your project and rely on a setuptools feature which simply causes all files checked into a version control system to @@ -697,21 +697,21 @@ Your application's name can be any string; it is specified in the ``name`` field. The version number is specified in the ``version`` value. A short description is provided in the ``description`` field. The ``long_description`` is conventionally the content of the ``README`` and ``CHANGES`` files appended -together. The ``classifiers`` field is a list of `Trove -`_ classifiers -describing your application. ``author`` and ``author_email`` are text fields -which probably don't need any description. ``url`` is a field that should -point at your application project's URL (if any). ``packages=find_packages()`` -causes all packages within the project to be found when packaging the -application. ``include_package_data`` will include non-Python files when the -application is packaged if those files are checked into version control. -``zip_safe=False`` indicates that this package is not safe to use as a zipped -egg; instead it will always unpack as a directory, which is more convenient. -``install_requires`` indicate that this package depends on the ``pyramid`` -package. ``extras_require`` is a Python dictionary that defines what is -required to be installed for running tests. We examined ``entry_points`` in our -discussion of the ``development.ini`` file; this file defines the ``main`` -entry point that represents our project's application. +together. The ``classifiers`` field is a list of `Trove classifiers +`_ describing your +application. ``author`` and ``author_email`` are text fields which probably +don't need any description. ``url`` is a field that should point at your +application project's URL (if any). ``packages=find_packages()`` causes all +packages within the project to be found when packaging the application. +``include_package_data`` will include non-Python files when the application is +packaged if those files are checked into version control. ``zip_safe=False`` +indicates that this package is not safe to use as a zipped egg; instead it will +always unpack as a directory, which is more convenient. ``install_requires`` +indicates that this package depends on the ``pyramid`` package. +``extras_require`` is a Python dictionary that defines what is required to be +installed for running tests. We examined ``entry_points`` in our discussion of +the ``development.ini`` file; this file defines the ``main`` entry point that +represents our project's application. Usually you only need to think about the contents of the ``setup.py`` file when distributing your application to other people, when adding Python package diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 50e85813a..e06c78028 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -317,7 +317,7 @@ JSONP Renderer .. versionadded:: 1.1 :class:`pyramid.renderers.JSONP` is a `JSONP -`_ renderer factory helper which implements +`_ renderer factory helper which implements a hybrid JSON/JSONP renderer. JSONP is useful for making cross-domain AJAX requests. diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 9e3a31845..6b3b5fcce 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -448,7 +448,7 @@ templating languages including the following: .. _pyramid_chameleon: http://docs.pylonsproject.org/projects/pyramid-chameleon/en/latest/ -.. _Jinja2: http://jinja.pocoo.org/docs/ +.. _Jinja2: http://jinja.pocoo.org/docs/dev/ .. _pyramid_jinja2: http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/ diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index fcdce4f8d..21b696775 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -128,7 +128,8 @@ you can see DeprecationWarnings printed to the console when the tests run. The ``-Wd`` argument tells Python to print deprecation warnings to the console. See `the Python -W flag documentation -`_ for more information. +`_ for more +information. As your tests run, deprecation warnings will be printed to the console explaining the deprecation and providing instructions about how to prevent the @@ -215,9 +216,10 @@ around in your application interactively to try to generate them, and remediate as explained in :ref:`testing_under_new_release`. See `the PYTHONWARNINGS environment variable documentation -`_ or `the +`_ or `the Python -W flag documentation -`_ for more information. +`_ for more +information. Upgrading to the very latest Pyramid release -------------------------------------------- diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index c13558008..2472ace31 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -271,8 +271,9 @@ pattern like this: But this will either cause an error at startup time or it won't match properly. You'll want to use a Unicode value as the pattern instead rather than raw bytestring escapes. You can use a high-order Unicode value as the pattern by -using `Python source file encoding `_ -plus the "real" character in the Unicode pattern in the source, like so: +using `Python source file encoding +`_ plus the "real" character in the +Unicode pattern in the source, like so: .. code-block:: text @@ -1194,7 +1195,7 @@ If a predicate is a class, just add ``__text__`` property in a standard manner. __text__ = 'my custom class predicate' If a predicate is a method, you'll need to assign it after method declaration -(see `PEP 232 `_). +(see `PEP 232 `_). .. code-block:: python :linenos: diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index cfcf532bc..ce1586834 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -27,8 +27,8 @@ functionality to the standard WebOb request, which is documented in the :ref:`request_module` API documentation. WebOb provides objects for HTTP requests and responses. Specifically it does -this by wrapping the `WSGI `_ request environment and response -status, header list, and app_iter (body) values. +this by wrapping the `WSGI `_ request +environment and response status, header list, and app_iter (body) values. WebOb request and response objects provide many conveniences for parsing WSGI requests and forming WSGI responses. WebOb is a nice way to represent "raw" @@ -46,7 +46,7 @@ Request ~~~~~~~ The request object is a wrapper around the `WSGI environ dictionary -`_. This +`_. This dictionary contains keys for each header, keys that describe the request (including the path and query string), a file-like object for the request body, and a variety of custom keys. You can always access the environ with -- cgit v1.2.3 From 7461299e7489458ed9e9996fde33b095eb7e729a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 24 Apr 2016 13:23:05 -0700 Subject: update bad link --- docs/narr/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index bfc908396..7e961f5e8 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -305,7 +305,7 @@ Preventing Cross-Site Request Forgery Attacks --------------------------------------------- `Cross-site request forgery -`_ attacks are a +`_ attacks are a phenomenon whereby a user who is logged in to your website might inadvertantly load a URL because it is linked from, or embedded in, an attacker's website. If the URL is one that may modify or delete data, the consequences can be dire. -- cgit v1.2.3 From b5fcc452c364284648aae4c0ce061b3bac711cd0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 24 Apr 2016 15:42:34 -0700 Subject: Allow Sphinx doctests to run and pass with `make doctest SPHINXBUILD=$VENV/bin/sphinx-build`. - TODO: two tests in `docs/narr/hooks.rst` --- docs/narr/sessions.rst | 45 ++++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 17 deletions(-) (limited to 'docs/narr') 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 -- cgit v1.2.3 From a470ff601182fed93446b8bfe4bc8707a8455949 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 24 Apr 2016 20:39:37 -0700 Subject: add sphinx doctests for hooks.rst --- docs/narr/hooks.rst | 62 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 4 deletions(-) (limited to 'docs/narr') 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 -- cgit v1.2.3 From f2bc0e39cabb2f234ea622b2ebdd0b8eac5cea32 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 25 Apr 2016 21:12:32 -0500 Subject: fix explanation of require_csrf --- docs/narr/hooks.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 150eca944..49ef29d3f 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1647,8 +1647,9 @@ the user-defined :term:`view callable`: ``csrf_view`` Used to check the CSRF token provided in the request. This element is a - no-op if both the ``require_csrf`` view option and the - ``pyramid.require_default_csrf`` setting are disabled. + no-op if ``require_csrf`` view option is not ``True``. Note there will + always be a ``require_csrf`` option if a default value was assigned via + :meth:`pyramid.config.Configurator.set_default_csrf_options`. ``owrapped_view`` -- cgit v1.2.3 From 68ba583735aedc6762131af2cf93cf0fdd470fef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vincent=20F=C3=A9rotin?= Date: Fri, 6 May 2016 19:45:32 +0200 Subject: doc: Update documentation for using ``py.test [--cov]`` for newly created project with scaffolds. --- docs/narr/project.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 56247ee33..8849e9ee7 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -209,25 +209,29 @@ On UNIX: .. code-block:: bash - $ $VENV/bin/py.test myproject/tests.py -q + $ $VENV/bin/py.test -q On Windows: .. code-block:: doscon - > %VENV%\Scripts\py.test myproject\tests.py -q + > %VENV%\Scripts\py.test -q Here's sample output from a test run on UNIX: .. code-block:: bash - $ $VENV/bin/py.test myproject/tests.py -q + $ $VENV/bin/py.test -q .. 2 passed in 0.47 seconds The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, -only two sample tests exist. +only two sample tests exist. Previous command is identical to: + +.. code-block:: bash + + $ $VENV/bin/py.test myproject/tests.py -q .. note:: @@ -235,6 +239,14 @@ only two sample tests exist. to a stream of dots. If you don't pass ``-q``, you'll see verbose test result output (which normally isn't very useful). +Alternatively, if you'd like to see test coverage, pass the ``--cov`` option +to ``py.test``: + +.. code-block:: bash + + $ $VENV/bin/py.test -q --cov + + .. index:: single: running an application single: pserve -- cgit v1.2.3 From e09369f02f61f2443f393bcd29fa84e970268b53 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 7 May 2016 00:54:55 -0700 Subject: wordsmith py.test and coverage configuration --- docs/narr/project.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8849e9ee7..a25394151 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -227,11 +227,7 @@ Here's sample output from a test run on UNIX: The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, -only two sample tests exist. Previous command is identical to: - -.. code-block:: bash - - $ $VENV/bin/py.test myproject/tests.py -q +only two sample tests exist. .. note:: @@ -244,7 +240,19 @@ to ``py.test``: .. code-block:: bash - $ $VENV/bin/py.test -q --cov + $ $VENV/bin/py.test --cov -q + +Scaffolds include configuration defaults for ``py.test`` and test coverage. +These configuration files are ``pytest.ini`` and ``.coveragerc``, located at +the root of your package. Without these defaults, we would need to specify the +path to the module on which we want to run tests and coverage. + +.. code-block:: bash + + $ $VENV/bin/py.test --cov=myproject myproject/tests.py -q + +.. seealso:: See py.test's documentation for :ref:`pytest:usage` or invoke + ``py.test -h`` to see its full set of options. .. index:: -- cgit v1.2.3 From ea252c3df9cab326a5a5e9a7bdcafae637bd0d47 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 7 May 2016 01:53:23 -0700 Subject: update narr/project.rst with py.test and coverage defaults --- docs/narr/project.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index a25394151..1ce12a938 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -929,10 +929,10 @@ The ``tests.py`` module includes unit tests for your application. :linenos: This sample ``tests.py`` file has one unit test and one functional test defined -within it. These tests are executed when you run ``py.test myproject/tests.py --q``. You may add more tests here as you build your application. You are not -required to write tests to use :app:`Pyramid`. This file is simply provided for -convenience and example. +within it. These tests are executed when you run ``py.test -q``. You may add +more tests here as you build your application. You are not required to write +tests to use :app:`Pyramid`. This file is simply provided for convenience and +example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests. -- cgit v1.2.3 From c6729daea00b438bcf01c15c0e98f4a8024bf3c7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 8 May 2016 12:41:08 -0700 Subject: use new trypyramid.com page. whee! --- docs/narr/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index d92916503..de6ac408b 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -221,7 +221,7 @@ send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. Examples: -http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-ons +https://trypyramid.com/resources-extending-pyramid.html Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3