Pylons/pyramid — pull request #836 by davidjb (2013-01-31 04:01:26+00:00)
Title: Document PredicateMismatch for exception contexts

After recently attempting to add custom forbidden views to my application (Pyramid 1.4), I've found myself hitting PredicateMismatch exceptions. The following is a simplified example:
```
@forbidden_view_config([some predicates])
class ForbiddenView(object):
...

@view_config(route_name='my_route')
class MyView(object):
def __call__(self):
raise HTTPForbidden()
```

If a request comes for MyView, and that request fails to match the predicates specified for the ForbiddenView, a PredicateMismatch exception is raised. This exception isn't publicly documented, so I was unsure what this meant until I read the source code.

My suggestion is to document PredicateMismatch when it might occur (eg if predicates don't match for an exception context; eg at line 40 of pyramid/tweens.py when attempting to call an exception view) and what it means when you encounter one. I've done my best, but my documentation may need clarification.

I also think it would be useful to include a mention to PredicateMismatch somewhere more 'obvious' related to exception handling -- like http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/views.html#custom-exception-views.