Modules

flutils offers the following module utility functions:

cherry_pick(namespace)

Replace the calling cherry-pick-definition package module with a cherry-picking module.

Use this function when there is a need to cherry-pick modules. This means the loading and executing, of a module, will be postponed until an attribute is accessed.

Parameters

namespace (dict) – This should always be set to globals()

Return type

None

Warning

For projects where startup time is critical, this function allows for potentially minimizing the cost of loading a module if it is never used. For projects where startup time is not essential, the use of this function is heavily discouraged due to error messages created during loading being postponed and thus occurring out of context.

Example

It is recommended to first build the root package (__init__.py) as a normally desired root package. (Make sure that no functions or classes are defined. If needed, define these in a submodule). For example (mymodule/__init__.py):

"""This is the mymodule docstring."""

from mymodule import mysubmoduleone
import mymodule.mysubmoduletwo as two
from mymodule.mysubmodulethree import afunction
from mymodule.mysubmodulethree import anotherfunction as anotherfuc

MYVAL = 123

To use the cherry_pick function, the root package module (__init__.py) must be converted to a cherry-pick-definition package module. This example is the result of rewriting the root package (above):

"""This is the mymodule docstring."""

from flutils.moduleutils import cherry_pick

MYVAL = 123

__attr_map__ = (
    'mymodule.mysubmoduleone',
    'mymodule.mysubmoduletwo,two',
    'mymodule.mysubmodulethree:afunction',
    'mymodule.mysubmodulethree:anotherfunction,anotherfuc'
)
__additional_attrs__ = dict(
    MYVAL=MYVAL
)

cherry_pick(globals())

As you can see, the imports were each rewritten to a foreign-name and placed in the __attr_map__ tuple.

Then, MYVAL was put in the __additional_attrs__ dictionary. Use this dictionary to pass any values to cherry-picking module.

And finally the cherry_pick function was called with globals() as the only argument.

The result is the expected usage of mymodule:

>> import mymodule
>> mymodule.anotherfunc()
foo bar

To test if a cherry-picked module has been loaded, or not:

>> import sys
>> sys.modules.get('mymodule.mysubmodulethree')

If you get nothing back, it means the cherry-picked module has not been loaded.

Please be aware that there are some cases when all of the cherry-picked modules will be loaded automatically. Using any program that automatically inspects the cherry-picking module will cause the all of the cherry-picked modules to be loaded. Programs such as ipython and pycharm will do this.

lazy_import_module(name, package=None)

Lazy import a python module.

Parameters

• name (str) – specifies what module to import in absolute or relative terms (e.g. either pkg.mod or ..mod).

• package (str, optional) – If name is specified in relative terms, then the package argument must be set to the name of the package which is to act as the anchor for resolving the package name. Defaults to None.

Raises

ImportError – if the given name and package can not be loaded.

Return type

Module

• The lazy imported module with the execution of it’s loader postponed until an attribute accessed.

Warning

For projects where startup time is critical, this function allows for potentially minimizing the cost of loading a module if it is never used. For projects where startup time is not essential then use of this function is heavily discouraged due to error messages created during loading being postponed and thus occurring out of context.

Examples

>>> from flutils.moduleutils import lazy_import_module
>>> module = lazy_import_module('mymodule')

Relative import:

>>> module = lazy_import_module('.mysubmodule', package='mymodule')