SVN: r21292 - in trunk/quixote: . demo doc

Author: akuchlin
Date: 2003-04-08 12:48:47 -0400 (Tue, 08 Apr 2003)
New Revision: 21292

Modified:
   trunk/quixote/CHANGES
   trunk/quixote/demo/__init__.py
   trunk/quixote/demo/pages.ptl
   trunk/quixote/doc/demo.txt
   trunk/quixote/doc/programming.txt
   trunk/quixote/publish.py
   trunk/quixote/util.py
Log:
Rename _q_getname to _q_lookup

Much of this patch is straightforward search-and-replace; the actual
change is in publish.py, and is right at the bottom of the patch.


Modified: trunk/quixote/demo/__init__.py
==============================================================================
--- trunk/quixote/demo/__init__.py	(original)
+++ trunk/quixote/demo/__init__.py	2003-04-08 12:48:49.000000000 -0400
@@ -20,7 +20,7 @@
 def publish_error (request):
     raise PublishError(public_msg="Publishing error raised by publish_error")
 
-def _q_getname(request, component):
+def _q_lookup (request, component):
     return IntegerUI(request, component)
 
 def _q_resolve (component):

Modified: trunk/quixote/demo/pages.ptl
==============================================================================
--- trunk/quixote/demo/pages.ptl	(original)
+++ trunk/quixote/demo/pages.ptl	2003-04-08 12:48:49.000000000 -0400
@@ -40,7 +40,7 @@
             a <code>PublishError</code> exception.  This exception
             will be caught by a <code>_q_exception_handler</code> method.
         <li><a href="12/">12/</a>:
-            A Python object published through <code>_q_getname()</code>.
+            A Python object published through <code>_q_lookup()</code>.
         <li><a href="12/factorial">12/factorial</a>:
             A method on a published Python object.
         <li><a href="dumpreq">dumpreq</a>:

Modified: trunk/quixote/util.py
==============================================================================
--- trunk/quixote/util.py	(original)
+++ trunk/quixote/util.py	2003-04-08 12:48:49.000000000 -0400
@@ -158,7 +158,7 @@
                 "<p>This directory does not allow its contents to be listed.</p>"
         return out.getvalue()
 
-    def _q_getname(self, request, name):
+    def _q_lookup(self, request, name):
         """
         Get a file from the filesystem directory and return the StaticFile
         or StaticDirectory wrapper of it; use caching if that is in use.

Modified: trunk/quixote/doc/programming.txt
==============================================================================
--- trunk/quixote/doc/programming.txt	(original)
+++ trunk/quixote/doc/programming.txt	2003-04-08 12:48:49.000000000 -0400
@@ -299,7 +299,7 @@
 
 There are a few special functions that affect Quixote's 
 traversal of a URL to determine how to handle it: ``_q_access()``,
-``_q_getname()``, and  ``_q_resolve()``.
+``_q_lookup()``, and  ``_q_resolve()``.
 
 
 ``_q_access(request)``
@@ -327,7 +327,7 @@
 every single public function.
 
 
-``_q_getname(request, name)``
+``_q_lookup(request, name)``
 -----------------------------
 
 This function translates an arbitrary string into an object that we
@@ -336,19 +336,19 @@
 strings out of a query, or checking ``PATH_INFO`` after Quixote's done
 with it.  But it is a compromise with security: it opens up the
 traversal algorithm to arbitrary names not listed in ``_q_exports``.
-(``_q_getname()`` is never called for names listed in ``_q_exports``.)
+(``_q_lookup()`` is never called for names listed in ``_q_exports``.)
 You should therefore be extremely paranoid about checking the value of
 ``name``.
 
 ``request`` is the request object, as it is everywhere else; ``name`` is
-a string containing the next component of the path.  ``_q_getname()`` should
+a string containing the next component of the path.  ``_q_lookup()`` should
 return either a string (a complete document that will be returned to the
 client) or some object that can be traversed further.  Returning a
 string is useful in simple cases, eg. if you want the ``/user/joe`` URI
 to show everything about user "joe" in your database, you would define a
-``_q_getname()`` in the namespace that handles ``/user/`` requests::
+``_q_lookup()`` in the namespace that handles ``/user/`` requests::
 
-    def _q_getname [plain] (request, name):
+    def _q_lookup [plain] (request, name):
         if not request.session.user.is_admin():
             raise AccessError("permission denied")
         user = get_database().get_user(name)
@@ -363,21 +363,21 @@
 (This assumes that the namespace in question is a PTL module, not a
 Python module.)
 
-To publish more complex objects, you'll want to use ``_q_getname()``'s
+To publish more complex objects, you'll want to use ``_q_lookup()``'s
 ability to return a new namespace that Quixote continues traversing.
 The usual way to do this is to return an instance of a class that
 implements the web front-end to your object.  That class must have a
 ``_q_exports`` attribute, and it will almost certainly have a
 ``_q_index()`` method.  It might also have ``_q_access()`` and
-``_q_getname()`` (yes, ``_q_getname()`` calls can nest arbitrarily
+``_q_lookup()`` (yes, ``_q_lookup()`` calls can nest arbitrarily
 deeply).
 
 For example, you might want ``/user/joe/`` to show a summary,
 ``/user/joe/history`` to show a login history, ``/user/joe/prefs`` to be
 a page where joe can edit his personal preferences, etc.  The
-``_q_getname()`` function would then be ::
+``_q_lookup()`` function would then be ::
 
-     def _q_getname (request, name):
+     def _q_lookup (request, name):
          return UserUI(request, name)
 
 and the UserUI class, which implements the web interface to user
@@ -405,7 +405,7 @@
 ``_q_resolve(name)``
 --------------------
 
-``_q_resolve()`` looks a bit like ``_q_getname()``, but is intended for
+``_q_resolve()`` looks a bit like ``_q_lookup()``, but is intended for
 a different purpose.  Quixote applications can be slow to start up 
 because they have to import a large number of Python and PTL modules.
 ``_q_resolve()`` is a hook that lets time-consuming imports 

Modified: trunk/quixote/doc/demo.txt
==============================================================================
--- trunk/quixote/doc/demo.txt	(original)
+++ trunk/quixote/doc/demo.txt	2003-04-08 12:48:49.000000000 -0400
@@ -317,7 +317,7 @@
 Quixote demo.  (The empty string is implicitly exported from a namespace
 if a ``_q_index()`` callable exists there -- thus "/qdemo/" is handled
 by ``_q_index()`` in the "quixote.demo" namespace.  Arbitrary names may
-be implicitly exported using a ``_q_getname()`` function; see Lesson 4
+be implicitly exported using a ``_q_lookup()`` function; see Lesson 4
 below.)
 
 
@@ -408,15 +408,15 @@
 published on the web, and you can create URLs that call methods on those
 objects.
 
-This is all accomplished with the ``_q_getname()`` function.  Every
-namespace that Quixote encounters may have a ``_q_getname()``, just like
+This is all accomplished with the ``_q_lookup()`` function.  Every
+namespace that Quixote encounters may have a ``_q_lookup()``, just like
 it may have a ``_q_index()``.  ``_q_index()`` is used to handle requests for
 the empty name -- as we saw in Lesson 1, a request for "/qdemo/", maps to
 the "quixote.demo" namespace; the empty string after the last slash
 means that Quixote will call ``_q_index()`` in this namespace to handle
 the request.
 
-``_q_getname()`` is for requests that aren't handled by a Python callable
+``_q_lookup()`` is for requests that aren't handled by a Python callable
 in the namespace.  As seen in Lessons 2 and 3, requests for
 "/qdemo/simple" and "/qdemo/error" are handled by the ``simple()`` and
 ``error()`` functions in the "quixote.demo" namespace.  What if someone
@@ -427,14 +427,14 @@
 names.  Another part of Quixote then turns this into an HTTP 404
 response.)
 
-However, this particular namespace also defines a ``_q_getname()``
+However, this particular namespace also defines a ``_q_lookup()``
 function.  That means that the application wants a chance to handle
 unknown names before Quixote gives up entirely.  Let's take a look at
-the implementation of ``_q_getname()``::
+the implementation of ``_q_lookup()``::
 
     from quixote.demo.integer_ui import IntegerUI
     [...]
-    def _q_getname(request, component):
+    def _q_lookup(request, component):
         return IntegerUI(request, component)
 
 Pretty simple: we just construct an IntegerUI object and return it.  So

Modified: trunk/quixote/CHANGES
==============================================================================
--- trunk/quixote/CHANGES	(original)
+++ trunk/quixote/CHANGES	2003-04-08 12:48:49.000000000 -0400
@@ -1,5 +1,9 @@
 0.6?? (?? Mar 2003):
 
+  * Rename _q_getname() to _q_lookup().  The name '_q_getname' is still
+    supported, but will log a warning whenever it's encountered.
+    This change will require users to modify their applications.
+
   * Fix generation of temporary filenames in upload.py: filename
     collisions should be impossible now.
 
@@ -240,7 +244,7 @@
     found by the publisher to handle the terminal component of a URL can
     now be strings as well as callables; a string simply substitutes for
     a callable's return value.  The immediate reason for this was to
-    allow _q_getname() functions to return a string, but a consequence
+    allow _q_lookup() functions to return a string, but a consequence
     is that you can now put static text in global variables and simply
     publish them.
 

Modified: trunk/quixote/publish.py
==============================================================================
--- trunk/quixote/publish.py	(original)
+++ trunk/quixote/publish.py	2003-04-08 12:48:49.000000000 -0400
@@ -8,7 +8,7 @@
 __revision__ = "$Id$"
 
 import sys, os, traceback, cStringIO
-import time, types, socket, re
+import time, types, socket, re, warnings
 import cgi
 import struct
 try:
@@ -724,21 +724,25 @@
 
     # Third security check: make sure the current name component
     # is in the export list or is '_q_index'.  If neither
-    # condition is true, check for a _q_getname() and call it.
-    # '_q_getname()' translates an arbitrary string into an object
+    # condition is true, check for a _q_lookup() and call it.
+    # '_q_lookup()' translates an arbitrary string into an object
     # that we continue traversing.  (This is very handy; it lets
     # you put user-space objects into your URL-space, eliminating
     # the need for digging ID strings out of a query, or checking
     # PATHINFO after Quixote's done with it.  But it is a
     # compromise to security: it opens up the traversal algorithm
     # to arbitrary names not listed in _q_exports!)  If
-    # _q_getname() doesn't exist or is None, a TraversalError is
+    # _q_lookup() doesn't exist or is None, a TraversalError is
     # raised.
 
     if (component != "_q_index" and component not in container._q_exports):
         # Component is not in exports list.
         object = None
-        if hasattr(container, "_q_getname"):
+        if hasattr(container, "_q_lookup"):
+            object = container._q_lookup(request, component)
+        elif hasattr(container, "_q_getname"):
+            warnings.warn("_q_getname() on %s used; should "
+                          "be replaced by _q_lookup()" % type(container))
             object = container._q_getname(request, component)
         if object is None:
             raise errors.TraversalError(