Package logilab :: Package common :: Module modutils

[frames] | no frames]

# Module modutils

source code

    Python modules manipulation utility functions.

    :type PY_SOURCE_EXTS: tuple(str)
    :var PY_SOURCE_EXTS: list of possible python source file extension

    :type STD_LIB_DIR: str
    :var STD_LIB_DIR: directory where standard modules are located

    :type BUILTIN_MODULES: dict
    :var BUILTIN_MODULES: dictionary with builtin module names as key

Classes
| NoSourceFile exception raised when we are not able to get a python...
| LazyObject

Functions

load_module_from_name(dotted_name, path=None, use_sys=True) Load a Python module from its name. | source code

load_module_from_modpath(parts, path=None, use_sys=True) Load a python module from its splitted name. | source code

load_module_from_file(filepath, path=None, use_sys=True, extrapath=None) Load a Python module from it's path. | source code

modpath_from_file(filename, extrapath=None) DEPRECATED: doens't play well with symlinks and sys.meta_path | source code

file_from_modpath(modpath, path=None, context_file=None) given a mod path (i.e. | source code

get_module_part(dotted_name, context_file=None) given a dotted name return the module part of the name : | source code

get_modules(package, src_directory, blacklist=STD_BLACKLIST) given a package directory return a list of all available python modules in the package and its subpackages | source code

get_module_files(src_directory, blacklist=STD_BLACKLIST) given a package directory return a list of all available python module's files in the package and its subpackages | source code

get_source_file(filename, include_no_ext=False) given a python module's file name return the matching source file name (the filename will be returned identically if it's a already an absolute path to a python source file...) | source code

cleanup_sys_modules(directories) remove submodules of `directories` from `sys.modules` | source code

clean_sys_modules(names) remove submodules starting with name from `names` from `sys.modules` | source code

is_python_source(filename) rtype: bool... | source code

is_standard_module(modname, std_path=(STD_LIB_DIR,)) try to guess if a module is a standard python module (by default, see `std_path` parameter's description) | source code

is_relative(modname, from_file) return true if the given module name is relative to the given file name | source code

Variables
| zipimport = `None` hash(x)
| ZIPFILE = `object()`
| PY_SOURCE_EXTS = `'py',`
| PY_COMPILED_EXTS = `'so',`
| STD_LIB_DIR = `'//'`
| EXT_LIB_DIR = `get_python_lib()`
| BUILTIN_MODULES = `dict.fromkeys(sys.builtin_module_names, True)`
| pkg_resources = `None` hash(x)

Function Details

### load_module_from_name(dotted_name, path=None, use_sys=True)

source code

    Load a Python module from its name.

    :type dotted_name: str
    :param dotted_name: python name of a module or package

    :type path: list or None
    :param path:
      optional list of path where the module or package should be
      searched (use sys.path if nothing or None is given)

    :type use_sys: bool
    :param use_sys:
      boolean indicating whether the sys.modules dictionary should be
      used or not

    :raise ImportError: if the module or package is not found

    :rtype: module
    :return: the loaded module

### load_module_from_modpath(parts, path=None, use_sys=True)

source code

    Load a python module from its splitted name.

    :type parts: list(str) or tuple(str)
    :param parts:
      python name of a module or package splitted on '.'

    :type path: list or None
    :param path:
      optional list of path where the module or package should be
      searched (use sys.path if nothing or None is given)

    :type use_sys: bool
    :param use_sys:
      boolean indicating whether the sys.modules dictionary should be used or not

    :raise ImportError: if the module or package is not found

    :rtype: module
    :return: the loaded module

### load_module_from_file(filepath, path=None, use_sys=True, extrapath=None)

source code

    Load a Python module from it's path.

    :type filepath: str
    :param filepath: path to the python module or package

    :type path: list or None
    :param path:
      optional list of path where the module or package should be
      searched (use sys.path if nothing or None is given)

    :type use_sys: bool
    :param use_sys:
      boolean indicating whether the sys.modules dictionary should be
      used or not

    :raise ImportError: if the module or package is not found

    :rtype: module
    :return: the loaded module

### modpath_from_file(filename, extrapath=None)

source code

    DEPRECATED: doens't play well with symlinks and sys.meta_path

    Given a file path return the corresponding splitted module's name
    (i.e name of a module or package splitted on '.')

    :type filename: str
    :param filename: file's path for which we want the module's name

    :type extrapath: dict
    :param extrapath:
      optional extra search path, with path as key and package name for the path
      as value. This is usually useful to handle package splitted in multiple
      directories using __path__ trick.

    :raise ImportError:
      if the corresponding module's name has not been found

    :rtype: list(str)
    :return: the corresponding splitted module's name

Decorators:
  - `@deprecated('you should avoid using modpath_from_file()')`

### file_from_modpath(modpath, path=None, context_file=None)

source code

    given a mod path (i.e. splitted module / package name), return the
    corresponding file, giving priority to source file over precompiled
    file if it exists

    :type modpath: list or tuple
    :param modpath:
      splitted module's name (i.e name of a module or package splitted
      on '.')
      (this means explicit relative imports that start with dots have
      empty strings in this list!)

    :type path: list or None
    :param path:
      optional list of path where the module or package should be
      searched (use sys.path if nothing or None is given)

    :type context_file: str or None
    :param context_file:
      context file to consider, necessary if the identifier has been
      introduced using a relative import unresolvable in the actual
      context (i.e. modutils)

    :raise ImportError: if there is no such module in the directory

    :rtype: str or None
    :return:
      the path to the module's file or None if it's an integrated
      builtin module such as 'sys'

### get_module_part(dotted_name, context_file=None)

source code

    given a dotted name return the module part of the name :

    >>> get_module_part('logilab.common.modutils.get_module_part')
    'logilab.common.modutils'

    :type dotted_name: str
    :param dotted_name: full name of the identifier we are interested in

    :type context_file: str or None
    :param context_file:
      context file to consider, necessary if the identifier has been
      introduced using a relative import unresolvable in the actual
      context (i.e. modutils)

    :raise ImportError: if there is no such module in the directory

    :rtype: str or None
    :return:
      the module part of the name or None if we have not been able at
      all to import the given name

    XXX: deprecated, since it doesn't handle package precedence over module
    (see #10066)

### get_modules(package, src_directory, blacklist=STD_BLACKLIST)

source code

    given a package directory return a list of all available python
    modules in the package and its subpackages

    :type package: str
    :param package: the python name for the package

    :type src_directory: str
    :param src_directory:
      path of the directory corresponding to the package

    :type blacklist: list or tuple
    :param blacklist:
      optional list of files or directory to ignore, default to
      the value of `logilab.common.STD_BLACKLIST`

    :rtype: list
    :return:
      the list of all available python modules in the package and its
      subpackages

### get_module_files(src_directory, blacklist=STD_BLACKLIST)

source code

    given a package directory return a list of all available python
    module's files in the package and its subpackages

    :type src_directory: str
    :param src_directory:
      path of the directory corresponding to the package

    :type blacklist: list or tuple
    :param blacklist:
      optional list of files or directory to ignore, default to the value of
      `logilab.common.STD_BLACKLIST`

    :rtype: list
    :return:
      the list of all available python module's files in the package and
      its subpackages

### get_source_file(filename, include_no_ext=False)

source code

    given a python module's file name return the matching source file
    name (the filename will be returned identically if it's a already an
    absolute path to a python source file...)

    :type filename: str
    :param filename: python module's file name

    :raise NoSourceFile: if no source file exists on the file system

    :rtype: str
    :return: the absolute path of the source file if it exists

### is_python_source(filename)

source code

    rtype: bool
    return: True if the filename is a python source file

### is_standard_module(modname, std_path=(STD_LIB_DIR,))

source code

    try to guess if a module is a standard python module (by default,
    see `std_path` parameter's description)

    :type modname: str
    :param modname: name of the module we are interested in

    :type std_path: list(str) or tuple(str)
    :param std_path: list of path considered as standard

    :rtype: bool
    :return:
      true if the module:
      - is located on the path listed in one of the directory in `std_path`
      - is a built-in module

    Note: this function is known to return wrong values when inside virtualenv.
    See https://www.logilab.org/ticket/294756.

### is_relative(modname, from_file)

source code

    return true if the given module name is relative to the given
    file name

    :type modname: str
    :param modname: name of the module we are interested in

    :type from_file: str
    :param from_file:
      path of the module from which modname has been imported

    :rtype: bool
    :return:
      true if the module has been imported relatively to `from_file`