flesh out categories more

TODO.txt

@@ -8,6 +8,10 @@ Must-Have
 
   * Narrative docs.
 
+  * ``default root factory`` category?
+
+  * ``default view mapper`` category?
+
   * ActionInfo for ZCML actions (begin/end lineno/cols?)
 
   * Document ActionInfo.

docs/narr/introspector.rst

@@ -15,6 +15,10 @@ feature is useful for debug toolbars, command-line scripts which show some
 aspect of configuration, and for runtime reporting of startup-time
 configuration settings.
 
+.. warning::
+
+   Introspection is new in Pyramid 1.3.
+
 Using the Introspector
 ----------------------
 
@@ -86,6 +90,12 @@ The important attributes shared by all introspectables are the following:
   often be a singular version of the category name but it can be an arbitrary
   value.
 
+``action_info``
+
+  An object describing the directive call site which caused this
+  introspectable to be registered; contains attributes described in
+  :class:`pyramid.interfaces.IActionInfo`.
+
 Besides having the attributes described above, an introspectable is a
 dictionary-like object.  An introspectable can be queried for data values via
 its ``__getitem__``, ``get``, ``keys``, ``values``, or ``items`` methods.
@@ -107,7 +117,7 @@ introspectables in categories not described here.
 ``subscribers``
 
   Each introspectable in the ``subscribers`` category represents a call to
-  :meth:`pryamid.config.Configurator.add_subscriber` (or the decorator
+  :meth:`pyramid.config.Configurator.add_subscriber` (or the decorator
   equivalent); each will have the following data.
 
   ``subscriber``
@@ -138,8 +148,6 @@ introspectables in categories not described here.
 
 ``root factories``
 
-  XXX ``default root factory`` category?
-
   Each introspectable in the ``root factories`` category represents a call to
   :meth:`pyramid.config.Configurator.set_root_factory` (or the Configurator
   constructor equivalent) *or* a ``factory`` argument passed to
@@ -435,8 +443,6 @@ introspectables in categories not described here.
 
 ``view mapper``
 
-  XXX default view mapper category?
-
   Each introspectable in the ``permissions`` category represents a call to
   :meth:`pyramid.config.Configurator.add_view` that has an explicit
   ``mapper`` argument to *or* a call to
@@ -450,17 +456,69 @@ introspectables in categories not described here.
 
 ``asset overrides``
 
-  XXX
+  Each introspectable in the ``asset overrides`` category represents a call
+  to :meth:`pyramid.config.Configurator.override_asset`; each will have the
+  following data.
+
+  ``to_override``
+
+    The ``to_override`` argument (an asset spec) passed to
+    ``override_asset``.
+
+  ``override_with``
+
+    The ``override_with`` argument (an asset spec) passed to
+    ``override_asset``.
 
 ``translation directories``
 
-  XXX
+  Each introspectable in the ``asset overrides`` category represents an
+  individual element in a ``specs`` argument passed to to
+  :meth:`pyramid.config.Configurator.add_translation_dirs`; each will have
+  the following data.
+
+  ``directory``
+
+    The absolute path of the translation directory.
+
+  ``spec``
+
+    The asset specification passed to ``add_translation_dirs``.
+
+``tweens``
+
+  Each introspectable in the ``tweens`` category represents a call to
+  :meth:`pyramid.config.Configurator.add_tween`; each will have the following
+  data.
+
+  ``name``
+
+    The dotted name to the tween factory as a string (passed as
+    the ``tween_factory`` argument to ``add_tween``).
+
+  ``factory``
+
+    The (resolved) tween factory object.
+
+  ``type``
+
+    ``implict`` or ``explicit`` as a string.
+
+  ``under``
+
+     The ``under`` argument passed to ``add_tween`` (a string).
+
+  ``over``
+
+     The ``over`` argument passed to ``add_tween`` (a string).
 
-``tweens (implicit)``
+Toolbar Introspection
+---------------------
 
-  XXX
+The Pyramid debug toolbar (part of the ``pyramid_debugtoolbar`` package)
+provides a canned view of all registered introspectables and their
+relationships.  It looks something like this:
 
-``tweens (explicit)``
+.. image:: tb_introspector.png
 
-  XXX
 

pyramid/config/assets.py

@@ -239,14 +239,11 @@ def register():
         intr = self.introspectable(
             'asset overrides',
             (package, override_package, path, override_prefix),
-            '%s/%s -> %s/%s' % (package, path, override_package,
-                                override_prefix),
+            '%s -> %s' % (to_override, override_with),
             'asset override',
             )
-        intr['package'] = package
-        intr['override_package'] = package
-        intr['override_prefix'] = override_prefix
-        intr['path'] = path
+        intr['to_override'] = to_override
+        intr['override_with'] = override_with
         self.action(None, register, introspectables=(intr,))
 
     override_resource = override_asset # bw compat

pyramid/config/i18n.py

@@ -93,6 +93,7 @@ def add_translation_dirs(self, *specs):
             intr = self.introspectable('translation directories', directory,
                                        spec, 'translation directory')
             intr['directory'] = directory
+            intr['spec'] = spec
             introspectables.append(intr)
             directories.append(directory)
 
@@ -106,7 +107,6 @@ def register():
                                                   ITranslationDirectories)
 
                 tdirs.insert(0, directory)
-                # XXX no action?
 
             if directories:
                 # We actually only need an IChameleonTranslate function

pyramid/config/tweens.py

@@ -144,10 +144,11 @@ def is_string_or_iterable(v):
         if tweens is None:
             tweens = Tweens()
             registry.registerUtility(tweens, ITweens)
-            ex_intr = self.introspectable('tweens (implicit)',
+            ex_intr = self.introspectable('tweens',
                                           ('tween', EXCVIEW, False),
                                           EXCVIEW,
                                           'implicit tween')
+            ex_intr['name'] = EXCVIEW
             ex_intr['factory'] = excview_tween_factory
             ex_intr['type'] = 'implicit'
             ex_intr['under'] = None
@@ -164,10 +165,11 @@ def register():
         discriminator = ('tween', name, explicit)
         tween_type = explicit and 'explicit' or 'implicit'
 
-        intr = self.introspectable('tweens (%s)' % tween_type,
+        intr = self.introspectable('tweens',
                                    discriminator,
                                    name,
                                    '%s tween' % tween_type)
+        intr['name'] = name
         intr['factory'] = tween_factory
         intr['type'] = tween_type
         intr['under'] = under

pyramid/config/views.py

@@ -1119,7 +1119,7 @@ def regclosure():
         if mapper:
             mapper_intr = self.introspectable('view mappers',
                                               discriminator,
-                                              view_desc,
+                                              'view mapper for %s' % view_desc,
                                               'view mapper')
             mapper_intr['mapper'] = mapper
             mapper_intr.relate('views', discriminator)