Skip to content

robot.utils.importer

Importer 

1
Importer(type=None, logger=None)

Utility that can import modules and classes based on names and paths.

Imported classes can optionally be instantiated automatically.

:param type: Type of the thing being imported. Used in error and log messages. :param logger: Logger to be notified about successful imports and other events. Currently only needs the info method, but other level specific methods may be needed in the future. If not given, logging is disabled.

Source code in src/robot/utils/importer.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(self, type=None, logger=None):
    """
    :param type:
        Type of the thing being imported. Used in error and log messages.
    :param logger:
        Logger to be notified about successful imports and other events.
        Currently only needs the ``info`` method, but other level specific
        methods may be needed in the future. If not given, logging is disabled.
    """
    self._type = type or ''
    self._logger = logger or NoLogger()
    library_import = type and type.upper() == 'LIBRARY'
    self._importers = (ByPathImporter(logger, library_import),
                       NonDottedImporter(logger, library_import),
                       DottedImporter(logger, library_import))
    self._by_path_importer = self._importers[0]

import_class_or_module 

1
2
3
4
5
import_class_or_module(
    name_or_path,
    instantiate_with_args=None,
    return_source=False,
)

Imports Python class or module based on the given name or path.

:param name_or_path: Name or path of the module or class to import. :param instantiate_with_args: When arguments are given, imported classes are automatically initialized using them. :param return_source: When true, returns a tuple containing the imported module or class and a path to it. By default, returns only the imported module or class.

The class or module to import can be specified either as a name, in which case it must be in the module search path, or as a path to the file or directory implementing the module. See :meth:import_class_or_module_by_path for more information about importing classes and modules by path.

Classes can be imported from the module search path using name like modulename.ClassName. If the class name and module name are same, using just CommonName is enough. When importing a class by a path, the class name and the module name must match.

Optional arguments to use when creating an instance are given as a list. Starting from Robot Framework 4.0, both positional and named arguments are supported (e.g. ['positional', 'name=value']) and arguments are converted automatically based on type hints and default values.

If arguments needed when creating an instance are initially embedded into the name or path like Example:arg1:arg2, separate :func:~robot.utils.text.split_args_from_name_or_path function can be used to split them before calling this method.

Use :meth:import_module if only a module needs to be imported.

Source code in src/robot/utils/importer.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def import_class_or_module(self, name_or_path, instantiate_with_args=None,
                           return_source=False):
    """Imports Python class or module based on the given name or path.

    :param name_or_path:
        Name or path of the module or class to import.
    :param instantiate_with_args:
        When arguments are given, imported classes are automatically initialized
        using them.
    :param return_source:
        When true, returns a tuple containing the imported module or class
        and a path to it. By default, returns only the imported module or class.

    The class or module to import can be specified either as a name, in which
    case it must be in the module search path, or as a path to the file or
    directory implementing the module. See :meth:`import_class_or_module_by_path`
    for more information about importing classes and modules by path.

    Classes can be imported from the module search path using name like
    ``modulename.ClassName``. If the class name and module name are same, using
    just ``CommonName`` is enough. When importing a class by a path, the class
    name and the module name must match.

    Optional arguments to use when creating an instance are given as a list.
    Starting from Robot Framework 4.0, both positional and named arguments are
    supported (e.g. ``['positional', 'name=value']``) and arguments are converted
    automatically based on type hints and default values.

    If arguments needed when creating an instance are initially embedded into
    the name or path like ``Example:arg1:arg2``, separate
    :func:`~robot.utils.text.split_args_from_name_or_path` function can be
    used to split them before calling this method.

    Use :meth:`import_module` if only a module needs to be imported.
    """
    try:
        imported, source = self._import(name_or_path)
        self._log_import_succeeded(imported, name_or_path, source)
        imported = self._instantiate_if_needed(imported, instantiate_with_args)
    except DataError as err:
        self._raise_import_failed(name_or_path, err)
    else:
        return self._handle_return_values(imported, source, return_source)

import_module 

1
import_module(name_or_path)

Imports Python module based on the given name or path.

:param name_or_path: Name or path of the module to import.

The module to import can be specified either as a name, in which case it must be in the module search path, or as a path to the file or directory implementing the module. See :meth:import_class_or_module_by_path for more information about importing modules by path.

Use :meth:import_class_or_module if it is desired to get a class from the imported module automatically.

New in Robot Framework 6.0.

Source code in src/robot/utils/importer.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def import_module(self, name_or_path):
    """Imports Python module based on the given name or path.

    :param name_or_path:
        Name or path of the module to import.

    The module to import can be specified either as a name, in which
    case it must be in the module search path, or as a path to the file or
    directory implementing the module. See :meth:`import_class_or_module_by_path`
    for more information about importing modules by path.

    Use :meth:`import_class_or_module` if it is desired to get a class
    from the imported module automatically.

    New in Robot Framework 6.0.
    """
    try:
        imported, source = self._import(name_or_path, get_class=False)
        self._log_import_succeeded(imported, name_or_path, source)
    except DataError as err:
        self._raise_import_failed(name_or_path, err)
    else:
        return imported

import_class_or_module_by_path 

1
2
3
import_class_or_module_by_path(
    path, instantiate_with_args=None
)

Import a Python module or class using a file system path.

:param path: Path to the module or class to import. :param instantiate_with_args: When arguments are given, imported classes are automatically initialized using them.

When importing a Python file, the path must end with :file:.py and the actual file must also exist.

Use :meth:import_class_or_module to support importing also using name, not only path. See the documentation of that function for more information about creating instances automatically.

Source code in src/robot/utils/importer.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def import_class_or_module_by_path(self, path, instantiate_with_args=None):
    """Import a Python module or class using a file system path.

    :param path:
        Path to the module or class to import.
    :param instantiate_with_args:
        When arguments are given, imported classes are automatically initialized
        using them.

    When importing a Python file, the path must end with :file:`.py` and the
    actual file must also exist.

    Use :meth:`import_class_or_module` to support importing also using name,
    not only path. See the documentation of that function for more information
    about creating instances automatically.
    """
    try:
        imported, source = self._by_path_importer.import_(path)
        self._log_import_succeeded(imported, imported.__name__, source)
        return self._instantiate_if_needed(imported, instantiate_with_args)
    except DataError as err:
        self._raise_import_failed(path, err)