← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/imputil.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/imputil.rst
 
1
 
 
2
:mod:`imputil` --- Import utilities
 
3
=====================================================
 
4
 
 
5
.. module:: imputil
 
6
   :synopsis: Manage and augment the import process.
 
7
   :deprecated:
 
8
 
 
9
.. deprecated:: 2.6
 
10
   The :mod:`imputil` module has been removed in Python 3.0.
 
11
 
 
12
 
 
13
.. index:: statement: import
 
14
 
 
15
This module provides a very handy and useful mechanism for custom
 
16
:keyword:`import` hooks. Compared to the older :mod:`ihooks` module,
 
17
:mod:`imputil` takes a dramatically simpler and more straight-forward
 
18
approach to custom :keyword:`import` functions.
 
19
 
 
20
 
 
21
.. class:: ImportManager([fs_imp])
 
22
 
 
23
   Manage the import process.
 
24
 
 
25
   .. method:: ImportManager.install([namespace])
 
26
 
 
27
      Install this ImportManager into the specified namespace.
 
28
 
 
29
   .. method:: ImportManager.uninstall()
 
30
 
 
31
      Restore the previous import mechanism.
 
32
 
 
33
   .. method:: ImportManager.add_suffix(suffix, importFunc)
 
34
 
 
35
      Undocumented.
 
36
 
 
37
 
 
38
.. class:: Importer()
 
39
 
 
40
   Base class for replacing standard import functions.
 
41
 
 
42
   .. method:: Importer.import_top(name)
 
43
 
 
44
      Import a top-level module.
 
45
 
 
46
   .. method:: Importer.get_code(parent, modname, fqname)
 
47
 
 
48
      Find and retrieve the code for the given module.
 
49
 
 
50
      *parent* specifies a parent module to define a context for importing.
 
51
      It may be ``None``, indicating no particular context for the search.
 
52
 
 
53
      *modname* specifies a single module (not dotted) within the parent.
 
54
 
 
55
      *fqname* specifies the fully-qualified module name. This is a
 
56
      (potentially) dotted name from the "root" of the module namespace
 
57
      down to the modname.
 
58
 
 
59
      If there is no parent, then modname==fqname.
 
60
 
 
61
      This method should return ``None``, or a 3-tuple.
 
62
 
 
63
        * If the module was not found, then ``None`` should be returned.
 
64
 
 
65
        * The first item of the 2- or 3-tuple should be the integer 0 or 1,
 
66
          specifying whether the module that was found is a package or not.
 
67
 
 
68
        * The second item is the code object for the module (it will be
 
69
          executed within the new module's namespace). This item can also
 
70
          be a fully-loaded module object (e.g. loaded from a shared lib).
 
71
 
 
72
        * The third item is a dictionary of name/value pairs that will be
 
73
          inserted into new module before the code object is executed. This
 
74
          is provided in case the module's code expects certain values (such
 
75
          as where the module was found). When the second item is a module
 
76
          object, then these names/values will be inserted *after* the module
 
77
          has been loaded/initialized.
 
78
 
 
79
 
 
80
.. class:: BuiltinImporter()
 
81
 
 
82
   Emulate the import mechanism for builtin and frozen modules.  This is a
 
83
   sub-class of the :class:`Importer` class.
 
84
 
 
85
   .. method:: BuiltinImporter.get_code(parent, modname, fqname)
 
86
 
 
87
      Undocumented.
 
88
 
 
89
.. function:: py_suffix_importer(filename, finfo, fqname)
 
90
 
 
91
   Undocumented.
 
92
 
 
93
.. class:: DynLoadSuffixImporter([desc])
 
94
 
 
95
   Undocumented.
 
96
 
 
97
   .. method:: DynLoadSuffixImporter.import_file(filename, finfo, fqname)
 
98
 
 
99
      Undocumented.
 
100
 
 
101
.. _examples-imputil:
 
102
 
 
103
Examples
 
104
--------
 
105
 
 
106
This is a re-implementation of hierarchical module import.
 
107
 
 
108
This code is intended to be read, not executed.  However, it does work
 
109
-- all you need to do to enable it is "import knee".
 
110
 
 
111
(The name is a pun on the clunkier predecessor of this module, "ni".)
 
112
 
 
113
::
 
114
 
 
115
   import sys, imp, __builtin__
 
116
 
 
117
   # Replacement for __import__()
 
118
   def import_hook(name, globals=None, locals=None, fromlist=None):
 
119
       parent = determine_parent(globals)
 
120
       q, tail = find_head_package(parent, name)
 
121
       m = load_tail(q, tail)
 
122
       if not fromlist:
 
123
           return q
 
124
       if hasattr(m, "__path__"):
 
125
           ensure_fromlist(m, fromlist)
 
126
       return m
 
127
 
 
128
   def determine_parent(globals):
 
129
       if not globals or  not globals.has_key("__name__"):
 
130
           return None
 
131
       pname = globals['__name__']
 
132
       if globals.has_key("__path__"):
 
133
           parent = sys.modules[pname]
 
134
           assert globals is parent.__dict__
 
135
           return parent
 
136
       if '.' in pname:
 
137
           i = pname.rfind('.')
 
138
           pname = pname[:i]
 
139
           parent = sys.modules[pname]
 
140
           assert parent.__name__ == pname
 
141
           return parent
 
142
       return None
 
143
 
 
144
   def find_head_package(parent, name):
 
145
       if '.' in name:
 
146
           i = name.find('.')
 
147
           head = name[:i]
 
148
           tail = name[i+1:]
 
149
       else:
 
150
           head = name
 
151
           tail = ""
 
152
       if parent:
 
153
           qname = "%s.%s" % (parent.__name__, head)
 
154
       else:
 
155
           qname = head
 
156
       q = import_module(head, qname, parent)
 
157
       if q: return q, tail
 
158
       if parent:
 
159
           qname = head
 
160
           parent = None
 
161
           q = import_module(head, qname, parent)
 
162
           if q: return q, tail
 
163
       raise ImportError, "No module named " + qname
 
164
 
 
165
   def load_tail(q, tail):
 
166
       m = q
 
167
       while tail:
 
168
           i = tail.find('.')
 
169
           if i < 0: i = len(tail)
 
170
           head, tail = tail[:i], tail[i+1:]
 
171
           mname = "%s.%s" % (m.__name__, head)
 
172
           m = import_module(head, mname, m)
 
173
           if not m:
 
174
               raise ImportError, "No module named " + mname
 
175
       return m
 
176
 
 
177
   def ensure_fromlist(m, fromlist, recursive=0):
 
178
       for sub in fromlist:
 
179
           if sub == "*":
 
180
               if not recursive:
 
181
                   try:
 
182
                       all = m.__all__
 
183
                   except AttributeError:
 
184
                       pass
 
185
                   else:
 
186
                       ensure_fromlist(m, all, 1)
 
187
               continue
 
188
           if sub != "*" and not hasattr(m, sub):
 
189
               subname = "%s.%s" % (m.__name__, sub)
 
190
               submod = import_module(sub, subname, m)
 
191
               if not submod:
 
192
                   raise ImportError, "No module named " + subname
 
193
 
 
194
   def import_module(partname, fqname, parent):
 
195
       try:
 
196
           return sys.modules[fqname]
 
197
       except KeyError:
 
198
           pass
 
199
       try:
 
200
           fp, pathname, stuff = imp.find_module(partname,
 
201
                                                 parent and parent.__path__)
 
202
       except ImportError:
 
203
           return None
 
204
       try:
 
205
           m = imp.load_module(fqname, fp, pathname, stuff)
 
206
       finally:
 
207
           if fp: fp.close()
 
208
       if parent:
 
209
           setattr(parent, partname, m)
 
210
       return m
 
211
 
 
212
 
 
213
   # Replacement for reload()
 
214
   def reload_hook(module):
 
215
       name = module.__name__
 
216
       if '.' not in name:
 
217
           return import_module(name, name, None)
 
218
       i = name.rfind('.')
 
219
       pname = name[:i]
 
220
       parent = sys.modules[pname]
 
221
       return import_module(name[i+1:], name, parent)
 
222
 
 
223
 
 
224
   # Save the original hooks
 
225
   original_import = __builtin__.__import__
 
226
   original_reload = __builtin__.reload
 
227
 
 
228
   # Now install our hooks
 
229
   __builtin__.__import__ = import_hook
 
230
   __builtin__.reload = reload_hook
 
231
 
 
232
.. index::
 
233
   module: knee
 
234
 
 
235
Also see the :mod:`importers` module (which can be found
 
236
in :file:`Demo/imputil/` in the Python source distribution) for additional
 
237
examples.
 
238