Skip to content

importer

Importer

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

Imported classes can optionally be instantiated automatically.

Source code in src/robot/utils/importer.py 
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 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
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
class Importer:
    """Utility that can import modules and classes based on names and paths.

    Imported classes can optionally be instantiated automatically.
    """

    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]

    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)

    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

    def _import(self, name, get_class=True):
        for importer in self._importers:
            if importer.handles(name):
                return importer.import_(name, get_class)

    def _handle_return_values(self, imported, source, return_source=False):
        if not return_source:
            return imported
        if source and os.path.exists(source):
            source = self._sanitize_source(source)
        return imported, source

    def _sanitize_source(self, source):
        source = normpath(source)
        if os.path.isdir(source):
            candidate = os.path.join(source, '__init__.py')
        elif source.endswith('.pyc'):
            candidate = source[:-4] + '.py'
        else:
            return source
        return candidate if os.path.exists(candidate) else source

    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)

    def _log_import_succeeded(self, item, name, source):
        prefix = f'Imported {self._type.lower()}' if self._type else 'Imported'
        item_type = 'module' if inspect.ismodule(item) else 'class'
        source = f"'{source}'" if source else 'unknown location'
        self._logger.info(f"{prefix} {item_type} '{name}' from {source}.")

    def _raise_import_failed(self, name, error):
        prefix = f'Importing {self._type.lower()}' if self._type else 'Importing'
        raise DataError(f"{prefix} '{name}' failed: {error}")

    def _instantiate_if_needed(self, imported, args):
        if args is None:
            return imported
        if inspect.isclass(imported):
            return self._instantiate_class(imported, args)
        if args:
            raise DataError("Modules do not take arguments.")
        return imported

    def _instantiate_class(self, imported, args):
        spec = self._get_arg_spec(imported)
        try:
            positional, named = spec.resolve(args)
        except ValueError as err:
            raise DataError(err.args[0])
        try:
            return imported(*positional, **dict(named))
        except Exception:
            message, traceback = get_error_details()
            raise DataError(f'Creating instance failed: {message}\n{traceback}')

    def _get_arg_spec(self, imported):
        # Avoid cyclic import. Yuck.
        from robot.running.arguments import ArgumentSpec, PythonArgumentParser

        init = getattr(imported, '__init__', None)
        name = imported.__name__
        if not is_init(init):
            return ArgumentSpec(name, self._type)
        return PythonArgumentParser(self._type).parse(init, name)

__init__(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.

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(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_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)

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