/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/lazy_import.py

  • Committer: Marius Kruger
  • Date: 2010-07-10 21:28:56 UTC
  • mto: (5384.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 5385.
  • Revision ID: marius.kruger@enerweb.co.za-20100710212856-uq4ji3go0u5se7hx
* Update documentation
* add NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/lazy_import.py
1
 
# Copyright (C) 2006-2010 Canonical Ltd
 
1
# Copyright (C) 2006 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
19
19
This includes waiting to import a module until it is actually used.
20
20
 
21
21
Most commonly, the 'lazy_import' function is used to import other modules
22
 
in an on-demand fashion. Typically use looks like::
23
 
 
24
 
    from .lazy_import import lazy_import
 
22
in an on-demand fashion. Typically use looks like:
 
23
    from bzrlib.lazy_import import lazy_import
25
24
    lazy_import(globals(), '''
26
 
    from breezy import (
 
25
    from bzrlib import (
27
26
        errors,
28
27
        osutils,
29
28
        branch,
30
29
        )
31
 
    import breezy.branch
 
30
    import bzrlib.branch
32
31
    ''')
33
32
 
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.
 
33
    Then 'errors, osutils, branch' and 'bzrlib' will exist as lazy-loaded
 
34
    objects which will be replaced with a real object on first use.
36
35
 
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).
 
36
    In general, it is best to only load modules in this way. This is because
 
37
    it isn't safe to pass these variables to other functions before they
 
38
    have been replaced. This is especially true for constants, sometimes
 
39
    true for classes or functions (when used as a factory, or you want
 
40
    to inherit from them).
42
41
"""
43
42
 
44
 
from .errors import BzrError, InternalBzrError
45
 
 
46
 
 
47
 
class ImportNameCollision(InternalBzrError):
48
 
 
49
 
    _fmt = ("Tried to import an object to the same name as"
50
 
            " an existing object. %(name)s")
51
 
 
52
 
    def __init__(self, name):
53
 
        BzrError.__init__(self)
54
 
        self.name = name
55
 
 
56
 
 
57
 
class IllegalUseOfScopeReplacer(InternalBzrError):
58
 
 
59
 
    _fmt = ("ScopeReplacer object %(name)r was used incorrectly:"
60
 
            " %(msg)s%(extra)s")
61
 
 
62
 
    def __init__(self, name, msg, extra=None):
63
 
        BzrError.__init__(self)
64
 
        self.name = name
65
 
        self.msg = msg
66
 
        if extra:
67
 
            self.extra = ': ' + str(extra)
68
 
        else:
69
 
            self.extra = ''
70
 
 
71
 
 
72
 
class InvalidImportLine(InternalBzrError):
73
 
 
74
 
    _fmt = "Not a valid import statement: %(msg)\n%(text)s"
75
 
 
76
 
    def __init__(self, text, msg):
77
 
        BzrError.__init__(self)
78
 
        self.text = text
79
 
        self.msg = msg
80
 
 
81
43
 
82
44
class ScopeReplacer(object):
83
45
    """A lazy object that will replace itself in the appropriate scope.
88
50
 
89
51
    __slots__ = ('_scope', '_factory', '_name', '_real_obj')
90
52
 
91
 
    # If you to do x = y, setting this to False will disallow access to
92
 
    # members from the second variable (i.e. x). This should normally
93
 
    # be enabled for reasons of thread safety and documentation, but
94
 
    # will be disabled during the selftest command to check for abuse.
95
 
    _should_proxy = True
 
53
    # Setting this to True will allow you to do x = y, and still access members
 
54
    # from both variables. This should not normally be enabled, but is useful
 
55
    # when building documentation.
 
56
    _should_proxy = False
96
57
 
97
58
    def __init__(self, scope, factory, name):
98
59
        """Create a temporary object in the specified scope.
109
70
        object.__setattr__(self, '_real_obj', None)
110
71
        scope[name] = self
111
72
 
112
 
    def _resolve(self):
113
 
        """Return the real object for which this is a placeholder"""
 
73
    def _replace(self):
 
74
        """Actually replace self with other in the given scope"""
114
75
        name = object.__getattribute__(self, '_name')
115
 
        real_obj = object.__getattribute__(self, '_real_obj')
116
 
        if real_obj is None:
117
 
            # No obj generated previously, so generate from factory and scope.
 
76
        try:
118
77
            factory = object.__getattribute__(self, '_factory')
119
78
            scope = object.__getattribute__(self, '_scope')
120
 
            obj = factory(self, scope, name)
121
 
            if obj is self:
122
 
                raise IllegalUseOfScopeReplacer(
123
 
                    name, msg="Object tried"
124
 
                    " to replace itself, check it's not using its own scope.")
125
 
 
126
 
            # Check if another thread has jumped in while obj was generated.
127
 
            real_obj = object.__getattribute__(self, '_real_obj')
128
 
            if real_obj is None:
129
 
                # Still no prexisting obj, so go ahead and assign to scope and
130
 
                # return. There is still a small window here where races will
131
 
                # not be detected, but safest to avoid additional locking.
132
 
                object.__setattr__(self, '_real_obj', obj)
133
 
                scope[name] = obj
134
 
                return obj
135
 
 
136
 
        # Raise if proxying is disabled as obj has already been generated.
137
 
        if not ScopeReplacer._should_proxy:
138
 
            raise IllegalUseOfScopeReplacer(
139
 
                name, msg="Object already replaced, did you assign it"
140
 
                          " to another variable?")
141
 
        return real_obj
 
79
        except AttributeError, e:
 
80
            # Because ScopeReplacer objects only replace a single
 
81
            # item, passing them to another variable before they are
 
82
            # replaced would cause them to keep getting replaced
 
83
            # (only they are replacing the wrong variable). So we
 
84
            # make it forbidden, and try to give a good error.
 
85
            raise errors.IllegalUseOfScopeReplacer(
 
86
                name, msg="Object already cleaned up, did you assign it"
 
87
                          " to another variable?",
 
88
                extra=e)
 
89
        obj = factory(self, scope, name)
 
90
        if ScopeReplacer._should_proxy:
 
91
            object.__setattr__(self, '_real_obj', obj)
 
92
        scope[name] = obj
 
93
        return obj
 
94
 
 
95
    def _cleanup(self):
 
96
        """Stop holding on to all the extra stuff"""
 
97
        del self._factory
 
98
        del self._scope
 
99
        # We keep _name, so that we can report errors
 
100
        # del self._name
142
101
 
143
102
    def __getattribute__(self, attr):
144
 
        obj = object.__getattribute__(self, '_resolve')()
 
103
        obj = object.__getattribute__(self, '_real_obj')
 
104
        if obj is None:
 
105
            _replace = object.__getattribute__(self, '_replace')
 
106
            obj = _replace()
 
107
            _cleanup = object.__getattribute__(self, '_cleanup')
 
108
            _cleanup()
145
109
        return getattr(obj, attr)
146
110
 
147
111
    def __setattr__(self, attr, value):
148
 
        obj = object.__getattribute__(self, '_resolve')()
 
112
        obj = object.__getattribute__(self, '_real_obj')
 
113
        if obj is None:
 
114
            _replace = object.__getattribute__(self, '_replace')
 
115
            obj = _replace()
 
116
            _cleanup = object.__getattribute__(self, '_cleanup')
 
117
            _cleanup()
149
118
        return setattr(obj, attr, value)
150
119
 
151
120
    def __call__(self, *args, **kwargs):
152
 
        obj = object.__getattribute__(self, '_resolve')()
 
121
        _replace = object.__getattribute__(self, '_replace')
 
122
        obj = _replace()
 
123
        _cleanup = object.__getattribute__(self, '_cleanup')
 
124
        _cleanup()
153
125
        return obj(*args, **kwargs)
154
126
 
155
127
 
156
 
def disallow_proxying():
157
 
    """Disallow lazily imported modules to be used as proxies.
158
 
 
159
 
    Calling this function might cause problems with concurrent imports
160
 
    in multithreaded environments, but will help detecting wasteful
161
 
    indirection, so it should be called when executing unit tests.
162
 
 
163
 
    Only lazy imports that happen after this call are affected.
164
 
    """
165
 
    ScopeReplacer._should_proxy = False
166
 
 
167
 
 
168
 
_builtin_import = __import__
169
 
 
170
 
 
171
128
class ImportReplacer(ScopeReplacer):
172
129
    """This is designed to replace only a portion of an import list.
173
130
 
193
150
        :param scope: The scope that objects should be imported into.
194
151
            Typically this is globals()
195
152
        :param name: The variable name. Often this is the same as the
196
 
            module_path. 'breezy'
 
153
            module_path. 'bzrlib'
197
154
        :param module_path: A list for the fully specified module path
198
 
            ['breezy', 'foo', 'bar']
 
155
            ['bzrlib', 'foo', 'bar']
199
156
        :param member: The member inside the module to import, often this is
200
157
            None, indicating the module is being imported.
201
158
        :param children: Children entries to be imported later.
202
159
            This should be a map of children specifications.
203
 
            ::
204
 
 
205
 
                {'foo':(['breezy', 'foo'], None,
206
 
                    {'bar':(['breezy', 'foo', 'bar'], None {})})
207
 
                }
208
 
 
209
 
        Examples::
210
 
 
 
160
            {'foo':(['bzrlib', 'foo'], None,
 
161
                {'bar':(['bzrlib', 'foo', 'bar'], None {})})
 
162
            }
 
163
        Examples:
211
164
            import foo => name='foo' module_path='foo',
212
165
                          member=None, children={}
213
166
            import foo.bar => name='foo' module_path='foo', member=None,
234
187
        children = object.__getattribute__(self, '_import_replacer_children')
235
188
        member = object.__getattribute__(self, '_member')
236
189
        module_path = object.__getattribute__(self, '_module_path')
237
 
        name = '.'.join(module_path)
 
190
        module_python_path = '.'.join(module_path)
238
191
        if member is not None:
239
 
            module = _builtin_import(name, scope, scope, [member], level=0)
 
192
            module = __import__(module_python_path, scope, scope, [member])
240
193
            return getattr(module, member)
241
194
        else:
242
 
            module = _builtin_import(name, scope, scope, [], level=0)
 
195
            module = __import__(module_python_path, scope, scope, [])
243
196
            for path in module_path[1:]:
244
197
                module = getattr(module, path)
245
198
 
246
199
        # Prepare the children to be imported
247
200
        for child_name, (child_path, child_member, grandchildren) in \
248
 
                children.items():
 
201
                children.iteritems():
249
202
            # Using self.__class__, so that children get children classes
250
203
            # instantiated. (This helps with instrumented tests)
251
204
            cls = object.__getattribute__(self, '__class__')
284
237
 
285
238
    def _convert_imports(self, scope):
286
239
        # Now convert the map into a set of imports
287
 
        for name, info in self.imports.items():
 
240
        for name, info in self.imports.iteritems():
288
241
            self._lazy_import_class(scope, name=name, module_path=info[0],
289
242
                                    member=info[1], children=info[2])
290
243
 
296
249
            elif line.startswith('from '):
297
250
                self._convert_from_str(line)
298
251
            else:
299
 
                raise InvalidImportLine(
300
 
                    line, "doesn't start with 'import ' or 'from '")
 
252
                raise errors.InvalidImportLine(line,
 
253
                    "doesn't start with 'import ' or 'from '")
301
254
 
302
255
    def _convert_import_str(self, import_str):
303
256
        """This converts a import string into an import map.
322
275
                name = as_hunks[1].strip()
323
276
                module_path = as_hunks[0].strip().split('.')
324
277
                if name in self.imports:
325
 
                    raise ImportNameCollision(name)
326
 
                if not module_path[0]:
327
 
                    raise ImportError(path)
 
278
                    raise errors.ImportNameCollision(name)
328
279
                # No children available in 'import foo as bar'
329
280
                self.imports[name] = (module_path, None, {})
330
281
            else:
331
282
                # Now we need to handle
332
283
                module_path = path.split('.')
333
284
                name = module_path[0]
334
 
                if not name:
335
 
                    raise ImportError(path)
336
285
                if name not in self.imports:
337
286
                    # This is a new import that we haven't seen before
338
287
                    module_def = ([name], None, {})
364
313
 
365
314
        from_module_path = from_module.split('.')
366
315
 
367
 
        if not from_module_path[0]:
368
 
            raise ImportError(from_module)
369
 
 
370
316
        for path in import_list.split(','):
371
317
            path = path.strip()
372
318
            if not path:
381
327
            else:
382
328
                name = module = path
383
329
            if name in self.imports:
384
 
                raise ImportNameCollision(name)
 
330
                raise errors.ImportNameCollision(name)
385
331
            self.imports[name] = (from_module_path, module, {})
386
332
 
387
333
    def _canonicalize_import_text(self, text):
392
338
        """
393
339
        out = []
394
340
        cur = None
 
341
        continuing = False
395
342
 
396
343
        for line in text.split('\n'):
397
344
            line = line.strip()
413
360
                else:
414
361
                    out.append(line.replace('(', '').replace(')', ''))
415
362
        if cur is not None:
416
 
            raise InvalidImportLine(cur, 'Unmatched parenthesis')
 
363
            raise errors.InvalidImportLine(cur, 'Unmatched parenthesis')
417
364
        return out
418
365
 
419
366
 
420
367
def lazy_import(scope, text, lazy_import_class=None):
421
368
    """Create lazy imports for all of the imports in text.
422
369
 
423
 
    This is typically used as something like::
424
 
 
425
 
        from breezy.lazy_import import lazy_import
426
 
        lazy_import(globals(), '''
427
 
        from breezy import (
428
 
            foo,
429
 
            bar,
430
 
            baz,
431
 
            )
432
 
        import breezy.branch
433
 
        import breezy.transport
434
 
        ''')
435
 
 
436
 
    Then 'foo, bar, baz' and 'breezy' will exist as lazy-loaded
 
370
    This is typically used as something like:
 
371
    from bzrlib.lazy_import import lazy_import
 
372
    lazy_import(globals(), '''
 
373
    from bzrlib import (
 
374
        foo,
 
375
        bar,
 
376
        baz,
 
377
        )
 
378
    import bzrlib.branch
 
379
    import bzrlib.transport
 
380
    ''')
 
381
 
 
382
    Then 'foo, bar, baz' and 'bzrlib' will exist as lazy-loaded
437
383
    objects which will be replaced with a real object on first use.
438
384
 
439
385
    In general, it is best to only load modules in this way. This is
444
390
    # This is just a helper around ImportProcessor.lazy_import
445
391
    proc = ImportProcessor(lazy_import_class=lazy_import_class)
446
392
    return proc.lazy_import(scope, text)
 
393
 
 
394
 
 
395
# The only module that this module depends on is 'bzrlib.errors'. But it
 
396
# can actually be imported lazily, since we only need it if there is a
 
397
# problem.
 
398
 
 
399
lazy_import(globals(), """
 
400
from bzrlib import errors
 
401
""")