Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Add subheads for clarity, reference.

  • Loading branch information...
commit b39dcef270e64dfce860d14b8cadc25694a64255 1 parent 5190f60
Tres Seaver authored September 17, 2012

Showing 1 changed file with 27 additions and 0 deletions. Show diff stats Hide diff stats

  1. 27  configuration/whirlwind_tour.rst
27  configuration/whirlwind_tour.rst
Source Rendered
... ...
@@ -1,6 +1,9 @@
1 1
 A Whirlwind Tour of Advanced Pyramid Configuration Tactics
2 2
 ==========================================================
3 3
 
  4
+Concepts:  Configuration, Directives, and Statements
  5
+-----------------------------------------------------
  6
+
4 7
 This article attempts to demonstrate some of Pyramid's more advanced
5 8
 startup-time configuration features.  The stuff below talks about
6 9
 "configuration", which is a shorthand word I'll use to mean the state that is
@@ -134,6 +137,9 @@ configuration happens before any view configuration at commit time.  If a
134 137
 view references a nonexistent route, an error will be raised at commit time
135 138
 rather than at configuration statement execution time.
136 139
 
  140
+Sanity Checks
  141
+-------------
  142
+
137 143
 We can see this sanity-checking feature in action in a failure case.  Let's
138 144
 change our application, commenting out our call to ``config.add_route()``
139 145
 temporarily within ``app.py``:
@@ -181,6 +187,9 @@ It's telling us that we attempted to add a view which references a
181 187
 nonexistent route.  Configuration directives sometimes introduce
182 188
 sanity-checking to startup, as demonstrated here.
183 189
 
  190
+Configuration Conflicts
  191
+-----------------------
  192
+
184 193
 Let's change our application once again.  We'll undo our last change, and add
185 194
 a configuration statement that attempts to add another view:
186 195
 
@@ -254,6 +263,9 @@ other in this circumstance; it can't serve both.  So rather than trying to
254 263
 guess what you meant, Pyramid raises a configuration conflict error and
255 264
 refuses to start.
256 265
 
  266
+Resolving Conflicts
  267
+-------------------
  268
+
257 269
 Obviously it's necessary to be able to resolve configuration conflicts.
258 270
 Sometimes these conflicts are done by mistake, so they're easy to resolve.
259 271
 You just change the code so that the conflict is no longer present.  We can
@@ -363,6 +375,9 @@ callback overwrote the view configuration added by the first commit.
363 375
 Calling ``config.commit()`` is a brute-force way to resolve configuration
364 376
 conflicts.
365 377
 
  378
+Including Configuration from Other Modules
  379
+------------------------------------------
  380
+
366 381
 Now that we have played around a bit with configuration that exists all in
367 382
 the same module, let's add some code to ``app.py`` that causes configuration
368 383
 that lives in another module to be *included*.  We do that by adding a call
@@ -446,6 +461,9 @@ just import the moreconfiguration function from ``another`` and call it directly
446 461
 the configurator!"  You're mostly right.  However, ``config.include()`` does
447 462
 more than that.  Please stick with me, we'll get to it.
448 463
 
  464
+The :func:`includeme` Convention
  465
+--------------------------------
  466
+
449 467
 Now, let's change our ``app.py`` slightly.  We'll change the
450 468
 ``config.include()`` line in ``app.py`` to include a slightly different
451 469
 name:
@@ -498,6 +516,9 @@ Pyramid convenience shorthand: if you tell Pyramid to include a Python
498 516
 ``config.include('amodule')`` always means
499 517
 ``config.include('amodule.includeme')``.
500 518
 
  519
+Nested Includes
  520
+---------------
  521
+
501 522
 Something which is included can also do including.  Let's add a file named
502 523
 ``yetanother.py`` next to app.py:
503 524
 
@@ -535,6 +556,9 @@ When we start up this application, we can visit ``/``, ``/goodbye`` and
535 556
 which includes ``yetanother.py``.  You can nest configuration includes within
536 557
 configuration includes ad infinitum.  It's turtles all the way down.
537 558
 
  559
+Automatic Resolution via Includes
  560
+---------------------------------
  561
+
538 562
 As we saw previously, it's relatively easy to manually resolve configuration
539 563
 conflicts that are produced by mistake.  But sometimes configuration
540 564
 conflicts are not injected by mistake.  Sometimes they're introduced on
@@ -595,6 +619,9 @@ just factoring your configuration into functions and arranging to call those
595 619
 functions at startup time directly.  Using ``config.include()`` makes
596 620
 automatic conflict resolution work properly.
597 621
 
  622
+Custom Configuration Directives
  623
+-------------------------------
  624
+
598 625
 A developer needn't satisfy himself with only the directives provided by
599 626
 Pyramid like ``add_route`` and ``add_view``.  He can add directives to the
600 627
 Configurator.  This makes it easy for him to allow other developers to add

0 notes on commit b39dcef

Please sign in to comment.
Something went wrong with that request. Please try again.