diff options
| -rw-r--r-- | docs/api/exceptions.rst | 2 | ||||
| -rw-r--r-- | pyramid/exceptions.py | 28 |
2 files changed, 25 insertions, 5 deletions
diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst index 1dfbf46fd..ab158f18d 100644 --- a/docs/api/exceptions.rst +++ b/docs/api/exceptions.rst @@ -5,6 +5,8 @@ .. automodule:: pyramid.exceptions + .. autoclass:: PredicateMismatch + .. autoclass:: Forbidden .. autoclass:: NotFound diff --git a/pyramid/exceptions.py b/pyramid/exceptions.py index dab958282..a8fca1d84 100644 --- a/pyramid/exceptions.py +++ b/pyramid/exceptions.py @@ -10,11 +10,29 @@ CR = '\n' class PredicateMismatch(HTTPNotFound): """ - Internal exception (not an API) raised by multiviews when no - view matches. This exception subclasses the ``NotFound`` - exception only one reason: if it reaches the main exception - handler, it should be treated like a ``NotFound`` by any exception - view registrations. + This exception is raised by multiviews when no view matches + all given predicates. + + This exception subclasses the :class:`HTTPNotFound` exception for a + specific reason: if it reaches the main exception handler, it should + be treated as :class:`HTTPNotFound`` by any exception view + registrations. Thus, typically, this exception will not be seen + publicly. + + However, this exception will be raised if the predicates of all + views configured to handle another exception context cannot be + successfully matched. For instance, if a view is configured to + handle a context of ``HTTPForbidden`` and the configured with + additional predicates, then :class:`PredicateMismatch` will be + raised if: + + * An original view callable has raised :class:`HTTPForbidden` (thus + invoking an exception view); and + * The given request fails to match all predicates for said + exception view associated with :class:`HTTPForbidden`. + + The same applies to any type of exception being handled by an + exception view. """ class URLDecodeError(UnicodeDecodeError): |