On Tue, Jan 21, 2003 at 02:03:18PM -0600, Martin Maney wrote:
>On Tue, Jan 21, 2003 at 01:39:46PM -0500, Andrew Kuchling wrote:
>> Interface question: _q_resolve is called iff the name is listed in
>> _q_exports.
>
>Isn't that iff listed and not already present in the namespace?  I'm

You're correct.

Here's the section of documentation I've just written for
_q_resolve().  Everyone, please suggest clarifications.  (Apologies
for the RST markup.)

--amk

``_q_resolve(name)``
-------------------

``_q_resolve()`` looks a bit like ``_q_getname()``, 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
be postponed until the code is actually needed

``name`` is a string containing the next chunk of the path.
``_q_resolve()`` should do whatever imports are necessary and return a
module that will be traversed further.  (Other things can be returned,
such as class instances or whatever, but modules are likely to be the
most common return type.)

``_q_resolve()`` is only ever called for names that are in
``_q_exports`` and that don't already exist in the module or instance.
It is not passed the request object, so its return value can't depend
on the client in any way.  Calls are also memoized; after being called
the object returned will be added as an attribute of the containing
module or instance, so ``_q_resolve()`` will be called at most once
for a given name.

Most commonly, ``_q_resolve()`` will look something like this:

    _q_exports = [..., 'expensive', ...]

    def _q_resolve(name):
        if name == 'expensive':
            from otherpackage import expensive
            return expensive

Let's say this function is in app.ui.  The first time /expensive is
accessed, _q_resolve('expensive') is called, the
otherpackage.expensive module is returned and traversal continues.
app.ui.expensive is also set to the module objects, so future
references to /expensive won't need to invoke the ``_q_resolve()``
hook.