.. _design_defense:

Defending Pyramid's Design
==========================

From time to time, challenges to various aspects of :app:`Pyramid` design are
lodged.  To give context to discussions that follow, we detail some of the
design decisions and trade-offs here.  In some cases, we acknowledge that the
framework can be made better and we describe future steps which will be taken
to improve it; in some cases we just file the challenge as "noted", as
obviously you can't please everyone all of the time.

Pyramid Provides More Than One Way to Do It
-------------------------------------------

A canon of Python popular culture is "TIOOWTDI" ("there is only one way to do
it", a slighting, tongue-in-cheek reference to Perl's "TIMTOWTDI", which is
an acronym for "there is more than one way to do it").

:app:`Pyramid` is, for better or worse, a "TIMTOWTDI" system.  For example,
it includes more than one way to resolve a URL to a :term:`view callable`:
via :term:`url dispatch` or :term:`traversal`.  Multiple methods of
configuration exist: :term:`imperative configuration`, :term:`configuration
decoration`, and :term:`ZCML` (optionally via :term:`pyramid_zcml`). It works
with multiple different kinds of persistence and templating systems.  And so
on.  However, the existence of most of these overlapping ways to do things
are not without reason and purpose: we have a number of audiences to serve,
and we believe that TIMTOWTI at the web framework level actually *prevents* a
much more insidious and harmful set of duplication at higher levels in the
Python web community.

:app:`Pyramid` began its life as :mod:`repoze.bfg`, written by a team of
people with many years of prior :term:`Zope` experience.  The idea of
:term:`traversal` and the way :term:`view lookup` works was stolen entirely
from Zope.  The authorization subsystem provided by :app:`Pyramid` is a
derivative of Zope's.  The idea that an application can be *extended* without
forking is also a Zope derivative.

Implementations of these features were *required* to allow the :app:`Pyramid`
authors to build the bread-and-butter CMS-type systems for customers in the
way they were accustomed to building them.  No other system save Zope itself
had such features.  And Zope itself was beginning to show signs of its age.
We were becoming hampered by consequences of its early design mistakes.
Zope's lack of documentation was also difficult to work around: it was hard
to hire smart people to work on Zope applications, because there was no
comprehensive documentation set to point them at which explained "it all" in
one consumble place, and it was too large and self-inconsistent to document
properly.  Before :mod:`repoze.bfg` went under development, its authors
obviously looked around for other frameworks that fit the bill.  But no
non-Zope framework did.  So we embarked on building :mod:`repoze.bfg`.

As the result of our research, however, it became apparent that, despite the
fact that no *one* framework had all the features we required, lots of
existing frameworks had good, and sometimes very compelling ideas.  In
particular, :term:`URL dispatch` is a more direct mechanism to map URLs to
code.

So although we couldn't find a framework save for Zope that fit our needs,
and while we incorporated a lot of Zope ideas into BFG, we also emulated the
features we found compelling in other frameworks (such as :term:`url
dispatch`).  After the initial public release of BFG, as time went on,
features were added to support people allergic to various Zope-isms in the
system, such as the ability to configure the application using
:term:`imperative configuration` rather than solely using :term:`ZCML`, and
the elimination of the required use of :term:`interface` objects.  It soon
became clear that we had a system that was very generic, and was beginning to
appeal to non-Zope users as well as ex-Zope users.

As the result of this generalization, it became obvious BFG shared 90% of its
featureset with the featureset of Pylons 1, and thus had a very similar
target market.  Because they were so similar, choosing between the two
systems was an exercise in frustration for an otherwise non-partisan
developer.  It was also strange for the Pylons and BFG development
communities to be in competition for the same set of users, given how similar
the two frameworks were.  So the Pylons and BFG teams began to work together
to form a plan to "merge".  The features missing from BFG (notably
:term:`view handler` classes, flash messaging, and other minor missing bits),
were added, to provide familiarity to ex-Pylons users.  The result is
:app:`Pyramid`.

The Python web framework space is currently notoriously balkanized.  We're
truly hoping that the amalgamation of components in :app:`Pyramid` will
appeal to at least two currently very distinct sets of users: Pylons and BFG
users.  By unifying the best concepts from Pylons and BFG into a single
codebase and leaving the bad concepts from their ancestors behind, we'll be
able to consolidate our efforts better, share more code, and promote our
efforts as a unit rather than competing pointlessly.  We hope to be able to
shortcut the pack mentality which results in a *much larger* duplication of
effort, represented by competing but incredibly similar applications and
libraries, each built upon a specific low level stack that is incompatible
with the other.  We'll also shrink the choice of credible Python web
frameworks down by at least one.  We're also hoping to attract users from
other communities (such as Zope's and TurboGears') by providing the features
they require, while allowing enough flexibility to do things in a familiar
fashion.  Some overlap of functionality to achieve these goals is expected
and unavoidable, at least if we aim to prevent pointless duplication at
higher levels.  If we've done our job well enough, the various audiences will
be able to coexist and cooperate rather than firing at each other across some
imaginary web framework "DMZ".

Pyramid Uses A Zope Component Architecture ("ZCA") Registry
-----------------------------------------------------------

:app:`Pyramid` uses a :term:`Zope Component Architecture` (ZCA) "component
registry" as its :term:`application registry` under the hood.  This is a
point of some contention.  :app:`Pyramid` is of a :term:`Zope` pedigree, so
it was natural for its developers to use a ZCA registry at its inception.
However, we understand that using a ZCA registry has issues and consequences,
which we've attempted to address as best we can.  Here's an introspection
about :app:`Pyramid` use of a ZCA registry, and the trade-offs its usage
involves.

Problems
++++++++

The "global" API that may be used to access data in a ZCA "component
registry" is not particularly pretty or intuitive, and sometimes it's just
plain obtuse.  Likewise, the conceptual load on a casual source code reader
of code that uses the ZCA global API is somewhat high.  Consider a ZCA
neophyte reading the code that performs a typical "unnamed utility" lookup
using the :func:`zope.component.getUtility` global API:

.. ignore-next-block
.. code-block:: python
   :linenos:

   from pyramid.interfaces import ISettings
   from zope.component import getUtility
   settings = getUtility(ISettings)

After this code runs, ``settings`` will be a Python dictionary.  But it's
unlikely that any "civilian" would know that just by reading the code.  There
are a number of comprehension issues with the bit of code above that are
obvious.

First, what's a "utility"?  Well, for the purposes of this discussion, and
for the purpose of the code above, it's just not very important.  If you
really want to know, you can read `this
<http://www.muthukadan.net/docs/zca.html#utility>`_.  However, still, readers
of such code need to understand the concept in order to parse it.  This is
problem number one.

Second, what's this ``ISettings`` thing?  It's an :term:`interface`.  Is that
important here?  Not really, we're just using it as a "key" for some lookup
based on its identity as a marker: it represents an object that has the
dictionary API, but that's not very important in this context.  That's
problem number two.

Third of all, what does the ``getUtility`` function do?  It's performing a
lookup for the ``ISettings`` "utility" that should return.. well, a utility.
Note how we've already built up a dependency on the understanding of an
:term:`interface` and the concept of "utility" to answer this question: a bad
sign so far.  Note also that the answer is circular, a *really* bad sign.

Fourth, where does ``getUtility`` look to get the data?  Well, the "component
registry" of course.  What's a component registry?  Problem number four.

Fifth, assuming you buy that there's some magical registry hanging around,
where *is* this registry?  *Homina homina*... "around"?  That's sort of the
best answer in this context (a more specific answer would require knowledge
of internals).  Can there be more than one registry?  Yes.  So *which*
registry does it find the registration in?  Well, the "current" registry of
course.  In terms of :app:`Pyramid`, the current registry is a thread local
variable.  Using an API that consults a thread local makes understanding how
it works non-local.

You've now bought in to the fact that there's a registry that is just
"hanging around".  But how does the registry get populated?  Why, via code
that calls directives like ``config.add_view``.  In this particular case,
however, the registration of ``ISettings`` is made by the framework itself
"under the hood": it's not present in any user configuration.  This is
extremely hard to comprehend.  Problem number six.

Clearly there's some amount of cognitive load here that needs to be borne by
a reader of code that extends the :app:`Pyramid` framework due to its use of
the ZCA, even if he or she is already an expert Python programmer and whom is
an expert in the domain of web applications.  This is suboptimal.

Ameliorations
+++++++++++++

First, the primary amelioration: :app:`Pyramid` *does not expect application
developers to understand ZCA concepts or any of its APIs*.  If an
*application* developer needs to understand a ZCA concept or API during the
creation of a :app:`Pyramid` application, we've failed on some axis.

Instead, the framework hides the presence of the ZCA registry behind
special-purpose API functions that *do* use ZCA APIs.  Take for example the
``pyramid.security.authenticated_userid`` function, which returns the userid
present in the current request or ``None`` if no userid is present in the
current request.  The application developer calls it like so:

.. ignore-next-block
.. code-block:: python
   :linenos:

   from pyramid.security import authenticated_userid
   userid = authenticated_userid(request)

He now has the current user id.

Under its hood however, the implementation of ``authenticated_userid``
is this:

.. code-block:: python
   :linenos:

   def authenticated_userid(request):
       """ Return the userid of the currently authenticated user or
       ``None`` if there is no authentication policy in effect or there
       is no currently authenticated user. """

       registry = request.registry # the ZCA component registry
       policy = registry.queryUtility(IAuthenticationPolicy)
       if policy is None:
           return None
       return policy.authenticated_userid(request)

Using such wrappers, we strive to always hide the ZCA API from application
developers.  Application developers should just never know about the ZCA API:
they should call a Python function with some object germane to the domain as
an argument, and it should returns a result.  A corollary that follows is
that any reader of an application that has been written using :app:`Pyramid`
needn't understand the ZCA API either.

Hiding the ZCA API from application developers and code readers is a form of
enhancing "domain specificity".  No application developer wants to need to
understand the small, detailed mechanics of how a web framework does its
thing.  People want to deal in concepts that are closer to the domain they're
working in: for example, web developers want to know about *users*, not
*utilities*.  :app:`Pyramid` uses the ZCA as an implementation detail, not as
a feature which is exposed to end users.

However, unlike application developers, *framework developers*, including
people who want to override :app:`Pyramid` functionality via preordained
framework plugpoints like traversal or view lookup *must* understand the ZCA
registry API.

:app:`Pyramid` framework developers were so concerned about conceptual load
issues of the ZCA registry API for framework developers that a `replacement
registry implementation <http://svn.repoze.org/repoze.component/trunk>`_
named :mod:`repoze.component` was actually developed.  Though this package
has a registry implementation which is fully functional and well-tested, and
its API is much nicer than the ZCA registry API, work on it was largely
abandoned and it is not used in :app:`Pyramid`.  We continued to use a ZCA
registry within :app:`Pyramid` because it ultimately proved a better fit.

.. note:: We continued using ZCA registry rather than disusing it in
   favor of using the registry implementation in
   :mod:`repoze.component` largely because the ZCA concept of
   interfaces provides for use of an interface hierarchy, which is
   useful in a lot of scenarios (such as context type inheritance).
   Coming up with a marker type that was something like an interface
   that allowed for this functionality seemed like it was just
   reinventing the wheel.

Making framework developers and extenders understand the ZCA registry API is
a trade-off.  We (the :app:`Pyramid` developers) like the features that the
ZCA registry gives us, and we have long-ago borne the weight of understanding
what it does and how it works.  The authors of :app:`Pyramid` understand the
ZCA deeply and can read code that uses it as easily as any other code.

But we recognize that developers who might want to extend the framework are not
as comfortable with the ZCA registry API as the original developers are with
it.  So, for the purposes of being kind to third-party :app:`Pyramid`
framework developers in, we've drawn some lines in the sand.

In all "core" code, We've made use of ZCA global API functions such as
``zope.component.getUtility`` and ``zope.component.getAdapter`` the exception
instead of the rule.  So instead of:

.. code-block:: python
   :linenos:

   from pyramid.interfaces import IAuthenticationPolicy
   from zope.component import getUtility
   policy = getUtility(IAuthenticationPolicy)

:app:`Pyramid` code will usually do:

.. code-block:: python
   :linenos:

   from pyramid.interfaces import IAuthenticationPolicy
   from pyramid.threadlocal import get_current_registry
   registry = get_current_registry()
   policy = registry.getUtility(IAuthenticationPolicy)

While the latter is more verbose, it also arguably makes it more obvious
what's going on.  All of the :app:`Pyramid` core code uses this pattern
rather than the ZCA global API.

Rationale
+++++++++

Here are the main rationales involved in the :app:`Pyramid` decision to use
the ZCA registry:

- History.  A nontrivial part of the answer to this question is "history".
  Much of the design of :app:`Pyramid` is stolen directly from :term:`Zope`.
  Zope uses the ZCA registry to do a number of tricks.  :app:`Pyramid` mimics
  these tricks, and, because the ZCA registry works well for that set of
  tricks, :app:`Pyramid` uses it for the same purposes.  For example, the way
  that :app:`Pyramid` maps a :term:`request` to a :term:`view callable` using
  :term:`traversal` is lifted almost entirely from Zope.  The ZCA registry
  plays an important role in the particulars of how this request to view
  mapping is done.

- Features.  The ZCA component registry essentially provides what can be
  considered something like a "superdictionary", which allows for more
  complex lookups than retrieving a value based on a single key.  Some of
  this lookup capability is very useful for end users, such as being able to
  register a view that is only found when the context is some class of
  object, or when the context implements some :term:`interface`.

- Singularity.  There's only one "place" where "application configuration"
  lives in a :app:`Pyramid` application: in a component registry.  The
  component registry answers questions made to it by the framework at runtime
  based on the configuration of *an application*.  Note: "an application" is
  not the same as "a process", multiple independently configured copies of
  the same :app:`Pyramid` application are capable of running in the same
  process space.

- Composability.  A ZCA component registry can be populated imperatively, or
  there's an existing mechanism to populate a registry via the use of a
  configuration file (ZCML, via :term:`pyramid_zcml`).  We didn't need to
  write a frontend from scratch to make use of configuration-file-driven
  registry population.

- Pluggability.  Use of the ZCA registry allows for framework extensibility
  via a well-defined and widely understood plugin architecture.  As long as
  framework developers and extenders understand the ZCA registry, it's
  possible to extend :app:`Pyramid` almost arbitrarily.  For example, it's
  relatively easy to build a directive that registers several views "all at
  once", allowing app developers to use that directive as a "macro" in code
  that they write.  This is somewhat of a differentiating feature from other
  (non-Zope) frameworks.

- Testability.  Judicious use of the ZCA registry in framework code makes
  testing that code slightly easier.  Instead of using monkeypatching or
  other facilities to register mock objects for testing, we inject
  dependencies via ZCA registrations and then use lookups in the code find
  our mock objects.

- Speed.  The ZCA registry is very fast for a specific set of complex lookup
  scenarios that :app:`Pyramid` uses, having been optimized through the years
  for just these purposes.  The ZCA registry contains optional C code for
  this purpose which demonstrably has no (or very few) bugs.

- Ecosystem.  Many existing Zope packages can be used in :app:`Pyramid` with
  few (or no) changes due to our use of the ZCA registry.

Conclusion
++++++++++

If you only *develop applications* using :app:`Pyramid`, there's not much to
complain about here.  You just should never need to understand the ZCA
registry API: use documented :app:`Pyramid` APIs instead.  However, you may
be an application developer who doesn't read API documentation because it's
unmanly. Instead you read the raw source code, and because you haven't read
the documentation, you don't know what functions, classes, and methods even
*form* the :app:`Pyramid` API.  As a result, you've now written code that
uses internals and you've painted yourself into a conceptual corner as a
result of needing to wrestle with some ZCA-using implementation detail.  If
this is you, it's extremely hard to have a lot of sympathy for you.  You'll
either need to get familiar with how we're using the ZCA registry or you'll
need to use only the documented APIs; that's why we document them as APIs.

If you *extend* or *develop* :app:`Pyramid` (create new directives, use some
of the more obscure "hooks" as described in :ref:`hooks_chapter`, or work on
the :app:`Pyramid` core code), you will be faced with needing to understand
at least some ZCA concepts.  In some places it's used unabashedly, and will
be forever.  We know it's quirky, but it's also useful and fundamentally
understandable if you take the time to do some reading about it.

Pyramid Uses Interfaces Too Liberally
-------------------------------------

In this `TOPP Engineering blog entry
<http://www.coactivate.org/projects/topp-engineering/blog/2008/10/20/what-bothers-me-about-the-component-architecture/>`_,
Ian Bicking asserts that the way :mod:`repoze.bfg` used a Zope interface to
represent an HTTP request method added too much indirection for not enough
gain.  We agreed in general, and for this reason, :mod:`repoze.bfg` version
1.1 (and subsequent versions including :app:`Pyramid` 1.0+) added :term:`view
predicate` and :term:`route predicate` modifiers to view configuration.
Predicates are request-specific (or :term:`context` -specific) matching
narrowers which don't use interfaces.  Instead, each predicate uses a
domain-specific string as a match value.

For example, to write a view configuration which matches only requests with
the ``POST`` HTTP request method, you might write a ``@view_config``
decorator which mentioned the ``request_method`` predicate:

.. code-block:: python
   :linenos:

   from pyramid.view import view_config
   @view_config(name='post_view', request_method='POST', renderer='json')
   def post_view(request):
       return 'POSTed'

You might further narrow the matching scenario by adding an ``accept``
predicate that narrows matching to something that accepts a JSON response:

.. code-block:: python
   :linenos:

   from pyramid.view import view_config
   @view_config(name='post_view', request_method='POST', 
                accept='application/json', renderer='json')
   def post_view(request):
       return 'POSTed'

Such a view would only match when the request indicated that HTTP request
method was ``POST`` and that the remote user agent passed
``application/json`` (or, for that matter, ``application/*``) in its
``Accept`` request header.

"Under the hood", these features make no use of interfaces.

Many "prebaked" predicates exist.  However, use of only "prebaked" predicates,
however, doesn't entirely meet Ian's criterion.  He would like to be able to
match a request using a lambda or another function which interrogates the
request imperatively.  In :mod:`repoze.bfg` version 1.2, we acommodate this by
allowing people to define "custom" view predicates:

.. code-block:: python
   :linenos:

   from pyramid.view import view_config
   from pyramid.response import Response

   def subpath(context, request):
       return request.subpath and request.subpath[0] == 'abc'

   @view_config(custom_predicates=(subpath,))
   def aview(request):
       return Response('OK')

The above view will only match when the first element of the request's
:term:`subpath` is ``abc``.

.. _zcml_encouragement:

Pyramid "Encourages Use of ZCML"
--------------------------------

:term:`ZCML` is a configuration language that can be used to configure the
:term:`Zope Component Architecture` registry that :app:`Pyramid` uses for
application configuration.  Often people claim that Pyramid "needs ZCML".

It doesn't.  In :app:`Pyramid` 1.0, ZCML doesn't ship as part of the core;
instead it ships in the :term:`pyramid_zcml` add-on package, which is
completely optional.  No ZCML is required at all to use :app:`Pyramid`, nor
any other sort of frameworky declarative frontend to application
configuration.

.. _model_traversal_confusion:

Pyramid Uses "Model" To Represent A Node In The Graph of Objects Traversed
--------------------------------------------------------------------------

The ``repoze.bfg`` documentation used to refer to the graph being traversed
when :term:`traversal` is used as a "model graph".  A terminology overlap
confused people who wrote applications that always use ORM packages such as
SQLAlchemy, which has a different notion of the definition of a "model".  As
a result, in Pyramid 1.0a7, the tree of objects traversed is now renamed to
:term:`resource tree` and its components are now named :term:`resource`
objects.  Associated APIs have been changed.  This hopefully alleviates the
terminology confusion caused by overriding the term "model".

Pyramid Does Traversal, And I Don't Like Traversal
--------------------------------------------------

In :app:`Pyramid`, :term:`traversal` is the act of resolving a URL path to a
:term:`resource` object in a resource tree.  Some people are uncomfortable
with this notion, and believe it is wrong.  Thankfully, if you use
:app:`Pyramid`, and you don't want to model your application in terms of a
resource tree, you needn't use it at all.  Instead, use :term:`URL dispatch`
to map URL paths to views.

The idea that some folks believe traversal is unilaterally "wrong" is
understandable.  The people who believe it is wrong almost invariably have
all of their data in a relational database.  Relational databases aren't
naturally hierarchical, so "traversing" one like a tree is not possible.

However, folks who deem traversal unilaterally wrong are neglecting to take
into account that many persistence mechanisms *are* hierarchical.  Examples
include a filesystem, an LDAP database, a :term:`ZODB` (or another type of
graph) database, an XML document, and the Python module namespace.  It is
often convenient to model the frontend to a hierarchical data store as a
graph, using traversal to apply views to objects that either *are* the
resources in the tree being traversed (such as in the case of ZODB) or at
least ones which stand in for them (such as in the case of wrappers for files
from the filesystem).

Also, many website structures are naturally hierarchical, even if the data
which drives them isn't.  For example, newspaper websites are often extremely
hierarchical: sections within sections within sections, ad infinitum.  If you
want your URLs to indicate this structure, and the structure is indefinite
(the number of nested sections can be "N" instead of some fixed number), a
resource tree is an excellent way to model this, even if the backend is a
relational database.  In this situation, the resource tree a just a site
structure.

Traversal also offers better composability of applications than URL dispatch,
because it doesn't rely on a fixed ordering of URL matching.  You can compose
a set of disparate functionality (and add to it later) around a mapping of
view to resource more predictably than trying to get "the right" ordering of
URL pattern matching.

But the point is ultimately moot.  If you don't want to use traversal, you
needn't.  Use URL dispatch instead.

Pyramid Does URL Dispatch, And I Don't Like URL Dispatch
--------------------------------------------------------

In :app:`Pyramid`, :term:`url dispatch` is the act of resolving a URL path to
a :term:`view` callable by performing pattern matching against some set of
ordered route definitions.  The route definitions are examined in order: the
first pattern which matches is used to associate the URL with a view
callable.

Some people are uncomfortable with this notion, and believe it is wrong.
These are usually people who are steeped deeply in :term:`Zope`.  Zope does
not provide any mechanism except :term:`traversal` to map code to URLs.  This
is mainly because Zope effectively requires use of :term:`ZODB`, which is a
hierarchical object store.  Zope also supports relational databases, but
typically the code that calls into the database lives somewhere in the ZODB
object graph (or at least is a :term:`view` related to a node in the object
graph), and traversal is required to reach this code.

I'll argue that URL dispatch is ultimately useful, even if you want to use
traversal as well.  You can actually *combine* URL dispatch and traversal in
:app:`Pyramid` (see :ref:`hybrid_chapter`).  One example of such a usage: if
you want to emulate something like Zope 2's "Zope Management Interface" UI on
top of your object graph (or any administrative interface), you can register
a route like ``<route name="manage" pattern="manage/*traverse"/>`` and then
associate "management" views in your code by using the ``route_name``
argument to a ``view`` configuration, e.g. ``<view view=".some.callable"
context=".some.Resource" route_name="manage"/>``.  If you wire things up this
way someone then walks up to for example, ``/manage/ob1/ob2``, they might be
presented with a management interface, but walking up to ``/ob1/ob2`` would
present them with the default object view.  There are other tricks you can
pull in these hybrid configurations if you're clever (and maybe masochistic)
too.

Also, if you are a URL dispatch hater, if you should ever be asked to write
an application that must use some legacy relational database structure, you
might find that using URL dispatch comes in handy for one-off associations
between views and URL paths.  Sometimes it's just pointless to add a node to
the object graph that effectively represents the entry point for some bit of
code.  You can just use a route and be done with it.  If a route matches, a
view associated with the route will be called; if no route matches,
:app:`Pyramid` falls back to using traversal.

But the point is ultimately moot.  If you use :app:`Pyramid`, and you really
don't want to use URL dispatch, you needn't use it at all.  Instead, use
:term:`traversal` exclusively to map URL paths to views, just like you do in
:term:`Zope`.

Pyramid Views Do Not Accept Arbitrary Keyword Arguments
-------------------------------------------------------

Many web frameworks (Zope, TurboGears, Pylons 1.X, Django) allow for their
variant of a :term:`view callable` to accept arbitrary keyword or positional
arguments, which are "filled in" using values present in the ``request.POST``
or ``request.GET`` dictionaries or by values present in the "route match
dictionary".  For example, a Django view will accept positional arguments
which match information in an associated "urlconf" such as
``r'^polls/(?P<poll_id>\d+)/$``:

.. code-block:: python
   :linenos:

   def aview(request, poll_id):
       return HttpResponse(poll_id)

Zope, likewise allows you to add arbitrary keyword and positional
arguments to any method of a resource object found via traversal:

.. ignore-next-block
.. code-block:: python
   :linenos:

   from persistent import Persistent

   class MyZopeObject(Persistent):
        def aview(self, a, b, c=None):
            return '%s %s %c' % (a, b, c)

When this method is called as the result of being the published callable, the
Zope request object's GET and POST namespaces are searched for keys which
match the names of the positional and keyword arguments in the request, and
the method is called (if possible) with its argument list filled with values
mentioned therein.  TurboGears and Pylons 1.X operate similarly.

Out of the box, :app:`Pyramid` is configured to have none of these features.
By default, :mod:`pyramid` view callables always accept only ``request`` and
no other arguments.  The rationale: this argument specification matching done
aggressively can be costly, and :app:`Pyramid` has performance as one of its
main goals, so we've decided to make people, by default, obtain information
by interrogating the request object within the view callable body instead of
providing magic to do unpacking into the view argument list.

However, as of :app:`Pyramid` 1.0a9, user code can influence the way view
callables are expected to be called, making it possible to compose a system
out of view callables which are called with arbitrary arguments.  See
:ref:`using_a_view_mapper`.

Pyramid Provides Too Few "Rails"
--------------------------------

By design, :app:`Pyramid` is not a particularly "opinionated" web framework.
It has a relatively parsimonious feature set.  It contains no built in ORM
nor any particular database bindings.  It contains no form generation
framework.  It has no administrative web user interface.  It has no built in
text indexing.  It does not dictate how you arrange your code.

Such opinionated functionality exists in applications and frameworks built
*on top* of :app:`Pyramid`.  It's intended that higher-level systems emerge
built using :app:`Pyramid` as a base.  See also :ref:`apps_are_extensible`.

Pyramid Provides Too Many "Rails"
---------------------------------

:app:`Pyramid` provides some features that other web frameworks do not.
These are features meant for use cases that might not make sense to you if
you're building a simple "bespoke" web application:

- An optional way to map URLs to code using :term:`traversal` which implies a
  walk of a :term:`resource tree`.

- The ability to aggregate Pyramid application configuration from multiple
  sources using :meth:`pyramid.config.Configurator.include`.

- View and subscriber registrations made using :term:`interface` objects
  instead of class objects (e.g. :ref:`using_resource_interfaces`).

- A declarative :term:`authorization` system.

- Multiple separate I18N :term:`translation string` factories, each of which
  can name its own "domain".

These features are important to the authors of :app:`Pyramid`.  The
:app:`Pyramid` authors are often commissioned to build CMS-style
applications.  Such applications are often "frameworky" because they have
more than one deployment.  Each deployment requires a slightly different
composition of sub-applications, and the framework and sub-applications often
need to be *extensible*.  Because the application has more than one
deployment, pluggability and extensibility is important, as maintaining
multiple forks of the application, one per deployment, is extremely
undesirable.  Because it's easier to extend a system that uses
:term:`traversal` "from the outside" than it is to do the same in a system
that uses :term:`URL dispatch`, each deployment uses a :term:`resource tree`
composed of a persistent tree of domain model objects, and uses
:term:`traversal` to map :term:`view callable` code to resources in the tree.
The resource tree contains very granular security declarations, as resources
are owned and accessible by different sets of users.  Interfaces are used to
make unit testing and implementation substitutability easier.

In a bespoke web application, usually there's a single canonical deployment,
and therefore no possibility of multiple code forks.  Extensibility is not
required; the code is just changed in-place.  Security requirements are often
less granular.  Using the features listed above will often be overkill for
such an application.

If you don't like these features, it doesn't mean you can't or shouldn't use
:app:`Pyramid`.  They are all optional, and a lot of time has been spent
making sure you don't need to know about them up-front.  You can build
"Pylons-1.X-style" applications using :app:`Pyramid` that are purely bespoke
by ignoring the features above.  You may find these features handy later
after building a "bespoke" web application that suddenly becomes popular and
requires extensibility because it must be deployed in multiple locations.

Pyramid Is Too Big
------------------

"The :app:`Pyramid` compressed tarball is almost 2MB.  It must be
enormous!"

No.  We just ship it with test code and helper templates.  Here's a
breakdown of what's included in subdirectories of the package tree:

docs/

  3.0MB

pyramid/tests/

  1.1MB

pyramid/paster_templates/

  804KB

pyramid/ (except for ``pyramd/tests and pyramid/paster_templates``)

  539K

The actual :app:`Pyramid` runtime code is about 10% of the total size of the
tarball omitting docs, helper templates used for package generation, and test
code.  Of the approximately 19K lines of Python code in the package, the code
that actually has a chance of executing during normal operation, excluding
tests and paster template Python files, accounts for approximately 5K lines
of Python code.  This is comparable to Pylons 1.X, which ships with a little
over 2K lines of Python code, excluding tests.

Pyramid Has Too Many Dependencies
---------------------------------

This is true.  At the time of this writing, the total number of Python
package distributions that :app:`Pyramid` depends upon transitively is 18 if
you use Python 2.6 or 2.7, or 16 if you use Python 2.4 or 2.5.  This is a lot
more than zero package distribution dependencies: a metric which various
Python microframeworks and Django boast.

The :mod:`zope.component` and :mod:`zope.configuration` packages on which
:app:`Pyramid` depends have transitive dependencies on several other packages
(:mod:`zope.schema`, :mod:`zope.i18n`, :mod:`zope.event`,
:mod:`zope.interface`, :mod:`zope.deprecation`, :mod:`zope.i18nmessageid`).
We've been working with the Zope community to try to collapse and untangle
some of these dependencies.  We'd prefer that these packages have fewer
packages as transitive dependencies, and that much of the functionality of
these packages was moved into a smaller *number* of packages.

:app:`Pyramid` also has its own direct dependencies, such as :term:`Paste`,
:term:`Chameleon`, :term:`Mako` and :term:`WebOb`, and some of these in turn
have their own transitive dependencies.

It should be noted that :app:`Pyramid` is positively lithe compared to
:term:`Grok`, a different Zope-based framework.  As of this writing, in its
default configuration, Grok has 109 package distribution dependencies. The
number of dependencies required by :app:`Pyramid` is many times fewer than
Grok (or Zope itself, upon which Grok is based).  :app:`Pyramid` has a number
of package distribution dependencies comparable to similarly-targeted
frameworks such as Pylons 1.X.

We try not to reinvent too many wheels (at least the ones that don't need
reinventing), and this comes at the cost of some number of dependencies.
However, "number of package distributions" is just not a terribly great
metric to measure complexity.  For example, the :mod:`zope.event`
distribution on which :app:`Pyramid` depends has a grand total of four lines
of runtime code.  As noted above, we're continually trying to agitate for a
collapsing of these sorts of packages into fewer distribution files.

Pyramid "Cheats" To Obtain Speed
--------------------------------

Complaints have been lodged by other web framework authors at various times
that :app:`Pyramid` "cheats" to gain performance.  One claimed cheating
mechanism is our use (transitively) of the C extensions provided by
:mod:`zope.interface` to do fast lookups.  Another claimed cheating mechanism
is the religious avoidance of extraneous function calls.

If there's such a thing as cheating to get better performance, we want to
cheat as much as possible.  We optimize :app:`Pyramid` aggressively.  This
comes at a cost: the core code has sections that could be expressed more
readably.  As an amelioration, we've commented these sections liberally.

Pyramid Gets Its Terminology Wrong ("MVC")
------------------------------------------

"I'm a MVC web framework user, and I'm confused.  :app:`Pyramid` calls the
controller a view!  And it doesn't have any controllers."

If you are in this camp, you might have come to expect things about how your
existing "MVC" framework uses its terminology.  For example, you probably
expect that models are ORM models, controllers are classes that have methods
that map to URLs, and views are templates.  :app:`Pyramid` indeed has each of
these concepts, and each probably *works* almost exactly like your existing
"MVC" web framework. We just don't use the "MVC" terminology, as we can't
square its usage in the web framework space with historical reality.

People very much want to give web applications the same properties as common
desktop GUI platforms by using similar terminology, and to provide some frame
of reference for how various components in the common web framework might
hang together.  But in the opinion of the author, "MVC" doesn't match the web
very well in general. Quoting from the `Model-View-Controller Wikipedia entry
<http://en.wikipedia.org/wiki/Model–view–controller>`_:

.. code-block:: text

  Though MVC comes in different flavors, control flow is generally as
  follows:

    The user interacts with the user interface in some way (for
    example, presses a mouse button).

    The controller handles the input event from the user interface,
    often via a registered handler or callback and converts the event
    into appropriate user action, understandable for the model.

    The controller notifies the model of the user action, possibly  
    resulting in a change in the model's state. (For example, the
    controller updates the user's shopping cart.)[5]

    A view queries the model in order to generate an appropriate
    user interface (for example, the view lists the shopping cart's     
    contents). Note that the view gets its own data from the model.

    The controller may (in some implementations) issue a general
    instruction to the view to render itself. In others, the view is
    automatically notified by the model of changes in state
    (Observer) which require a screen update.

    The user interface waits for further user interactions, which
    restarts the cycle.

To the author, it seems as if someone edited this Wikipedia definition,
tortuously couching concepts in the most generic terms possible in order to
account for the use of the term "MVC" by current web frameworks.  I doubt
such a broad definition would ever be agreed to by the original authors of
the MVC pattern.  But *even so*, it seems most "MVC" web frameworks fail to
meet even this falsely generic definition.

For example, do your templates (views) always query models directly as is
claimed in "note that the view gets its own data from the model"?  Probably
not.  My "controllers" tend to do this, massaging the data for easier use by
the "view" (template). What do you do when your "controller" returns JSON? Do
your controllers use a template to generate JSON? If not, what's the "view"
then?  Most MVC-style GUI web frameworks have some sort of event system
hooked up that lets the view detect when the model changes.  The web just has
no such facility in its current form: it's effectively pull-only.

So, in the interest of not mistaking desire with reality, and instead of
trying to jam the square peg that is the web into the round hole of "MVC", we
just punt and say there are two things: resources and views. The resource
tree represents a site structure, the view presents a resource.  The
templates are really just an implementation detail of any given view: a view
doesn't need a template to return a response.  There's no "controller": it
just doesn't exist.  The "model" is either represented by the resource tree
or by a "domain model" (like a SQLAlchemy model) that is separate from the
framework entirely.  This seems to us like more reasonable terminology, given
the current constraints of the web.

.. _apps_are_extensible:

Pyramid Applications are Extensible; I Don't Believe In Application Extensibility
---------------------------------------------------------------------------------

Any :app:`Pyramid` application written obeying certain constraints is
*extensible*. This feature is discussed in the :app:`Pyramid` documentation
chapters named :ref:`extending_chapter` and :ref:`advconfig_narr`.  It is
made possible by the use of the :term:`Zope Component Architecture` and
within :app:`Pyramid`.

"Extensible", in this context, means:

- The behavior of an application can be overridden or extended in a
  particular *deployment* of the application without requiring that
  the deployer modify the source of the original application.

- The original developer is not required to anticipate any
  extensibility plugpoints at application creation time to allow
  fundamental application behavior to be overriden or extended.

- The original developer may optionally choose to anticipate an
  application-specific set of plugpoints, which may be hooked by
  a deployer.  If he chooses to use the facilities provided by the
  ZCA, the original developer does not need to think terribly hard
  about the mechanics of introducing such a plugpoint.

Many developers seem to believe that creating extensible applications is "not
worth it".  They instead suggest that modifying the source of a given
application for each deployment to override behavior is more reasonable.
Much discussion about version control branching and merging typically ensues.

It's clear that making every application extensible isn't required.  The
majority of web applications only have a single deployment, and thus needn't
be extensible at all.  However, some web applications have multiple
deployments, and some have *many* deployments.  For example, a generic
"content management" system (CMS) may have basic functionality that needs to
be extended for a particular deployment.  That CMS system may be deployed for
many organizations at many places.  Some number of deployments of this CMS
may be deployed centrally by a third party and managed as a group.  It's
useful to be able to extend such a system for each deployment via preordained
plugpoints than it is to continually keep each software branch of the system
in sync with some upstream source: the upstream developers may change code in
such a way that your changes to the same codebase conflict with theirs in
fiddly, trivial ways.  Merging such changes repeatedly over the lifetime of a
deployment can be difficult and time consuming, and it's often useful to be
able to modify an application for a particular deployment in a less invasive
way.

If you don't want to think about :app:`Pyramid` application extensibility at
all, you needn't.  You can ignore extensibility entirely.  However, if you
follow the set of rules defined in :ref:`extending_chapter`, you don't need
to *make* your application extensible: any application you write in the
framework just *is* automatically extensible at a basic level.  The
mechanisms that deployers use to extend it will be necessarily coarse:
typically, views, routes, and resources will be capable of being
overridden. But for most minor (and even some major) customizations, these
are often the only override plugpoints necessary: if the application doesn't
do exactly what the deployment requires, it's often possible for a deployer
to override a view, route, or resource and quickly make it do what he or she
wants it to do in ways *not necessarily anticipated by the original
developer*.  Here are some example scenarios demonstrating the benefits of
such a feature.

- If a deployment needs a different styling, the deployer may override the
  main template and the CSS in a separate Python package which defines
  overrides.

- If a deployment needs an application page to do something differently needs
  it to expose more or different information, the deployer may override the
  view that renders the page within a separate Python package.

- If a deployment needs an additional feature, the deployer may add a view to
  the override package.

As long as the fundamental design of the upstream package doesn't change,
these types of modifications often survive across many releases of the
upstream package without needing to be revisited.

Extending an application externally is not a panacea, and carries a set of
risks similar to branching and merging: sometimes major changes upstream will
cause you to need to revisit and update some of your modifications.  But you
won't regularly need to deal wth meaningless textual merge conflicts that
trivial changes to upstream packages often entail when it comes time to
update the upstream package, because if you extend an application externally,
there just is no textual merge done.  Your modifications will also, for
whatever its worth, be contained in one, canonical, well-defined place.

Branching an application and continually merging in order to get new features
and bugfixes is clearly useful.  You can do that with a :app:`Pyramid`
application just as usefully as you can do it with any application.  But
deployment of an application written in :app:`Pyramid` makes it possible to
avoid the need for this even if the application doesn't define any plugpoints
ahead of time.  It's possible that promoters of competing web frameworks
dismiss this feature in favor of branching and merging because applications
written in their framework of choice aren't extensible out of the box in a
comparably fundamental way.

While :app:`Pyramid` application are fundamentally extensible even if you
don't write them with specific extensibility in mind, if you're moderately
adventurous, you can also take it a step further.  If you learn more about
the :term:`Zope Component Architecture`, you can optionally use it to expose
other more domain-specific configuration plugpoints while developing an
application.  The plugpoints you expose needn't be as coarse as the ones
provided automatically by :app:`Pyramid` itself.  For example, you might
compose your own directive that configures a set of views for a prebaked
purpose (e.g. ``restview`` or somesuch) , allowing other people to refer to
that directive when they make declarations in the ``includeme`` of their
customization package.  There is a cost for this: the developer of an
application that defines custom plugpoints for its deployers will need to
understand the ZCA or he will need to develop his own similar extensibility
system.

Ultimately, any argument about whether the extensibility features lent to
applications by :app:`Pyramid` are "good" or "bad" is mostly pointless. You
needn't take advantage of the extensibility features provided by a particular
:app:`Pyramid` application in order to affect a modification for a particular
set of its deployments.  You can ignore the application's extensibility
plugpoints entirely, and instead use version control branching and merging to
manage application deployment modifications instead, as if you were deploying
an application written using any other web framework.

Zope 3 Enforces "TTW" Authorization Checks By Default; Pyramid Does Not
-----------------------------------------------------------------------

Challenge
+++++++++

:app:`Pyramid` performs automatic authorization checks only at :term:`view`
execution time.  Zope 3 wraps context objects with a `security proxy
<http://wiki.zope.org/zope3/WhatAreSecurityProxies>`_, which causes Zope 3 to
do also security checks during attribute access.  I like this, because it
means:

#) When I use the security proxy machinery, I can have a view that
   conditionally displays certain HTML elements (like form fields) or
   prevents certain attributes from being modified depending on the the
   permissions that the accessing user possesses with respect to a context
   object.

#) I want to also expose my resources via a REST API using Twisted Web. If
   Pyramid performed authorization based on attribute access via Zope3's
   security proxies, I could enforce my authorization policy in both
   :app:`Pyramid` and in the Twisted-based system the same way.

Defense
+++++++

:app:`Pyramid` was developed by folks familiar with Zope 2, which has a
"through the web" security model.  This "TTW" security model was the
precursor to Zope 3's security proxies.  Over time, as the :app:`Pyramid`
developers (working in Zope 2) created such sites, we found authorization
checks during code interpretation extremely useful in a minority of projects.
But much of the time, TTW authorization checks usually slowed down the
development velocity of projects that had no delegation requirements.  In
particular, if we weren't allowing "untrusted" users to write arbitrary
Python code to be executed by our application, the burden of "through the
web" security checks proved too costly to justify.  We (collectively) haven't
written an application on top of which untrusted developers are allowed to
write code in many years, so it seemed to make sense to drop this model by
default in a new web framework.

And since we tend to use the same toolkit for all web applications, it's just
never been a concern to be able to use the same set of restricted-execution
code under two web different frameworks.

Justifications for disabling security proxies by default notwithstanding,
given that Zope 3 security proxies are "viral" by nature, the only
requirement to use one is to make sure you wrap a single object in a security
proxy and make sure to access that object normally when you want proxy
security checks to happen.  It is possible to override the :app:`Pyramid`
"traverser" for a given application (see :ref:`changing_the_traverser`).  To
get Zope3-like behavior, it is possible to plug in a different traverser
which returns Zope3-security-proxy-wrapped objects for each traversed object
(including the :term:`context` and the :term:`root`).  This would have the
effect of creating a more Zope3-like environment without much effort.

.. _http_exception_hierarchy:

Pyramid Uses its Own HTTP Exception Class Hierarchy Rather Than ``webob.exc``
-----------------------------------------------------------------------------

.. note:: This defense is new as of Pyramid 1.1.

The HTTP exception classes defined in :mod:`pyramid.httpexceptions` are very
much like the ones defined in ``webob.exc``
(e.g. :class:`~pyramid.httpexceptions.HTTPNotFound`,
:class:`~pyramid.httpexceptions.HTTPForbidden`, etc).  They have the same
names and largely the same behavior and all have a very similar
implementation, but not the same identity.  Here's why they have a separate
identity:

- Making them separate allows the HTTP exception classes to subclass
  :class:`pyramid.response.Response`.  This speeds up response generation
  slightly due to the way the Pyramid router works.  The same speedup could
  be gained by monkeypatching ``webob.response.Response`` but it's usually
  the case that monkeypatching turns out to be evil and wrong.

- Making them separate allows them to provide alternate ``__call__`` logic
  which also speeds up response generation.

- Making them separate allows the exception classes to provide for the proper
  value of ``RequestClass`` (:class:`pyramid.request.Request`).

- Making them separate allows us freedom from having to think about backwards
  compatibility code present in ``webob.exc`` having to do with Python 2.4,
  which we no longer support in Pyramid 1.1+.

- We change the behavior of two classes
  (:class:`~pyramid.httpexceptions.HTTPNotFound` and
  :class:`~pyramid.httpexceptions.HTTPForbidden`) in the module so that they
  can be used by Pyramid internally for notfound and forbidden exceptions.

- Making them separate allows us to influence the docstrings of the exception
  classes to provide Pyramid-specific documentation.

- Making them separate allows us to silence a stupid deprecation warning
  under Python 2.6 when the response objects are used as exceptions (related
  to ``self.message``).

.. _simpler_traversal_model:

Pyramid has Simpler Traversal Machinery than Does Zope
------------------------------------------------------

Zope's default traverser:

- Allows developers to mutate the traversal name stack while traversing (they
  can add and remove path elements).

- Attempts to use an adaptation to obtain the "next" element in the path from
  the currently traversed object, falling back to ``__bobo_traverse__``,
  ``__getitem__`` and eventually ``__getattr__``.

Zope's default traverser allows developers to mutate the traversal name stack
during traversal by mutating ``REQUEST['TraversalNameStack']``.  Pyramid's
default traverser (``pyramid.traversal.ResourceTreeTraverser``) does not
offer a way to do this; it does not maintain a stack as a request attribute
and, even if it did, it does not pass the request to resource objects while
it's traversing.  While it was handy at times, this feature was abused in
frameworks built atop Zope (like CMF and Plone), often making it difficult to
tell exactly what was happening when a traversal didn't match a view.  I felt
it was better to make folks that wanted the feature replace the traverser
rather than build that particular honey pot in to the default traverser.

Zope uses multiple mechanisms to attempt to obtain the next element in the
resource tree based on a name.  It first tries an adaptation of the current
resource to ``ITraversable``, and if that fails, it falls back to attempting
number of magic methods on the resource (``__bobo_traverse__``,
``__getitem__``, and ``__getattr__``).  My experience while both using Zope
and attempting to reimplement its publisher in ``repoze.zope2`` led me to
believe the following:

- The *default* traverser should be as simple as possible.  Zope's publisher
  is somewhat difficult to follow and replicate due to the fallbacks it tried
  when one traversal method failed.  It is also slow.

- The *entire traverser* should be replaceable, not just elements of the
  traversal machinery.  Pyramid has a few "big" components rather than a
  plethora of small ones.  If the entire traverser is replaceable, it's an
  antipattern to make portions of the default traverser replaceable.  Doing
  so is a "knobs on knobs" pattern, which is unfortunately somewhat endemic
  in Zope.  In a "knobs on knobs" pattern, a replaceable subcomponent of a
  larger component is made configurable using the same configuration
  mechanism that can be used to replace the larger component.  For example,
  in Zope, you can replace the default traverser by registering an adapter.
  But you can also (or alternately) control how the default traverser
  traverses by registering one or more adapters.  As a result of being able
  to either replace the larger component entirely or turn knobs on the
  default implementation of the larger component, no one understands when (or
  whether) they should ever override the larger component entrirely.  This
  results, over time, in a "rusting together" of the larger "replaceable"
  component and the framework itself, because people come to depend on the
  availability of the default component in order just to turn its knobs. The
  default component effectively becomes part of the framework, which entirely
  subverts the goal of making it replaceable.  In Pyramid, typically if a
  component is replaceable, it will itself have no knobs (it will be "solid
  state").  If you want to influence behavior controlled by that component,
  you will replace the component instead of turning knobs attached to the
  component.

.. _microframeworks_smaller_hello_world:

Microframeworks Have Smaller Hello World Programs
-------------------------------------------------

Self-described "microframeworks" exist: `Bottle <http://bottle.paws.de>`_ and
`Flask <http://flask.pocoo.org/>`_ are two that are becoming popular.  `Bobo
<http://bobo.digicool.com/>`_ doesn't describe itself as a microframework,
but its intended userbase is much the same.  Many others exist.  We've
actually even (only as a teaching tool, not as any sort of official project)
`created one using BFG <http://bfg.repoze.org/videos#groundhog1>`_ (the
precursor to Pyramid). Microframeworks are small frameworks with one common
feature: each allows its users to create a fully functional application that
lives in a single Python file.

Some developers and microframework authors point out that Pyramid's "hello
world" single-file program is longer (by about five lines) than the
equivalent program in their favorite microframework.  Guilty as charged.

This loss isn't for lack of trying. Pyramid is useful in the same
circumstance in which microframeworks claim dominance: single-file
applications.  But Pyramid doesn't sacrifice its ability to credibly support
larger applications in order to achieve hello-world LoC parity with the
current crop of microframeworks.  Pyramid's design instead tries to avoid
some common pitfalls associated with naive declarative configuration schemes.
The subsections which follow explain the rationale.

.. _you_dont_own_modulescope:

Application Programmers Don't Control The Module-Scope Codepath (Import-Time Side-Effects Are Evil)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Please imagine a directory structure with a set of Python files in it:

.. code-block:: text

    .
    |-- app.py
    |-- app2.py
    `-- config.py

The contents of ``app.py``:

.. code-block:: python
    :linenos:

    from config import decorator
    from config import L
    import pprint

    @decorator
    def foo():
        pass

    if __name__ == '__main__':
        import app2
        pprint.pprint(L)

The contents of ``app2.py``:

.. code-block:: python
    :linenos:

    import app

    @app.decorator
    def bar():
        pass

The contents of ``config.py``:

.. code-block:: python
  :linenos:

    L = []

    def decorator(func):
        L.append(func)
        return func

If we cd to the directory that holds these files and we run ``python app.py``
given the directory structure and code above, what happens?  Presumably, our
``decorator`` decorator will be used twice, once by the decorated function
``foo`` in ``app.py`` and once by the decorated function ``bar`` in
``app2.py``.  Since each time the decorator is used, the list ``L`` in
``config.py`` is appended to, we'd expect a list with two elements to be
printed, right?  Sadly, no:

.. code-block:: text

    [chrism@thinko]$ python app.py 
    [<function foo at 0x7f4ea41ab1b8>,
     <function foo at 0x7f4ea41ab230>,
     <function bar at 0x7f4ea41ab2a8>]

By visual inspection, that outcome (three different functions in the list)
seems impossible.  We only defined two functions and we decorated each of
those functions only once, so we believe that the ``decorator`` decorator
will only run twice.  However, what we believe is wrong because the code at
module scope in our ``app.py`` module was *executed twice*.  The code is
executed once when the script is run as ``__main__`` (via ``python app.py``),
and then it is executed again when ``app2.py`` imports the same file as
``app``.

What does this have to do with our comparison to microframeworks?  Many
microframeworks in the current crop (e.g. Bottle, Flask) encourage you to
attach configuration decorators to objects defined at module scope.  These
decorators execute arbitrarily complex registration code which populates a
singleton registry that is a global defined in external Python module.  This
is analogous to the above example: the "global registry" in the above example
is the list ``L``.

Let's see what happens when we use the same pattern with the `Groundhog
<https://github.com/Pylons/groundhog>`_ microframework.  Replace the contents
of ``app.py`` above with this:

.. code-block:: python
    :linenos:

    from config import gh

    @gh.route('/foo/')
    def foo():
        return 'foo'

    if __name__ == '__main__':
        import app2
        pprint.pprint(L)

Replace the contents of ``app2.py`` above with this:

.. code-block:: python
    :linenos:

    import app

    @app.gh.route('/bar/')
    def bar():
        'return bar'

Replace the contents of ``config.py`` above with this:

.. code-block:: python
    :linenos:

    from groundhog import Groundhog
    gh = Groundhog('myapp', 'seekrit')

How many routes will be registered within the routing table of the "gh"
Groundhog application?  If you answered three, you are correct.  How many
would a casual reader (and any sane developer) expect to be registered?  If
you answered two, you are correct.  Will the double registration be a
problem?  With our Groundhog framework's ``route`` method backing this
application, not really.  It will slow the application down a little bit,
because it will need to miss twice for a route when it does not match.  Will
it be a problem with another framework, another application, or another
decorator?  Who knows.  You need to understand the application in its
totality, the framework in its totality, and the chronology of execution to
be able to predict what the impact of unintentional code double-execution
will be.

The encouragement to use decorators which perform population of an external
registry has an unintended consequence: the application developer now must
assert ownership of every codepath that executes Python module scope
code. Module-scope code is presumed by the current crop of decorator-based
microframeworks to execute once and only once; if it executes more than once,
weird things will start to happen.  It is up to the application developer to
maintain this invariant.  Unfortunately, however, in reality, this is an
impossible task, because, Python programmers *do not own the module scope
codepath, and never will*.  Anyone who tries to sell you on the idea that
they do is simply mistaken.  Test runners that you may want to use to run
your code's tests often perform imports of arbitrary code in strange orders
that manifest bugs like the one demonstrated above.  API documentation
generation tools do the same.  Some people even think it's safe to use the
Python ``reload`` command or delete objects from ``sys.modules``, each of
which has hilarious effects when used against code that has import-time side
effects.

Global-registry-mutating microframework programmers therefore will at some
point need to start reading the tea leaves about what *might* happen if
module scope code gets executed more than once like we do in the previous
paragraph.  When Python programmers assume they can use the module-scope
codepath to run arbitrary code (especially code which populates an external
registry), and this assumption is challenged by reality, the application
developer is often required to undergo a painful, meticulous debugging
process to find the root cause of an inevitably obscure symptom.  The
solution is often to rearrange application import ordering or move an import
statement from module-scope into a function body.  The rationale for doing so
can never be expressed adequately in the checkin message which accompanies
the fix and can't be documented succinctly enough for the benefit of the rest
of the development team so that the problem never happens again.  It will
happen again, especially if you are working on a project with other people
who haven't yet internalized the lessons you learned while you stepped
through module-scope code using ``pdb``.  This is a really pretty poor
situation to find yourself in as an application developer: you probably
didn't even know your or your team signed up for the job, because the
documentation offered by decorator-based microframeworks don't warn you about
it.

Folks who have a large investment in eager decorator-based configuration that
populates an external data structure (such as microframework authors) may
argue that the set of circumstances I outlined above is anomalous and
contrived.  They will argue that it just will never happen.  If you never
intend your application to grow beyond one or two or three modules, that's
probably true.  However, as your codebase grows, and becomes spread across a
greater number of modules, the circumstances in which module-scope code will
be executed multiple times will become more and more likely to occur and less
and less predictable.  It's not responsible to claim that double-execution of
module-scope code will never happen.  It will; it's just a matter of luck,
time, and application complexity.

If microframework authors do admit that the circumstance isn't contrived,
they might then argue that "real" damage will never happen as the result of
the double-execution (or triple-execution, etc) of module scope code.  You
would be wise to disbelieve this assertion.  The potential outcomes of
multiple execution are too numerous to predict because they involve delicate
relationships between application and framework code as well as chronology of
code execution.  It's literally impossible for a framework author to know
what will happen in all circumstances.  But even if given the gift of
omniscience for some limited set of circumstances, the framework author
almost certainly does not have the double-execution anomaly in mind when
coding new features.  He's thinking of adding a feature, not protecting
against problems that might be caused by the 1% multiple execution case.
However, any 1% case may cause 50% of your pain on a project, so it'd be nice
if it never occured.

Responsible microframeworks actually offer a back-door way around the
problem.  They allow you to disuse decorator based configuration entirely.
Instead of requiring you to do the following:

.. code-block:: python
    :linenos:

    gh = Groundhog('myapp', 'seekrit')

    @gh.route('/foo/')
    def foo():
        return 'foo'

    if __name__ == '__main__':
        gh.run()

They allow you to disuse the decorator syntax and go almost-all-imperative:

.. code-block:: python
    :linenos:

    def foo():
        return 'foo'

    gh = Groundhog('myapp', 'seekrit')

    if __name__ == '__main__':
        gh.add_route(foo, '/foo/')
        gh.run()

This is a generic mode of operation that is encouraged in the Pyramid
documentation. Some existing microframeworks (Flask, in particular) allow for
it as well.  None (other than Pyramid) *encourage* it.  If you never expect
your application to grow beyond two or three or four or ten modules, it
probably doesn't matter very much which mode you use.  If your application
grows large, however, imperative configuration can provide better
predictability.

.. note::

  Astute readers may notice that Pyramid has configuration decorators too.
  Aha!  Don't these decorators have the same problems?  No.  These decorators
  do not populate an external Python module when they are executed.  They
  only mutate the functions (and classes and methods) they're attached to.
  These mutations must later be found during a "scan" process that has a
  predictable and structured import phase.  Module-localized mutation is
  actually the best-case circumstance for double-imports; if a module only
  mutates itself and its contents at import time, if it is imported twice,
  that's OK, because each decorator invocation will always be mutating an
  independent copy of the object its attached to, not a shared resource like
  a registry in another module.  This has the effect that
  double-registrations will never be performed.

Routes (Usually) Need Relative Ordering
+++++++++++++++++++++++++++++++++++++++

Consider the following simple `Groundhog
<https://github.com/Pylons/groundhog>`_ application:

.. code-block:: python
    :linenos:

    from groundhog import Groundhog
    app = Groundhog('myapp', 'seekrit')

    app.route('/admin')
    def admin():
        return '<html>admin page</html>'

    app.route('/:action')
    def action():
        if action == 'add':
           return '<html>add</html>'
        if action == 'delete':
           return '<html>delete</html>'
        return app.abort(404)

    if __name__ == '__main__':
        app.run()

If you run this application and visit the URL ``/admin``, you will see
"admin" page.  This is the intended result.  However, what if you rearrange
the order of the function definitions in the file?

.. code-block:: python
    :linenos:

    from groundhog import Groundhog
    app = Groundhog('myapp', 'seekrit')

    app.route('/:action')
    def action():
        if action == 'add':
           return '<html>add</html>'
        if action == 'delete':
           return '<html>delete</html>'
        return app.abort(404)

    app.route('/admin')
    def admin():
        return '<html>admin page</html>'

    if __name__ == '__main__':
        app.run()

If you run this application and visit the URL ``/admin``, you will now be
returned a 404 error.  This is probably not what you intended.  The reason
you see a 404 error when you rearrange function definition ordering is that
routing declarations expressed via our microframework's routing decorators
have an *ordering*, and that ordering matters.

In the first case, where we achieved the expected result, we first added a
route with the pattern ``/admin``, then we added a route with the pattern
``/:action`` by virtue of adding routing patterns via decorators at module
scope.  When a request with a ``PATH_INFO`` of ``/admin`` enters our
application, the web framework loops over each of our application's route
patterns in the order in which they were defined in our module.  As a result,
the view associated with the ``/admin`` routing pattern will be invoked: it
matches first.  All is right with the world.

In the second case, where we did not achieve the expected result, we first
added a route with the pattern ``/:action``, then we added a route with the
pattern ``/admin``.  When a request with a ``PATH_INFO`` of ``/admin`` enters
our application, the web framework loops over each of our application's route
patterns in the order in which they were defined in our module.  As a result,
the view associated with the ``/:action`` routing pattern will be invoked: it
matches first.  A 404 error is raised.  This is not what we wanted; it just
happened due to the order in which we defined our view functions.

You may be willing to maintain an ordering of your view functions which
reifies your routing policy.  Your application may be small enough where this
will never cause an issue.  If it becomes large enough to matter, however, I
don't envy you.  Maintaining that ordering as your application grows larger
will be difficult.  At some point, you will also need to start controlling
*import* ordering as well as function definition ordering.  When your
application grows beyond the size of a single file, and when decorators are
used to register views, the non-``__main__`` modules which contain
configuration decorators must be imported somehow for their configuration to
be executed.

Does that make you a little uncomfortable?  It should, because
:ref:`you_dont_own_modulescope`.

"Stacked Object Proxies" Are Too Clever / Thread Locals Are A Nuisance
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

In another manifestation of "import fascination", some microframeworks use
the ``import`` statement to get a handle to an object which *is not logically
global*:

.. code-block:: python
    :linenos:

    from flask import request

    @app.route('/login', methods=['POST', 'GET'])
    def login():
        error = None
        if request.method == 'POST':
            if valid_login(request.form['username'],
                           request.form['password']):
                return log_the_user_in(request.form['username'])
            else:
                error = 'Invalid username/password'
        # this is executed if the request method was GET or the
        # credentials were invalid    

The `Pylons 1.X <http://pylonsproject.org>`_ web framework uses a similar
strategy.  It calls these things "Stacked Object Proxies", so, for purposes
of this discussion, I'll do so as well.

Import statements in Python (``import foo``, ``from bar import baz``) are
most frequently performed to obtain a reference to an object defined globally
within an external Python module.  However, in "normal" programs, they are
never used to obtain a reference to an object that has a lifetime measured by
the scope of the body of a function.  It would be absurd to try to import,
for example, a variable named ``i`` representing a loop counter defined in
the body of a function.  For example, we'd never try to import ``i`` from the
code below:

.. code-block::  python
   :linenos:

   def afunc():
       for i in range(10):
           print i

By its nature, the *request* object created as the result of a WSGI server's
call into a long-lived web framework cannot be global, because the lifetime
of a single request will be much shorter than the lifetime of the process
running the framework.  A request object created by a web framework actually
has more similarity to the ``i`` loop counter in our example above than it
has to any comparable importable object defined in the Python standard
library or in "normal" library code.

However, systems which use stacked object proxies promote locally scoped
objects such as ``request`` out to module scope, for the purpose of being
able to offer users a "nice" spelling involving ``import``.  They, for what I
consider dubious reasons, would rather present to their users the canonical
way of getting at a ``request`` as ``from framework import request`` instead
of a saner ``from myframework.threadlocals import get_request; request =
get_request()`` even though the latter is more explicit.

It would be *most* explicit if the microframeworks did not use thread local
variables at all.  Pyramid view functions are passed a request object; many
of Pyramid's APIs require that an explicit request object be passed to them.
It is *possible* to retrieve the current Pyramid request as a threadlocal
variable but it is a "in case of emergency, break glass" type of activity.
This explicitness makes Pyramid view functions more easily unit testable, as
you don't need to rely on the framework to manufacture suitable "dummy"
request (and other similarly-scoped) objects during test setup.  It also
makes them more likely to work on arbitrary systems, such as async servers
that do no monkeypatching.

Explicitly WSGI
+++++++++++++++

Some microframeworks offer a ``run()`` method of an application object that
executes a default server configuration for easy execution.

Pyramid doesn't currently try to hide the fact that its router is a WSGI
application behind a convenience ``run()`` API.  It just tells people to
import a WSGI server and use it to serve up their Pyramid application as per
the documentation of that WSGI server.

The extra lines saved by abstracting away the serving step behind ``run()``
seem to have driven dubious second-order decisions related to API in some
microframeworks.  For example, Bottle contains a ``ServerAdapter`` subclass
for each type of WSGI server it supports via its ``app.run()`` mechanism.
This means that there exists code in ``bottle.py`` that depends on the
following modules: ``wsgiref``, ``flup``, ``paste``, ``cherrypy``, ``fapws``,
``tornado``, ``google.appengine``, ``twisted.web``, ``diesel``, ``gevent``,
``gunicorn``, ``eventlet``, and ``rocket``.  You choose the kind of server
you want to run by passing its name into the ``run`` method.  In theory, this
sounds great: I can try Bottle out on ``gunicorn`` just by passing in a name!
However, to fully test Bottle, all of these third-party systems must be
installed and functional; the Bottle developers must monitor changes to each
of these packages and make sure their code still interfaces properly with
them.  This expands the packages required for testing greatly; this is a
*lot* of requirements.  It is likely difficult to fully automate these tests
due to requirements conflicts and build issues.

As a result, for single-file apps, we currently don't bother to offer a
``run()`` shortcut; we tell folks to import their WSGI server of choice and
run it "by hand".  For the people who want a server abstraction layer, we
suggest that they use PasteDeploy.  In PasteDeploy-based systems, the onus
for making sure that the server can interface with a WSGI application is
placed on the server developer, not the web framework developer, making it
more likely to be timely and correct.

Wrapping Up
+++++++++++

Here's a diagrammed version of the simplest pyramid application, where
comments take into account what we've discussed in the
:ref:`microframeworks_smaller_hello_world` section.

.. code-block:: python
   :linenos:

   from pyramid.response import Response      # explicit response objects, no TL
   from paste.httpserver import serve         # explicitly WSGI

   def hello_world(request):  # accepts a request; no request thread local reqd
       # explicit response object means no response threadlocal
       return Response('Hello world!') 

   if __name__ == '__main__':
       from pyramid.config import Configurator
       config = Configurator()       # no global application object.
       config.add_view(hello_world)  # explicit non-decorator registration
       app = config.make_wsgi_app()  # explicitly WSGI
       serve(app, host='0.0.0.0')    # explicitly WSGI

Pyramid Doesn't Offer Pluggable Apps
------------------------------------

It is "Pyramidic" to compose multiple external sources into the same
configuration using :meth:`~pyramid.config.Configuration.include`.  Any
number of includes can be done to compose an application; includes can even
be done from within other includes.  Any directive can be used within an
include that can be used outside of one (such as
:meth:`~pyramid.config.Configurator.add_view`, etc).

Pyramid has a conflict detection system that will throw an error if two 
included externals try to add "the same" configuration in a conflicting 
way (such as both externals trying to add a route using the same name, 
or both externals trying to add a view with the same set of predicates). 
It's awful tempting to call this set of features something that can be 
used to compose a system out of "pluggable applications".  But in 
reality, there are a number of problems with claiming this: 

- The terminology is strained. Pyramid really has no notion of a 
  plurality of "applications", just a way to compose configuration 
  from multiple sources to create a single WSGI application.  That 
  WSGI application may gain behavior by including or disincluding 
  configuration, but once it's all composed together, Pyramid 
  doesn't really provide any machinery which can be used to demarcate 
  the boundaries of one "application" (in the sense of configuration 
  from an external that adds routes, views, etc) from another. 

- Pyramid doesn't provide enough "rails" to make it possible to 
  integrate truly honest-to-god, download-an-app-from-a-random-place 
  and-plug-it-in-to-create-a-system "pluggable" applications. 
  Because Pyramid itself isn't opinionated (it doesn't mandate a 
  particular kind of database, it offers multiple ways to map URLs 
  to code, etc), it's unlikely that someone who creates something 
  "application-like" will be able to casually redistribute it 
  to J. Random Pyramid User and have it "just work" by asking him 
  to config.include a function from the package. 
  This is particularly true of very high level components such 
  as blogs, wikis, twitter clones, commenting systems, etc. 
  The "integrator" (the Pyramid developer who has downloaded a 
  package advertised as a "pluggable app") will almost certainly 
  have made different choices about e.g. what type of persistence 
  system he's using, and for the integrator to appease the 
  requirements of the "pluggable application", he may be required 
  to set up a different database, make changes to his own code 
  to prevent his application from "shadowing" the pluggable 
  app (or vice versa), and any other number of arbitrary 
  changes. 

For this reason, we claim that Pyramid has "extensible" applications, 
not pluggable applications.  Any Pyramid application can be extended 
without forking it as long as its configuration statements have been 
composed into things that can be pulled in via "config.include". 

It's also perfectly reasonable for a single developer or team to create a set
of interoperating components which can be enabled or disabled by using
config.include.  That developer or team will be able to provide the "rails"
(by way of making high-level choices about the technology used to create the
project, so there won't be any issues with plugging all of the components
together.  The problem only rears its head when the components need to be
distributed to *arbitrary* users.  Note that Django has a similar problem
with "pluggable applications" that need to work for arbitrary third parties,
even though they provide many, many more rails than does Pyramid.  Even the
rails they provide are not enough to make the "pluggable application" story
really work without local modification.

Truly pluggable applications need to be created at a much higher level than a
web framework, as no web framework can offer enough constraints to really
make them "work out of the box".  They really need to plug into an
application, instead.  It would be a noble goal to build an application with
Pyramid that provides these constraints and which truly does offer a way to
plug in applications (Joomla, Plone, Drupal come to mind).

Pyramid Has Zope Things In It, So It's Too Complex
--------------------------------------------------

On occasion, someone will feel compelled to post a mailing list message that
reads something like this:

.. code-block:: text

   had a quick look at pyramid ... too complex to me and not really
   understand for which benefits.. I feel should consider whether it's time
   for me to step back to django .. I always hated zope (useless ?)
   complexity and I love simple way of thinking

(Paraphrased from a real email, actually.)

Let's take this criticism point-by point.

Too Complex
+++++++++++

If you can understand this hello world program, you can use Pyramid:

.. code-block:: python
   :linenos:

   from paste.httpserver import serve
   from pyramid.config import Configurator
   from pyramid.response import Response

   def hello_world(request):
       return Response('Hello world!')

   if __name__ == '__main__':
       config = Configurator()
       config.add_view(hello_world)
       app = config.make_wsgi_app()
       serve(app)

Pyramid has ~ 650 pages of documentation (printed), covering topics from the
very basic to the most advanced.  *Nothing* is left undocumented, quite
literally.  It also has an *awesome*, very helpful community.  Visit the
#repoze and/or #pylons IRC channels on freenode.net and see.

Hate Zope
+++++++++

I'm sorry you feel that way.  The Zope brand has certainly taken its share of
lumps over the years, and has a reputation for being insular and mysterious.
But the word "Zope" is literally quite meaningless without qualification.
What *part* of Zope do you hate?  "Zope" is a brand, not a technology.

If it's Zope2-the-web-framework, Pyramid is not that.  The primary designers
and developers of Pyramid, if anyone, should know.  We wrote Pyramid's
predecessor (:mod:`repoze.bfg`), in part, because *we* knew that Zope 2 had
usability issues and limitations.  :mod:`repoze.bfg` (and now :app:`Pyramid`)
was written to address these issues.

If it's Zope3-the-web-framework, Pyramid is *definitely* not that.  Making
use of lots of Zope 3 technologies is territory already staked out by the
:term:`Grok` project.  Save for the obvious fact that they're both web
frameworks, :mod:`Pyramid` is very, very different than Grok.  Grok exposes
lots of Zope technologies to end users.  On the other hand, if you need to
understand a Zope-only concept while using Pyramid, then we've failed on some
very basic axis.

If it's just the word Zope: this can only be guilt by association.  Because a
piece of software internally uses some package named ``zope.foo``, it doesn't
turn the piece of software that uses it into "Zope".  There is a lot of
*great* software written that has the word Zope in its name.  Zope is not
some sort of monolithic thing, and a lot of its software is usable
externally.  And while it's not really the job of this document to defend it,
Zope has been around for over 10 years and has an incredibly large, active
community.  If you don't believe this,
http://taichino.appspot.com/pypi_ranking/authors is an eye-opening reality
check.

Love Simplicity
+++++++++++++++

Years of effort have gone into honing this package and its documentation to
make it as simple as humanly possible for developers to use.  Everything is a
tradeoff, of course, and people have their own ideas about what "simple" is.
You may have a style difference if you believe Pyramid is complex.  Its
developers obviously disagree.

Other Challenges
----------------

Other challenges are encouraged to be sent to the `Pylons-devel
<http://groups.google.com/group/pylons-devel>`_ maillist.  We'll try to address
them by considering a design change, or at very least via exposition here.
