Roles.

1 files changed, 66 insertions, 59 deletions

diff --git a/repoze/bfg/traversal.py b/repoze/bfg/traversal.py
index 051a4c34c..8003de598 100644
--- a/repoze/bfg/traversal.py
+++ b/repoze/bfg/traversal.py
@@ -28,16 +28,18 @@ def find_root(model):
 
 def find_model(model, path):
     """ Given a model object and a string or tuple representing a path
-    (such as the return value of ``model_path`` or
-    ``model_path_tuple``), return a context in this application's
-    model graph at the specified path.  The model passed in *must* be
-    :term:`location`-aware.  If the path cannot be resolved (if the
-    respective node in the graph does not exist), a KeyError will be
-    raised.
-
-    This function is the logical inverse of ``model_path`` and
-    ``model_path_tuple``; it can resolve any path string or tuple
-    generated by ``model_path`` or ``model_path_tuple``.
+    (such as the return value of
+    :func:`repoze.bfg.traversal.model_path` or
+    :func:`repoze.bfg.traversal.model_path_tuple`), return a context
+    in this application's model graph at the specified path.  The
+    model passed in *must* be :term:`location`-aware.  If the path
+    cannot be resolved (if the respective node in the graph does not
+    exist), a :exc:`KeyError` will be raised.
+
+    This function is the logical inverse of
+    :func:`repoze.bfg.traversal.model_path` and
+    :func:`repoze.bfg.traversal.model_path_tuple`; it can resolve any
+    path string or tuple generated by either of those functions.
 
     Rules for passing a *string* as the ``path`` argument: if the
     first character in the path string is the with the ``/``
@@ -49,11 +51,11 @@ def find_model(model, path):
     empty string is passed as ``path``, the ``model`` passed in will
     be returned.  Model path strings must be escaped in the following
     manner: each Unicode path segment must be encoded as UTF-8 and as
-    each path segment must escaped via Python's ``urllib.quote``.  For
-    example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
-    ``to%20the/La%20Pe%C3%B1a`` (relative).  The ``model_path``
-    function generates strings which follow these rules (albeit only
-    absolute ones).
+    each path segment must escaped via Python's :mod:`urllib.quote`.
+    For example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
+    ``to%20the/La%20Pe%C3%B1a`` (relative).  The
+    :func:`repoze.bfg.traversal.model_path` function generates strings
+    which follow these rules (albeit only absolute ones).
 
     Rules for passing a *tuple* as the ``path`` argument: if the first
     element in the path tuple is the empty string (for example ``('',
@@ -67,7 +69,8 @@ def find_model(model, path):
     URL-quoting or UTF-8-encoding of individual path segments within
     the tuple is required (each segment may be any string or unicode
     object representing a model name).  Model path tuples generated by
-    ``model_path_tuple`` can always be resolved by ``find_model``.
+    :func:`repoze.bfg.traversal.model_path_tuple` can always be
+    resolved by ``find_model``.
     """
     D = traverse(model, path)
     view_name = D['view_name']
@@ -107,12 +110,12 @@ def model_path(model, *elements):
 
     Model path strings returned will be escaped in the following
     manner: each unicode path segment will be encoded as UTF-8 and
-    each path segment will be escaped via Python's ``urllib.quote``.
+    each path segment will be escaped via Python's :mod:`urllib.quote`.
     For example, ``/path/to%20the/La%20Pe%C3%B1a``.
 
-    This function is a logical inverse of ``find_model``: it can be
-    used to generate path references that can later be resolved via
-    ``find_model``.
+    This function is a logical inverse of
+    :mod:`repoze.bfg.traversal.find_model`: it can be used to generate
+    path references that can later be resolved via that function.
 
     The ``model`` passed in *must* be :term:`location`-aware.
 
@@ -124,8 +127,9 @@ def model_path(model, *elements):
               safety checking of model names is performed.  For
               instance, if one of the models in your graph has a
               ``__name__`` which (by error) is a dictionary, the
-              ``model_path`` function will attempt to append it to a
-              string and it will cause a TypeError.
+              :func:`repoze.bfg.traversal.model_path` function will
+              attempt to append it to a string and it will cause a
+              :exc:`TypeError`.
 
     .. note:: The the :term:`root` model *must* have a ``__name__``
               attribute with a value of either ``None`` or the empty
@@ -141,8 +145,8 @@ def model_path(model, *elements):
 def traverse(model, path):
     """Given a model object as ``model`` and a string or tuple
     representing a path as ``path`` (such as the return value of
-    ``repoze.bfg.traversal.model_path`` or
-    ``repoze.bfg.traversal.model_path_tuple`` or the value of
+    :func:`repoze.bfg.traversal.model_path` or
+    :func:`repoze.bfg.traversal.model_path_tuple` or the value of
     ``request.environ['PATH_INFO']``), return a dictionary with the
     keys ``context``, ``root``, ``view_name``, ``subpath``,
     ``traversed``, ``virtual_root``, and ``virtual_root_path``.
@@ -210,9 +214,9 @@ def traverse(model, path):
       to find the ``virtual_root`` object (e.g. if virtual hosting is
       not in effect), the ``traversed`` value will be the empty list.
       If url dispatch was used to find the ``model``, this will be
-      None.
+      ``None``.
 
-    If the path cannot be resolved, a ``KeyError`` will be raised.
+    If the path cannot be resolved, a :exc:`KeyError` will be raised.
 
     Rules for passing a *string* as the ``path`` argument: if the
     first character in the path string is the with the ``/``
@@ -224,11 +228,11 @@ def traverse(model, path):
     empty string is passed as ``path``, the ``model`` passed in will
     be returned.  Model path strings must be escaped in the following
     manner: each Unicode path segment must be encoded as UTF-8 and as
-    each path segment must escaped via Python's ``urllib.quote``.  For
-    example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
-    ``to%20the/La%20Pe%C3%B1a`` (relative).  The ``model_path``
-    function generates strings which follow these rules (albeit only
-    absolute ones).
+    each path segment must escaped via Python's :mod:`urllib.quote`.
+    For example, ``/path/to%20the/La%20Pe%C3%B1a`` (absolute) or
+    ``to%20the/La%20Pe%C3%B1a`` (relative).  The
+    :func:`repoze.bfg.traversal.model_path` function generates strings
+    which follow these rules (albeit only absolute ones).
 
     Rules for passing a *tuple* as the ``path`` argument: if the first
     element in the path tuple is the empty string (for example ``('',
@@ -241,17 +245,16 @@ def traverse(model, path):
     ``path``, the ``model`` passed in itself will be returned.  No
     URL-quoting or UTF-8-encoding of individual path segments within
     the tuple is required (each segment may be any string or unicode
-    object representing a model name).  Model path tuples generated by
-    ``model_path_tuple`` can always be resolved by ``find_model``.
+    object representing a model name).
 
     Explanation of the conversion of ``path`` segment values to
     Unicode during traversal: Each segment is URL-unquoted, and
     decoded into Unicode. Each segment is assumed to be encoded using
-    the UTF-8 encoding (or a subset, such as ASCII); a ``TypeError``
-    is raised if a segment cannot be decoded.  If a segment name is
-    empty or if it is ``.``, it is ignored.  If a segment name is
-    ``..``, the previous segment is deleted, and the ``..`` is
-    ignored.  As a result of this process, the return values
+    the UTF-8 encoding (or a subset, such as ASCII); a
+    :exc:`TypeError` is raised if a segment cannot be decoded.  If a
+    segment name is empty or if it is ``.``, it is ignored.  If a
+    segment name is ``..``, the previous segment is deleted, and the
+    ``..`` is ignored.  As a result of this process, the return values
     ``view_name``, each element in the ``subpath``, each element in
     ``traversed``, and each element in the ``virtual_root_path`` will
     be Unicode as opposed to a string, and will be URL-decoded.
@@ -292,9 +295,9 @@ def model_path_tuple(model, *elements):
     leading empty string element in a path tuple represents that the
     path is absolute).
 
-    This function is a logical inverse of ``find_model``: it can be
-    used to generate path references that can later be resolved via
-    ``find_model``.
+    This function is a logical inverse of
+    :func:`repoze.bfg.traversal.find_model`: it can be used to
+    generate path references that can later be resolved that function.
 
     The ``model`` passed in *must* be :term:`location`-aware.
 
@@ -364,13 +367,14 @@ def virtual_root(model, request):
 def traversal_path(path):
     """ Given a ``PATH_INFO`` string (slash-separated path segments),
     return a tuple representing that path which can be used to
-    traverse a graph.  The PATH_INFO is split on slashes, creating a
-    list of segments.  Each segment is URL-unquoted, and decoded into
-    Unicode. Each segment is assumed to be encoded using the UTF-8
-    encoding (or a subset, such as ASCII); a TypeError is raised if a
-    segment cannot be decoded.  If a segment name is empty or if it is
-    ``.``, it is ignored.  If a segment name is ``..``, the previous
-    segment is deleted, and the ``..`` is ignored.  Examples:
+    traverse a graph.  The ``PATH_INFO`` is split on slashes, creating
+    a list of segments.  Each segment is URL-unquoted, and decoded
+    into Unicode. Each segment is assumed to be encoded using the
+    UTF-8 encoding (or a subset, such as ASCII); a :exc:`TypeError` is
+    raised if a segment cannot be decoded.  If a segment name is empty
+    or if it is ``.``, it is ignored.  If a segment name is ``..``,
+    the previous segment is deleted, and the ``..`` is ignored.
+    Examples:
 
     ``/``
 
@@ -405,15 +409,17 @@ def traversal_path(path):
         (u'archives', u'<unprintable unicode>')
 
     .. note:: This function does not generate the same type of tuples
-              that ``model_path_tuple`` does.  In particular, the
-              leading empty string is not present in the tuple it
-              returns, unlike tuples returned by ``model_path_tuple``.
-              As a result, tuples generated by ``traversal_path`` are
-              not resolveable by the ``find_model`` API.
+              that :func:`repoze.bfg.traversal.model_path_tuple` does.
+              In particular, the leading empty string is not present
+              in the tuple it returns, unlike tuples returned by
+              :func:`repoze.bfg.traversal.model_path_tuple`.  As a
+              result, tuples generated by ``traversal_path`` are not
+              resolveable by the
+              :func:`repoze.bfg.traversal.find_model` API.
               ``traversal_path`` is a function mostly used by the
               internals of :mod:`repoze.bfg` and by people writing
               their own traversal machinery, as opposed to users
-              writing applications in BFG.
+              writing applications in :mod:`repoze.bfg`.
     """
     path = path.rstrip('/')
     path = path.lstrip('/')
@@ -441,10 +447,10 @@ def quote_path_segment(segment):
     ``segment`` passed in is a unicode object, it is converted to a
     UTF-8 string, then it is URL-quoted using Python's
     ``urllib.quote``.  If the ``segment`` passed in is a string, it is
-    URL-quoted using Python's ``urllib.quote``.  If the segment passed
-    in is not a string or unicode object, an error will be raised.
-    The return value of ``quote_path_segment`` is always a string,
-    never Unicode.
+    URL-quoted using Python's :mod:`urllib.quote`.  If the segment
+    passed in is not a string or unicode object, an error will be
+    raised.  The return value of ``quote_path_segment`` is always a
+    string, never Unicode.
 
     .. note:: The return value for each segment passed to this
               function is cached in a module-scope dictionary for
@@ -476,7 +482,8 @@ def quote_path_segment(segment):
 class ModelGraphTraverser(object):
     """ A model graph traverser that should be used (for speed) when
     every object in the graph supplies a ``__name__`` and
-    ``__parent__`` attribute (ie. every object 'provides ILocation') ."""
+    ``__parent__`` attribute (ie. every object in the graph is
+    :term:`location` aware) ."""
 
     implements(ITraverser)