From c6895b23b63365a983cf564fc67446913ef2bebd Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 24 Dec 2009 01:26:37 +0000 Subject: Roles. --- repoze/bfg/traversal.py | 125 +++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 59 deletions(-) (limited to 'repoze/bfg/traversal.py') 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'') .. 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) -- cgit v1.2.3