1
# Copyright (C) 2006-2010 Canonical Ltd
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""Functionality to create lazy evaluation objects.
19
This includes waiting to import a module until it is actually used.
21
Most commonly, the 'lazy_import' function is used to import other modules
22
in an on-demand fashion. Typically use looks like::
24
from .lazy_import import lazy_import
25
lazy_import(globals(), '''
34
Then 'errors, osutils, branch' and 'breezy' will exist as lazy-loaded
35
objects which will be replaced with a real object on first use.
37
In general, it is best to only load modules in this way. This is because
38
it isn't safe to pass these variables to other functions before they
39
have been replaced. This is especially true for constants, sometimes
40
true for classes or functions (when used as a factory, or you want
41
to inherit from them).
44
from __future__ import absolute_import
47
class ScopeReplacer(object):
48
"""A lazy object that will replace itself in the appropriate scope.
50
This object sits, ready to create the real object the first time it is
54
__slots__ = ('_scope', '_factory', '_name', '_real_obj')
56
# If you to do x = y, setting this to False will disallow access to
57
# members from the second variable (i.e. x). This should normally
58
# be enabled for reasons of thread safety and documentation, but
59
# will be disabled during the selftest command to check for abuse.
62
def __init__(self, scope, factory, name):
63
"""Create a temporary object in the specified scope.
64
Once used, a real object will be placed in the scope.
66
:param scope: The scope the object should appear in
67
:param factory: A callable that will create the real object.
68
It will be passed (self, scope, name)
69
:param name: The variable name in the given scope.
71
object.__setattr__(self, '_scope', scope)
72
object.__setattr__(self, '_factory', factory)
73
object.__setattr__(self, '_name', name)
74
object.__setattr__(self, '_real_obj', None)
78
"""Return the real object for which this is a placeholder"""
79
name = object.__getattribute__(self, '_name')
80
real_obj = object.__getattribute__(self, '_real_obj')
82
# No obj generated previously, so generate from factory and scope.
83
factory = object.__getattribute__(self, '_factory')
84
scope = object.__getattribute__(self, '_scope')
85
obj = factory(self, scope, name)
87
raise errors.IllegalUseOfScopeReplacer(name, msg="Object tried"
88
" to replace itself, check it's not using its own scope.")
90
# Check if another thread has jumped in while obj was generated.
91
real_obj = object.__getattribute__(self, '_real_obj')
93
# Still no prexisting obj, so go ahead and assign to scope and
94
# return. There is still a small window here where races will
95
# not be detected, but safest to avoid additional locking.
96
object.__setattr__(self, '_real_obj', obj)
100
# Raise if proxying is disabled as obj has already been generated.
101
if not ScopeReplacer._should_proxy:
102
raise errors.IllegalUseOfScopeReplacer(
103
name, msg="Object already replaced, did you assign it"
104
" to another variable?")
107
def __getattribute__(self, attr):
108
obj = object.__getattribute__(self, '_resolve')()
109
return getattr(obj, attr)
111
def __setattr__(self, attr, value):
112
obj = object.__getattribute__(self, '_resolve')()
113
return setattr(obj, attr, value)
115
def __call__(self, *args, **kwargs):
116
obj = object.__getattribute__(self, '_resolve')()
117
return obj(*args, **kwargs)
120
def disallow_proxying():
121
"""Disallow lazily imported modules to be used as proxies.
123
Calling this function might cause problems with concurrent imports
124
in multithreaded environments, but will help detecting wasteful
125
indirection, so it should be called when executing unit tests.
127
Only lazy imports that happen after this call are affected.
129
ScopeReplacer._should_proxy = False
132
class ImportReplacer(ScopeReplacer):
133
"""This is designed to replace only a portion of an import list.
135
It will replace itself with a module, and then make children
136
entries also ImportReplacer objects.
138
At present, this only supports 'import foo.bar.baz' syntax.
141
# '_import_replacer_children' is intentionally a long semi-unique name
142
# that won't likely exist elsewhere. This allows us to detect an
143
# ImportReplacer object by using
144
# object.__getattribute__(obj, '_import_replacer_children')
145
# We can't just use 'isinstance(obj, ImportReplacer)', because that
146
# accesses .__class__, which goes through __getattribute__, and triggers
148
__slots__ = ('_import_replacer_children', '_member', '_module_path')
150
def __init__(self, scope, name, module_path, member=None, children={}):
151
"""Upon request import 'module_path' as the name 'module_name'.
152
When imported, prepare children to also be imported.
154
:param scope: The scope that objects should be imported into.
155
Typically this is globals()
156
:param name: The variable name. Often this is the same as the
157
module_path. 'breezy'
158
:param module_path: A list for the fully specified module path
159
['breezy', 'foo', 'bar']
160
:param member: The member inside the module to import, often this is
161
None, indicating the module is being imported.
162
:param children: Children entries to be imported later.
163
This should be a map of children specifications.
166
{'foo':(['breezy', 'foo'], None,
167
{'bar':(['breezy', 'foo', 'bar'], None {})})
172
import foo => name='foo' module_path='foo',
173
member=None, children={}
174
import foo.bar => name='foo' module_path='foo', member=None,
175
children={'bar':(['foo', 'bar'], None, {}}
176
from foo import bar => name='bar' module_path='foo', member='bar'
178
from foo import bar, baz would get translated into 2 import
179
requests. On for 'name=bar' and one for 'name=baz'
181
if (member is not None) and children:
182
raise ValueError('Cannot supply both a member and children')
184
object.__setattr__(self, '_import_replacer_children', children)
185
object.__setattr__(self, '_member', member)
186
object.__setattr__(self, '_module_path', module_path)
188
# Indirecting through __class__ so that children can
189
# override _import (especially our instrumented version)
190
cls = object.__getattribute__(self, '__class__')
191
ScopeReplacer.__init__(self, scope=scope, name=name,
194
def _import(self, scope, name):
195
children = object.__getattribute__(self, '_import_replacer_children')
196
member = object.__getattribute__(self, '_member')
197
module_path = object.__getattribute__(self, '_module_path')
198
module_python_path = '.'.join(module_path)
199
if member is not None:
200
module = __import__(module_python_path, scope, scope, [member], level=0)
201
return getattr(module, member)
203
module = __import__(module_python_path, scope, scope, [], level=0)
204
for path in module_path[1:]:
205
module = getattr(module, path)
207
# Prepare the children to be imported
208
for child_name, (child_path, child_member, grandchildren) in \
210
# Using self.__class__, so that children get children classes
211
# instantiated. (This helps with instrumented tests)
212
cls = object.__getattribute__(self, '__class__')
213
cls(module.__dict__, name=child_name,
214
module_path=child_path, member=child_member,
215
children=grandchildren)
219
class ImportProcessor(object):
220
"""Convert text that users input into lazy import requests"""
222
# TODO: jam 20060912 This class is probably not strict enough about
223
# what type of text it allows. For example, you can do:
224
# import (foo, bar), which is not allowed by python.
225
# For now, it should be supporting a superset of python import
226
# syntax which is all we really care about.
228
__slots__ = ['imports', '_lazy_import_class']
230
def __init__(self, lazy_import_class=None):
232
if lazy_import_class is None:
233
self._lazy_import_class = ImportReplacer
235
self._lazy_import_class = lazy_import_class
237
def lazy_import(self, scope, text):
238
"""Convert the given text into a bunch of lazy import objects.
240
This takes a text string, which should be similar to normal python
243
self._build_map(text)
244
self._convert_imports(scope)
246
def _convert_imports(self, scope):
247
# Now convert the map into a set of imports
248
for name, info in self.imports.items():
249
self._lazy_import_class(scope, name=name, module_path=info[0],
250
member=info[1], children=info[2])
252
def _build_map(self, text):
253
"""Take a string describing imports, and build up the internal map"""
254
for line in self._canonicalize_import_text(text):
255
if line.startswith('import '):
256
self._convert_import_str(line)
257
elif line.startswith('from '):
258
self._convert_from_str(line)
260
raise errors.InvalidImportLine(line,
261
"doesn't start with 'import ' or 'from '")
263
def _convert_import_str(self, import_str):
264
"""This converts a import string into an import map.
266
This only understands 'import foo, foo.bar, foo.bar.baz as bing'
268
:param import_str: The import string to process
270
if not import_str.startswith('import '):
271
raise ValueError('bad import string %r' % (import_str,))
272
import_str = import_str[len('import '):]
274
for path in import_str.split(','):
278
as_hunks = path.split(' as ')
279
if len(as_hunks) == 2:
280
# We have 'as' so this is a different style of import
281
# 'import foo.bar.baz as bing' creates a local variable
282
# named 'bing' which points to 'foo.bar.baz'
283
name = as_hunks[1].strip()
284
module_path = as_hunks[0].strip().split('.')
285
if name in self.imports:
286
raise errors.ImportNameCollision(name)
287
if not module_path[0]:
288
raise ImportError(path)
289
# No children available in 'import foo as bar'
290
self.imports[name] = (module_path, None, {})
292
# Now we need to handle
293
module_path = path.split('.')
294
name = module_path[0]
296
raise ImportError(path)
297
if name not in self.imports:
298
# This is a new import that we haven't seen before
299
module_def = ([name], None, {})
300
self.imports[name] = module_def
302
module_def = self.imports[name]
306
for child in module_path[1:]:
307
cur_path.append(child)
311
next = (cur_path[:], None, {})
315
def _convert_from_str(self, from_str):
316
"""This converts a 'from foo import bar' string into an import map.
318
:param from_str: The import string to process
320
if not from_str.startswith('from '):
321
raise ValueError('bad from/import %r' % from_str)
322
from_str = from_str[len('from '):]
324
from_module, import_list = from_str.split(' import ')
326
from_module_path = from_module.split('.')
328
if not from_module_path[0]:
329
raise ImportError(from_module)
331
for path in import_list.split(','):
335
as_hunks = path.split(' as ')
336
if len(as_hunks) == 2:
337
# We have 'as' so this is a different style of import
338
# 'import foo.bar.baz as bing' creates a local variable
339
# named 'bing' which points to 'foo.bar.baz'
340
name = as_hunks[1].strip()
341
module = as_hunks[0].strip()
344
if name in self.imports:
345
raise errors.ImportNameCollision(name)
346
self.imports[name] = (from_module_path, module, {})
348
def _canonicalize_import_text(self, text):
349
"""Take a list of imports, and split it into regularized form.
351
This is meant to take regular import text, and convert it to
352
the forms that the rest of the converters prefer.
358
for line in text.split('\n'):
362
line = line[:loc].strip()
367
if line.endswith(')'):
368
out.append(cur + ' ' + line[:-1])
373
if '(' in line and ')' not in line:
374
cur = line.replace('(', '')
376
out.append(line.replace('(', '').replace(')', ''))
378
raise errors.InvalidImportLine(cur, 'Unmatched parenthesis')
382
def lazy_import(scope, text, lazy_import_class=None):
383
"""Create lazy imports for all of the imports in text.
385
This is typically used as something like::
387
from breezy.lazy_import import lazy_import
388
lazy_import(globals(), '''
395
import breezy.transport
398
Then 'foo, bar, baz' and 'breezy' will exist as lazy-loaded
399
objects which will be replaced with a real object on first use.
401
In general, it is best to only load modules in this way. This is
402
because other objects (functions/classes/variables) are frequently
403
used without accessing a member, which means we cannot tell they
406
# This is just a helper around ImportProcessor.lazy_import
407
proc = ImportProcessor(lazy_import_class=lazy_import_class)
408
return proc.lazy_import(scope, text)
411
# The only module that this module depends on is 'breezy.errors'. But it
412
# can actually be imported lazily, since we only need it if there is a
415
lazy_import(globals(), """
416
from breezy import errors
added
removed
breezy/lazy_import.py
