From d3255c4c452a1bdee1cb3b91bd3f1c7329cdda00 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 8 Jul 2011 02:30:19 -0400 Subject: point at groundhog github repo (why?) --- docs/designdefense.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index ce3c507c5..b285524c6 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1125,10 +1125,11 @@ Self-described "microframeworks" exist: `Bottle `_ and `_ 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 `_ (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. +`created one using Pyramid `_ (the +videos use BFG, a precursor to Pyramid, but the resulting code is `available +for Pyramid too `_). 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 -- cgit v1.2.3 From 0a585a85a73e276cc4c3e75beb040e4abf952e37 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 14 Jul 2011 18:18:10 -0400 Subject: note that flask does not use import ordering, but complexity ordering --- docs/designdefense.rst | 46 ++++++++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 14 deletions(-) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index b285524c6..cc46462da 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1395,8 +1395,8 @@ predictability. a registry in another module. This has the effect that double-registrations will never be performed. -Routes (Usually) Need Relative Ordering -+++++++++++++++++++++++++++++++++++++++ +Routes Need Relative Ordering ++++++++++++++++++++++++++++++ Consider the following simple `Groundhog `_ application: @@ -1471,18 +1471,36 @@ 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 +This is because "Groundhog" routes are added to the routing map in import +order, and matched in the same order when a request comes in. Bottle, like +Groundhog, as of this writing, matches routes in the order in which they're +defined at Python execution time. Flask, on the other hand, does not order +route matching based on import order; it reorders the routes you add to your +application based on their "complexity". Other microframeworks have varying +strategies to do route ordering. + +Your application may be small enough where route ordering will never cause an +issue. If your application becomes large enough, however, being able to +specify or predict that ordering as your application grows larger will be +difficult. At some point, you will likely need to more explicitly start +controlling route ordering, especially in applications that require +extensibility. + +If your microframework orders route matching based on "complexity", you'll +need to understand what that "complexity" ordering is and attempt to inject a +"less complex" route to have it get matched before any "more complex" one to +ensure that it's tried first. + +If your microframework orders its route matching based on relative +import/execution of function decorator definitions, you will need to ensure +you execute all of these statements in the "right" order, and you'll need to +be cognizant of this import/execution ordering as you grow your application +or try to extend it. This is a difficult invariant to maintain for all but +the smallest applications. + +In either case, your application must import the non-``__main__`` modules +which contain configuration decorations 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 -- cgit v1.2.3 From 1d197536090ecbd6df2dba96f96233c6526968e9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 14 Jul 2011 18:36:35 -0400 Subject: mention traversal --- docs/designdefense.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index cc46462da..ddc643e09 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1503,6 +1503,13 @@ which contain configuration decorations somehow for their configuration to be executed. Does that make you a little uncomfortable? It should, because :ref:`you_dont_own_modulescope`. +In the meantime, in Pyramid, if you don't want to have to maintain relative +route ordering imperatively, you can use :term:`traversal` instead of route +matching, which is a completely declarative (and completely predictable) +mechanism to map code to URLs. While URL dispatch is easier to understand +for small non-extensible applications, traversal is a great fit for very +large applications and applications that need to be arbitrarily extensible. + "Stacked Object Proxies" Are Too Clever / Thread Locals Are A Nuisance ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From 48d4c8afa04d3438e931a686fe54172f4a27345f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 14 Jul 2011 18:41:54 -0400 Subject: we no longer support py24 --- docs/designdefense.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index ddc643e09..22a58155d 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -711,9 +711,9 @@ 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. +you use Python 2.6 or 2.7, or 16 if you use Python 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 -- cgit v1.2.3 From 0428eddb22b02611f1f5e250d916cf705f781aee Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 14 Jul 2011 18:57:40 -0400 Subject: describe what Pyramid does --- docs/designdefense.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 22a58155d..9d3a3d38b 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1503,12 +1503,19 @@ which contain configuration decorations somehow for their configuration to be executed. Does that make you a little uncomfortable? It should, because :ref:`you_dont_own_modulescope`. -In the meantime, in Pyramid, if you don't want to have to maintain relative -route ordering imperatively, you can use :term:`traversal` instead of route -matching, which is a completely declarative (and completely predictable) -mechanism to map code to URLs. While URL dispatch is easier to understand -for small non-extensible applications, traversal is a great fit for very -large applications and applications that need to be arbitrarily extensible. +Pyramid uses neither decorator import time ordering nor does it attempt to +divine the relative "complexity" of one route to another in order to define a +route match ordering. In Pyramid, you have to maintain relative route +ordering imperatively via the chronology of multiple executions of the +:meth:`pyramid.config.Configurator.add_route` method. The order in which you +repeatedly call ``add_route`` becomes the order of route matching. + +If needing to maintain this imperative ordering truly bugs you, you can use +:term:`traversal` instead of route matching, which is a completely +declarative (and completely predictable) mechanism to map code to URLs. +While URL dispatch is easier to understand for small non-extensible +applications, traversal is a great fit for very large applications and +applications that need to be arbitrarily extensible. "Stacked Object Proxies" Are Too Clever / Thread Locals Are A Nuisance ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -- cgit v1.2.3 From 16b93e024e4c16e5684186fa34be2485de1e96ee Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 22 Jul 2011 07:02:10 -0400 Subject: s/repoze/pyramid/ --- docs/designdefense.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/designdefense.rst') diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 9d3a3d38b..4975ae2a0 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -1761,7 +1761,7 @@ If you can understand this hello world program, you can use Pyramid: 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. +#pyramid and/or #pylons IRC channels on freenode.net and see. Hate Zope +++++++++ -- cgit v1.2.3