# Copyright 2008-2015 Nokia Networks
# Copyright 2016- Robot Framework Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
from pathlib import Path
from typing import Any, Final, Iterable, Literal, overload, Sequence, TYPE_CHECKING
from robot import model
from robot.model import BodyItem, create_fixture, DataDict, ModelObject, Tags
from robot.output import LOGGER
from robot.utils import NOT_SET, setter, unescape as unescape_util
from .arguments import ArgInfo, ArgumentSpec, UserKeywordArgumentParser
from .keywordfinder import KeywordFinder
from .keywordimplementation import KeywordImplementation
from .model import Body, BodyItemParent, Keyword, TestSuite
from .userkeywordrunner import EmbeddedArgumentsRunner, UserKeywordRunner
if TYPE_CHECKING:
from robot.conf import LanguagesLike
from robot.parsing import File
[docs]
class ResourceFile(ModelObject):
"""Represents a resource file."""
repr_args = ("source",)
__slots__ = ("_source", "owner", "doc", "keyword_finder")
def __init__(
self,
source: "Path | str | None" = None,
owner: "TestSuite | None" = None,
doc: str = "",
):
self.source = source
self.owner = owner
self.doc = doc
self.keyword_finder = KeywordFinder["UserKeyword"](self)
self.imports = []
self.variables = []
self.keywords = []
@property
def source(self) -> "Path | None":
if self._source:
return self._source
if self.owner:
return self.owner.source
return None
@source.setter
def source(self, source: "Path | str | None"):
if isinstance(source, str):
source = Path(source)
self._source = source
@property
def name(self) -> "str | None":
"""Resource file name.
``None`` if resource file is part of a suite or if it does not have
:attr:`source`, name of the source file without the extension otherwise.
"""
if self.owner or not self.source:
return None
return self.source.stem
@setter
def imports(self, imports: Sequence["Import"]) -> "Imports":
return Imports(self, imports)
@setter
def variables(self, variables: Sequence["Variable"]) -> "Variables":
return Variables(self, variables)
@setter
def keywords(self, keywords: Sequence["UserKeyword"]) -> "UserKeywords":
return UserKeywords(self, keywords)
[docs]
@classmethod
def from_file_system(cls, path: "Path | str", **config) -> "ResourceFile":
"""Create a :class:`ResourceFile` object based on the give ``path``.
:param path: File path where to read the data from.
:param config: Configuration parameters for :class:`~.builders.ResourceFileBuilder`
class that is used internally for building the suite.
New in Robot Framework 6.1. See also :meth:`from_string` and :meth:`from_model`.
"""
from .builder import ResourceFileBuilder
return ResourceFileBuilder(**config).build(path)
[docs]
@classmethod
def from_string(cls, string: str, **config) -> "ResourceFile":
"""Create a :class:`ResourceFile` object based on the given ``string``.
:param string: String to create the resource file from.
:param config: Configuration parameters for
:func:`~robot.parsing.parser.parser.get_resource_model` used internally.
New in Robot Framework 6.1. See also :meth:`from_file_system` and
:meth:`from_model`.
"""
from robot.parsing import get_resource_model
model = get_resource_model(string, data_only=True, **config)
return cls.from_model(model)
[docs]
@classmethod
def from_model(cls, model: "File") -> "ResourceFile":
"""Create a :class:`ResourceFile` object based on the given ``model``.
:param model: Model to create the suite from.
The model can be created by using the
:func:`~robot.parsing.parser.parser.get_resource_model` function and possibly
modified by other tooling in the :mod:`robot.parsing` module.
New in Robot Framework 6.1. See also :meth:`from_file_system` and
:meth:`from_string`.
"""
from .builder import RobotParser
return RobotParser().parse_resource_model(model)
@overload
def find_keywords(self, name: str, count: Literal[1]) -> "UserKeyword": ...
@overload
def find_keywords(
self,
name: str,
count: "int | None" = None,
) -> "list[UserKeyword]": ...
[docs]
def find_keywords(
self,
name: str,
count: "int | None" = None,
) -> "list[UserKeyword] | UserKeyword":
return self.keyword_finder.find(name, count)
[docs]
def update_docs(self, unescape: bool = False):
"""Parse information from keyword docstring and update it accordingly.
:param unescape: When true, remove backslash escapes from resource file
and keyword documentation.
Updates argument, return value and exception documentation as well
as tags. The information is defined in appropriate sections using
the Google Python Style Guide docstring conventions.
New in Robot Framework 7.5.
"""
if unescape:
self.doc = unescape_util(self.doc)
for kw in self.keywords:
kw.update_docs(unescape)
[docs]
def to_dict(self) -> DataDict:
data = {}
if self._source:
data["source"] = str(self._source)
if self.doc:
data["doc"] = self.doc
if self.imports:
data["imports"] = self.imports.to_dicts()
if self.variables:
data["variables"] = self.variables.to_dicts()
if self.keywords:
data["keywords"] = self.keywords.to_dicts()
return data
[docs]
class UserKeyword(KeywordImplementation):
"""Represents a user keyword."""
type = KeywordImplementation.USER_KEYWORD
fixture_class = Keyword
__slots__ = ("timeout", "_setup", "_teardown")
def __init__(
self,
name: str = "",
args: "ArgumentSpec | Sequence[str] | None" = (),
doc: str = "",
tags: "Tags | Sequence[str]" = (),
timeout: "str | None" = None,
lineno: "int | None" = None,
owner: "ResourceFile | None" = None,
parent: "BodyItemParent | None" = None,
error: "str | None" = None,
):
super().__init__(name, args, doc, tags, lineno, owner, parent, error)
self.timeout = timeout
self._setup = None
self._teardown = None
self.body = []
@setter
def args(self, spec: "ArgumentSpec | Sequence[str] | None") -> ArgumentSpec:
if not spec:
spec = ArgumentSpec()
elif not isinstance(spec, ArgumentSpec):
spec = UserKeywordArgumentParser().parse(spec)
spec.name = lambda: self.full_name
return spec
@setter
def body(self, body: "Sequence[BodyItem | DataDict]") -> Body:
return Body(self, body)
@property
def setup(self) -> Keyword:
"""User keyword setup as a :class:`Keyword` object.
New in Robot Framework 7.0.
"""
if self._setup is None:
self.setup = None
return self._setup
@setup.setter
def setup(self, setup: "Keyword | DataDict | None"):
self._setup = create_fixture(self.fixture_class, setup, self, Keyword.SETUP)
@property
def has_setup(self) -> bool:
"""Check does a keyword have a setup without creating a setup object.
See :attr:`has_teardown` for more information. New in Robot Framework 7.0.
"""
return bool(self._setup)
@property
def teardown(self) -> Keyword:
"""User keyword teardown as a :class:`Keyword` object."""
if self._teardown is None:
self.teardown = None
return self._teardown
@teardown.setter
def teardown(self, teardown: "Keyword | DataDict | None"):
self._teardown = create_fixture(
self.fixture_class,
teardown,
self,
Keyword.TEARDOWN,
)
@property
def has_teardown(self) -> bool:
"""Check does a keyword have a teardown without creating a teardown object.
A difference between using ``if kw.has_teardown:`` and ``if kw.teardown:``
is that accessing the :attr:`teardown` attribute creates a :class:`Keyword`
object representing the teardown even when the user keyword actually does
not have one. This can have an effect on memory usage.
New in Robot Framework 6.1.
"""
return bool(self._teardown)
[docs]
def create_runner(
self,
name: "str | None",
languages: "LanguagesLike" = None,
) -> "UserKeywordRunner | EmbeddedArgumentsRunner":
if self.embedded:
return EmbeddedArgumentsRunner(self, name)
return UserKeywordRunner(self)
[docs]
def bind(self, data: Keyword) -> "UserKeyword":
kw = UserKeyword(
"",
self.args.copy(),
self.doc,
self.tags,
self.timeout,
self.lineno,
self.owner,
data.parent,
self.error,
)
# Avoid possible errors setting name with invalid embedded args.
kw._name = self._name
kw.embedded = self.embedded
if self.has_setup:
kw.setup = self.setup.to_dict()
if self.has_teardown:
kw.teardown = self.teardown.to_dict()
kw.body = self.body.to_dicts()
return kw
[docs]
def to_dict(self) -> DataDict:
data: DataDict = {"name": self.name}
for name, value in [
("args", tuple(self._decorate_arg(a) for a in self.args)),
("doc", self.doc),
("tags", tuple(self.tags)),
("timeout", self.timeout),
("lineno", self.lineno),
("error", self.error),
]:
if value:
data[name] = value
if self.has_setup:
data["setup"] = self.setup.to_dict()
data["body"] = self.body.to_dicts()
if self.has_teardown:
data["teardown"] = self.teardown.to_dict()
return data
def _decorate_arg(self, arg: ArgInfo) -> str:
if arg.kind == arg.VAR_NAMED:
deco = "&"
elif arg.kind in (arg.VAR_POSITIONAL, arg.NAMED_ONLY_MARKER):
deco = "@"
else:
deco = "$"
result = f"{deco}{{{arg.name}}}"
if arg.default is not NOT_SET:
result += f"={arg.default}"
return result
[docs]
class Variable(ModelObject):
repr_args = ("name", "value", "separator")
def __init__(
self,
name: str = "",
value: Sequence[str] = (),
separator: "str | None" = None,
owner: "ResourceFile | None" = None,
lineno: "int | None" = None,
error: "str | None" = None,
):
self.name = name
self.value = tuple(value)
self.separator = separator
self.owner = owner
self.lineno = lineno
self.error = error
@property
def source(self) -> "Path | None":
return self.owner.source if self.owner is not None else None
[docs]
def report_error(self, message: str, level: str = "ERROR"):
source = self.source or "<unknown>"
line = f" on line {self.lineno}" if self.lineno else ""
LOGGER.write(
f"Error in file '{source}'{line}: "
f"Setting variable '{self.name}' failed: {message}",
level,
)
[docs]
def to_dict(self) -> DataDict:
data = {"name": self.name, "value": self.value}
if self.lineno:
data["lineno"] = self.lineno
if self.error:
data["error"] = self.error
return data
def _include_in_repr(self, name: str, value: Any) -> bool:
return not (name == "separator" and value is None)
[docs]
class Import(ModelObject):
"""Represents library, resource file or variable file import."""
LIBRARY: Final = "LIBRARY"
RESOURCE: Final = "RESOURCE"
VARIABLES: Final = "VARIABLES"
repr_args = ("type", "name", "args", "alias")
def __init__(
self,
type: Literal["LIBRARY", "RESOURCE", "VARIABLES"],
name: str,
args: Sequence[str] = (),
alias: "str | None" = None,
owner: "ResourceFile | Keyword | None" = None,
lineno: "int | None" = None,
):
if type not in (self.LIBRARY, self.RESOURCE, self.VARIABLES):
raise ValueError(
f"Invalid import type: Expected '{self.LIBRARY}', "
f"'{self.RESOURCE}' or '{self.VARIABLES}', got '{type}'."
)
self.type = type
self.name = name
self.args = tuple(args)
self.alias = alias
self.owner = owner
self.lineno = lineno
@property
def source(self) -> "Path | None":
return self.owner.source if self.owner is not None else None
@property
def directory(self) -> "Path | None":
source = self.source
return source.parent if source and not source.is_dir() else source
@property
def setting_name(self) -> str:
return self.type.title()
[docs]
def select(self, library: Any, resource: Any, variables: Any) -> Any:
return {
self.LIBRARY: library,
self.RESOURCE: resource,
self.VARIABLES: variables,
}[self.type]
[docs]
def report_error(self, message: str, level: str = "ERROR"):
source = self.source or "<unknown>"
line = f" on line {self.lineno}" if self.lineno else ""
LOGGER.write(f"Error in file '{source}'{line}: {message}", level)
[docs]
@classmethod
def from_dict(cls, data) -> "Import":
return cls(**data)
[docs]
def to_dict(self) -> DataDict:
data: DataDict = {"type": self.type, "name": self.name}
if self.args:
data["args"] = self.args
if self.alias:
data["alias"] = self.alias
if self.lineno:
data["lineno"] = self.lineno
return data
def _include_in_repr(self, name: str, value: Any) -> bool:
return name in ("type", "name") or value
[docs]
class Imports(model.ItemList):
def __init__(self, owner: ResourceFile, imports: Sequence[Import] = ()):
super().__init__(Import, {"owner": owner}, items=imports)
[docs]
def library(
self,
name: str,
args: Sequence[str] = (),
alias: "str | None" = None,
lineno: "int | None" = None,
) -> Import:
"""Create library import."""
return self.create(Import.LIBRARY, name, args, alias, lineno=lineno)
[docs]
def resource(self, name: str, lineno: "int | None" = None) -> Import:
"""Create resource import."""
return self.create(Import.RESOURCE, name, lineno=lineno)
[docs]
def variables(
self,
name: str,
args: Sequence[str] = (),
lineno: "int | None" = None,
) -> Import:
"""Create variables import."""
return self.create(Import.VARIABLES, name, args, lineno=lineno)
[docs]
def create(self, *args, **kwargs) -> Import:
"""Generic method for creating imports.
Import type specific methods :meth:`library`, :meth:`resource` and
:meth:`variables` are recommended over this method.
"""
# RF 6.1 changed types to upper case. Code below adds backwards compatibility.
if args:
args = (args[0].upper(),) + args[1:]
elif "type" in kwargs:
kwargs["type"] = kwargs["type"].upper()
return super().create(*args, **kwargs)
[docs]
class Variables(model.ItemList[Variable]):
def __init__(self, owner: ResourceFile, variables: Sequence[Variable] = ()):
super().__init__(Variable, {"owner": owner}, items=variables)
[docs]
class UserKeywords(model.ItemList[UserKeyword]):
def __init__(self, owner: ResourceFile, keywords: Sequence[UserKeyword] = ()):
self.invalidate_keyword_cache = owner.keyword_finder.invalidate_cache
self.invalidate_keyword_cache()
super().__init__(UserKeyword, {"owner": owner}, items=keywords)
[docs]
def append(self, item: "UserKeyword | DataDict") -> UserKeyword:
self.invalidate_keyword_cache()
return super().append(item)
[docs]
def extend(self, items: "Iterable[UserKeyword | DataDict]"):
self.invalidate_keyword_cache()
return super().extend(items)
def __setitem__(
self, index: "int | slice", item: "Iterable[UserKeyword | DataDict]"
):
self.invalidate_keyword_cache()
return super().__setitem__(index, item)
[docs]
def insert(self, index: int, item: "UserKeyword | DataDict"):
self.invalidate_keyword_cache()
super().insert(index, item)
[docs]
def clear(self):
self.invalidate_keyword_cache()
super().clear()