Understanding resource and context in Pyramid

Question

Please bear with me, since I am just getting started with Pyramid. I am having trouble understanding context and resource in Pyramid, with regards to URL Dispatch. I'm not quite sure what it means from the description in the documentation, context and resource is somewhat circular (to me).

• What is a resource in pyramid? Is it just what the url is trying to represent? For example, if the url is /organization/add_users, is the resource organization or users?
• Is the context also organization in the example above?

Also,

• What exactly is a context object?

• What is the context object supposed to contain? The example in the tutorial only has the ACL and has nothing in the init method.

  class RootFactory(object):
  __acl__ = [(...some permissions...)]
  
  def __init__(self):
      pass
  

• When an exception is thrown (Forbidden for instance) at what point exactly does the context change?

• I can see the purpose of the changing context when there is something like a Forbidden error, but when doing something like validation, why should I throw an exception that is registered with a different view_callable, which renders to a different template, when I can simply render to a different template within the same view_callable instead of throwing the exception? (I saw a validation error example for add_view in the docs)

Answer 1

First of all, the main reason that you would want to even care about this stuff when using URL Dispatch is for the purposes of using pyramid's auth system. If you don't care about that, then you can completely ignore contexts and resource trees and go on with dispatch.

Resource Trees

Pyramid has a unique concept of a resource tree, which is literally a tree of objects that is mapped to a path. This tree is traversed from the root down to the end of a supplied path. During traversal if the path is exhausted or the tree hits a leave node, that object in the tree is now the context.

In URL Dispatch, traversal does not occur (by default), thus the context will always be the root of your resource tree.

In general, you can use the context for anything you want in your application. It is used explicitly by the ACLAuthorizationPolicy to determine permissions. This is a whole topic, and I'd suggest checking out my demo that explains how to use Pyramid's auth system with URL Dispatch [1].

Exceptions

Exception handling in Pyramid is done in two different ways:

1. You can use try: except: in your view to return a different response.
2. You can utilize exception views to more generally handle exceptions within your app.

Note that the second way is required for rendering 404 pages and if you're using Pyramid's auth, forbidden pages too. This is because Pyramid internally throws the NotFound and Forbidden exceptions that you must catch and render if you want to customize them.

When an exception is thrown and there is an exception view registered to match that type, Pyramid will invoke the exception view and pass in the exception as the new context, so that's when the context changes.

I'm not sure validation is a good example of an exception view. More typically the views are used for error cases, or to short-circuit execution in non-view parts of your application. For example you may want to handle and return different pages when your view fails to connect to your database, or when you want to return a 4xx or 5xx response. By default if the exception is not handled, the WSGI server just turns it into a generic 500 page. Exception views let you customize that behavior.

The important takeaway from all of this is that it's all optional. If you're confused, don't worry because you can utilize Pyramid without these things, and as you grow more comfortable you can begin to incorporate them into your application.

Answer 2

It doesn't help that the example here: http://docs.pylonsproject.org/projects/pyramid/1.1/tutorials/wiki2/authorization.html#adding-login-and-logout-views is incorrect.

The thrown exception (At least as it relates to Pyramid 1.0-2) is pyramid.exceptions.Forbidden; not the example's pyramid.httpexceptions.HTTPForbidden .

However in hitting that snag in the tutorial I learned where some other useful things were.