### Navigation

- index
- modules |
- previous |
- Miscellaneous »

# Lazy imports

Lazy imports

This module allows one to lazily import objects into a namespace, where the actual import is delayed until the object is actually called or inspected. This is useful for modules that are expensive to import or may cause circular references, though there is some overhead in its use.

EXAMPLES:

    sage: from sage.misc.lazy_import import lazy_import
    sage: lazy_import('sage.rings.all', 'ZZ')
    sage: type(ZZ)
    <type 'sage.misc.lazy_import.LazyImport'>
    sage: ZZ(4.0)
    4

By default, a warning is issued if a lazy import module is resolved during Sage’s startup. In case a lazy import’s sole purpose is to break a circular reference and it is known to be resolved at startup time, one can use the `at_startup` option:

    sage: lazy_import('sage.rings.all', 'ZZ', at_startup=True)

This option can also be used as an intermediate step toward not importing by default a module that is used in several places, some of which can already afford to lazy import the module but not all.

A lazy import that is marked as “at_startup” will print a message if it is actually resolved after the startup, so that the developer knows that (s)he can remove the flag:

    sage: ZZ
    Option ``at_startup=True`` for lazy import ZZ not needed anymore
    Integer Ring

See also

`lazy_import()`, `LazyImport`

AUTHOR:

> - Robert Bradshaw

class `sage.misc.lazy_import.``LazyImport`

  Bases: `object`

  EXAMPLES:

      sage: from sage.misc.lazy_import import LazyImport
      sage: my_integer = LazyImport('sage.rings.all', 'Integer')
      sage: my_integer(4)
      4
      sage: my_integer('101', base=2)
      5
      sage: my_integer(3/2)
      Traceback (most recent call last):
      ...
      TypeError: no conversion of this rational to integer

`sage.misc.lazy_import.``finish_startup`()

  This function must be called exactly once at the end of the Sage import process

  TESTS:

      sage: from sage.misc.lazy_import import finish_startup
      sage: finish_startup()
      Traceback (most recent call last):
      ...
      AssertionError: finish_startup() must be called exactly once

`sage.misc.lazy_import.``get_star_imports`(module_name)

  Lookup the list of names in a module that would be imported with “import *” either via a cache or actually importing.

  EXAMPLES:

      sage: from sage.misc.lazy_import import get_star_imports
      sage: 'get_star_imports' in get_star_imports('sage.misc.lazy_import')
      True
      sage: 'EllipticCurve' in get_star_imports('sage.schemes.all')
      True

  TESTS:

      sage: import os, tempfile
      sage: fd, cache_file = tempfile.mkstemp()
      sage: os.write(fd, 'invalid')
      7
      sage: os.close(fd)
      sage: import sage.misc.lazy_import as lazy
      sage: lazy.get_cache_file = (lambda: cache_file)
      sage: lazy.star_imports = None
      sage: lazy.get_star_imports('sage.schemes.all')
      doctest:...: UserWarning: star_imports cache is corrupted
      [...]
      sage: os.remove(cache_file)

`sage.misc.lazy_import.``is_during_startup`()

  Return whether Sage is currently starting up

  OUTPUT:

  Boolean

  TESTS:

      sage: from sage.misc.lazy_import import is_during_startup
      sage: is_during_startup()
      False

`sage.misc.lazy_import.``lazy_import`(module, names, _as=None, namespace=None, overwrite=True, at_startup=False, deprecation=None)

  Create a lazy import object and inject it into the caller’s global namespace. For the purposes of introspection and calling, this is like performing a lazy “from module import name” where the import is delayed until the object actually is used or inspected.

  INPUT:

  - `module` – a string representing the module to import
  - `names` – a string or list of strings representing the names to import from module
  - `_as` – (optional) a string or list of strings representing the aliases of the names imported
  - `namespace` – the namespace where importing the names; by default, import the names to current namespace
  - `overwrite` – (default: `True`) if set to `True` and a name is already in the namespace, overwrite it with the lazy_import-ed name
  - `at_startup` – a boolean (default: `False`); whether the lazy import is supposed to be resolved at startup time
  - `deprecation` – (optional) if not `None`, a deprecation warning will be issued when the object is actually imported; `deprecation` should be either a trac number (integer) or a pair `(trac_number, message)`

  See also

  `sage.misc.lazy_import`, `LazyImport`

  EXAMPLES:

      sage: from sage.misc.lazy_import import lazy_import
      sage: lazy_import('sage.rings.all', 'ZZ')
      sage: type(ZZ)
      <type 'sage.misc.lazy_import.LazyImport'>
      sage: ZZ(4.0)
      4
      sage: lazy_import('sage.rings.all', 'RDF', 'my_RDF')
      sage: my_RDF._get_object() is RDF
      True
      sage: my_RDF(1/2)
      0.5

      sage: lazy_import('sage.all', ['QQ', 'RR'], ['my_QQ', 'my_RR'])
      sage: my_QQ._get_object() is QQ
      True
      sage: my_RR._get_object() is RR
      True

  Upon the first use, the object is injected directly into the calling namespace:

      sage: lazy_import('sage.all', 'ZZ', 'my_ZZ')
      sage: my_ZZ is ZZ
      False
      sage: my_ZZ(37)
      37
      sage: my_ZZ is ZZ
      True

  We check that `lazy_import()` also works for methods:

      sage: class Foo(object):
      ...       lazy_import('sage.all', 'plot')
      sage: class Bar(Foo):
      ...       pass
      sage: type(Foo.__dict__['plot'])
      <type 'sage.misc.lazy_import.LazyImport'>
      sage: 'EXAMPLES' in Bar.plot.__doc__
      True
      sage: type(Foo.__dict__['plot'])
      <type 'function'>

  If deprecated then a deprecation warning is issued:

      sage: lazy_import('sage.all', 'Qp', 'my_Qp', deprecation=14275)
      sage: my_Qp(5)
      doctest:...: DeprecationWarning:
      Importing my_Qp from here is deprecated. If you need to use it, please import it directly from sage.all
      See http://trac.sagemath.org/14275 for details.
      5-adic Field with capped relative precision 20

  An example of deprecation with a message:

      sage: lazy_import('sage.all', 'Qp', 'my_Qp_msg', deprecation=(14275, "This is an example."))
      sage: my_Qp_msg(5)
      doctest:...: DeprecationWarning: This is an example.
      See http://trac.sagemath.org/14275 for details.
      5-adic Field with capped relative precision 20

`sage.misc.lazy_import.``save_cache_file`()

  Used to save the cached * import names.

  TESTS:

      sage: import sage.misc.lazy_import
      sage: sage.misc.lazy_import.save_cache_file()

`sage.misc.lazy_import.``test_fake_startup`()

  For testing purposes only.

  Switch the startup lazy import guard back on.

  EXAMPLES:

      sage: sage.misc.lazy_import.test_fake_startup()
      sage: from sage.misc.lazy_import import lazy_import
      sage: lazy_import('sage.rings.all', 'ZZ', 'my_ZZ')
      sage: my_ZZ(123)
      -------------------------------------------------------------------------------
      Resolving lazy import ZZ during startup
      Calling stack:
      ...
      -------------------------------------------------------------------------------
      123
      sage: sage.misc.lazy_import.finish_startup()

### Navigation

- index
- modules |
- previous |
- Miscellaneous »