Skip to content

statements

Error

Bases: Statement

Source code in src/robot/parsing/model/statements.py 
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
@Statement.register
class Error(Statement):
    type = Token.ERROR
    _errors: 'tuple[str, ...]' = ()

    @classmethod
    def from_params(cls, error: str, value: str = '', indent: str = FOUR_SPACES,
                    eol: str = EOL) -> 'Error':
        return cls([
            Token(Token.SEPARATOR, indent),
            Token(Token.ERROR, value, error=error),
            Token(Token.EOL, eol)
        ])

    @property
    def values(self) -> 'list[str]':
        return [token.value for token in self.data_tokens]

    @property
    def errors(self) -> 'tuple[str, ...]':
        """Errors got from the underlying ``ERROR``token.

        Errors can be set also explicitly. When accessing errors, they are returned
        along with errors got from tokens.
        """
        tokens = self.get_tokens(Token.ERROR)
        return tuple(t.error or '' for t in tokens) + self._errors

    @errors.setter
    def errors(self, errors: 'Sequence[str]'):
        self._errors = tuple(errors)

errors: tuple[str, ...] property writable

Errors got from the underlying ERRORtoken.

Errors can be set also explicitly. When accessing errors, they are returned along with errors got from tokens.

from_tokens(tokens) classmethod

Create a statement from given tokens.

Statement type is got automatically from token types.

This classmethod should be called from :class:Statement, not from its subclasses. If you know the subclass to use, simply create an instance of it directly.

Source code in src/robot/parsing/model/statements.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def from_tokens(cls, tokens: 'Sequence[Token]') -> 'Statement':
    """Create a statement from given tokens.

    Statement type is got automatically from token types.

    This classmethod should be called from :class:`Statement`, not from
    its subclasses. If you know the subclass to use, simply create an
    instance of it directly.
    """
    handlers = cls.statement_handlers
    for token in tokens:
        if token.type in handlers:
            return handlers[token.type](tokens)
    if any(token.type == Token.ASSIGN for token in tokens):
        return KeywordCall(tokens)
    return EmptyLine(tokens)

get_option(name, default=None)

Return value of a configuration option with the given name.

If the option has not been used, return default.

If the option has been used multiple times, values are joined together. This is typically an error situation and validated elsewhere.

New in Robot Framework 6.1.

Source code in src/robot/parsing/model/statements.py 
162
163
164
165
166
167
168
169
170
171
172
def get_option(self, name: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a configuration option with the given ``name``.

    If the option has not been used, return ``default``.

    If the option has been used multiple times, values are joined together.
    This is typically an error situation and validated elsewhere.

    New in Robot Framework 6.1.
    """
    return self._get_options().get(name, default)

get_token(*types)

Return a token with any of the given types.

If there are no matches, return None. If there are multiple matches, return the first match.

Source code in src/robot/parsing/model/statements.py 
126
127
128
129
130
131
132
133
134
135
def get_token(self, *types: str) -> 'Token|None':
    """Return a token with any of the given ``types``.

    If there are no matches, return ``None``. If there are multiple
    matches, return the first match.
    """
    for token in self.tokens:
        if token.type in types:
            return token
    return None

get_tokens(*types)

Return tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
137
138
139
def get_tokens(self, *types: str) -> 'list[Token]':
    """Return tokens having any of the given ``types``."""
    return [t for t in self.tokens if t.type in types]

get_value(type, default=None)

Return value of a token with the given type.

If there are no matches, return default. If there are multiple matches, return the value of the first match.

Source code in src/robot/parsing/model/statements.py 
149
150
151
152
153
154
155
156
def get_value(self, type: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a token with the given ``type``.

    If there are no matches, return ``default``. If there are multiple
    matches, return the value of the first match.
    """
    token = self.get_token(type)
    return token.value if token else default

get_values(*types)

Return values of tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
158
159
160
def get_values(self, *types: str) -> 'tuple[str, ...]':
    """Return values of tokens having any of the given ``types``."""
    return tuple(t.value for t in self.tokens if t.type in types)

Return

Bases: Statement

Represents the RETURN statement.

This class named ReturnStatement prior to Robot Framework 7.0. The old name still exists as a backwards compatible alias.

Source code in src/robot/parsing/model/statements.py 
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
@Statement.register
class Return(Statement):
    """Represents the RETURN statement.

    This class named ``ReturnStatement`` prior to Robot Framework 7.0.
    The old name still exists as a backwards compatible alias.
    """
    type = Token.RETURN_STATEMENT

    @classmethod
    def from_params(cls, values: 'Sequence[str]' = (), indent: str = FOUR_SPACES,
                    separator: str = FOUR_SPACES, eol: str = EOL) -> 'Return':
        tokens = [Token(Token.SEPARATOR, indent),
                  Token(Token.RETURN_STATEMENT)]
        for value in values:
            tokens.extend([Token(Token.SEPARATOR, separator),
                           Token(Token.ARGUMENT, value)])
        tokens.append(Token(Token.EOL, eol))
        return cls(tokens)

    @property
    def values(self) -> 'tuple[str, ...]':
        return self.get_values(Token.ARGUMENT)

    def validate(self, ctx: 'ValidationContext'):
        if not ctx.in_keyword:
            self.errors += ('RETURN can only be used inside a user keyword.',)
        if ctx.in_finally:
            self.errors += ('RETURN cannot be used in FINALLY branch.',)

from_tokens(tokens) classmethod

Create a statement from given tokens.

Statement type is got automatically from token types.

This classmethod should be called from :class:Statement, not from its subclasses. If you know the subclass to use, simply create an instance of it directly.

Source code in src/robot/parsing/model/statements.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def from_tokens(cls, tokens: 'Sequence[Token]') -> 'Statement':
    """Create a statement from given tokens.

    Statement type is got automatically from token types.

    This classmethod should be called from :class:`Statement`, not from
    its subclasses. If you know the subclass to use, simply create an
    instance of it directly.
    """
    handlers = cls.statement_handlers
    for token in tokens:
        if token.type in handlers:
            return handlers[token.type](tokens)
    if any(token.type == Token.ASSIGN for token in tokens):
        return KeywordCall(tokens)
    return EmptyLine(tokens)

get_option(name, default=None)

Return value of a configuration option with the given name.

If the option has not been used, return default.

If the option has been used multiple times, values are joined together. This is typically an error situation and validated elsewhere.

New in Robot Framework 6.1.

Source code in src/robot/parsing/model/statements.py 
162
163
164
165
166
167
168
169
170
171
172
def get_option(self, name: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a configuration option with the given ``name``.

    If the option has not been used, return ``default``.

    If the option has been used multiple times, values are joined together.
    This is typically an error situation and validated elsewhere.

    New in Robot Framework 6.1.
    """
    return self._get_options().get(name, default)

get_token(*types)

Return a token with any of the given types.

If there are no matches, return None. If there are multiple matches, return the first match.

Source code in src/robot/parsing/model/statements.py 
126
127
128
129
130
131
132
133
134
135
def get_token(self, *types: str) -> 'Token|None':
    """Return a token with any of the given ``types``.

    If there are no matches, return ``None``. If there are multiple
    matches, return the first match.
    """
    for token in self.tokens:
        if token.type in types:
            return token
    return None

get_tokens(*types)

Return tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
137
138
139
def get_tokens(self, *types: str) -> 'list[Token]':
    """Return tokens having any of the given ``types``."""
    return [t for t in self.tokens if t.type in types]

get_value(type, default=None)

Return value of a token with the given type.

If there are no matches, return default. If there are multiple matches, return the value of the first match.

Source code in src/robot/parsing/model/statements.py 
149
150
151
152
153
154
155
156
def get_value(self, type: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a token with the given ``type``.

    If there are no matches, return ``default``. If there are multiple
    matches, return the value of the first match.
    """
    token = self.get_token(type)
    return token.value if token else default

get_values(*types)

Return values of tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
158
159
160
def get_values(self, *types: str) -> 'tuple[str, ...]':
    """Return values of tokens having any of the given ``types``."""
    return tuple(t.value for t in self.tokens if t.type in types)

ReturnSetting

Bases: MultiValue

Represents the deprecated [Return] setting.

This class was named Return prior to Robot Framework 7.0. A forward compatible ReturnSetting alias existed already in Robot Framework 6.1.

Source code in src/robot/parsing/model/statements.py 
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
@Statement.register
class ReturnSetting(MultiValue):
    """Represents the deprecated ``[Return]`` setting.

    This class was named ``Return`` prior to Robot Framework 7.0. A forward
    compatible ``ReturnSetting`` alias existed already in Robot Framework 6.1.
    """
    type = Token.RETURN

    @classmethod
    def from_params(cls, args: 'Sequence[str]', indent: str = FOUR_SPACES,
                    separator: str = FOUR_SPACES, eol: str = EOL) -> 'ReturnSetting':
        tokens = [Token(Token.SEPARATOR, indent),
                  Token(Token.RETURN, '[Return]')]
        for arg in args:
            tokens.extend([Token(Token.SEPARATOR, separator),
                           Token(Token.ARGUMENT, arg)])
        tokens.append(Token(Token.EOL, eol))
        return cls(tokens)

from_tokens(tokens) classmethod

Create a statement from given tokens.

Statement type is got automatically from token types.

This classmethod should be called from :class:Statement, not from its subclasses. If you know the subclass to use, simply create an instance of it directly.

Source code in src/robot/parsing/model/statements.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def from_tokens(cls, tokens: 'Sequence[Token]') -> 'Statement':
    """Create a statement from given tokens.

    Statement type is got automatically from token types.

    This classmethod should be called from :class:`Statement`, not from
    its subclasses. If you know the subclass to use, simply create an
    instance of it directly.
    """
    handlers = cls.statement_handlers
    for token in tokens:
        if token.type in handlers:
            return handlers[token.type](tokens)
    if any(token.type == Token.ASSIGN for token in tokens):
        return KeywordCall(tokens)
    return EmptyLine(tokens)

get_option(name, default=None)

Return value of a configuration option with the given name.

If the option has not been used, return default.

If the option has been used multiple times, values are joined together. This is typically an error situation and validated elsewhere.

New in Robot Framework 6.1.

Source code in src/robot/parsing/model/statements.py 
162
163
164
165
166
167
168
169
170
171
172
def get_option(self, name: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a configuration option with the given ``name``.

    If the option has not been used, return ``default``.

    If the option has been used multiple times, values are joined together.
    This is typically an error situation and validated elsewhere.

    New in Robot Framework 6.1.
    """
    return self._get_options().get(name, default)

get_token(*types)

Return a token with any of the given types.

If there are no matches, return None. If there are multiple matches, return the first match.

Source code in src/robot/parsing/model/statements.py 
126
127
128
129
130
131
132
133
134
135
def get_token(self, *types: str) -> 'Token|None':
    """Return a token with any of the given ``types``.

    If there are no matches, return ``None``. If there are multiple
    matches, return the first match.
    """
    for token in self.tokens:
        if token.type in types:
            return token
    return None

get_tokens(*types)

Return tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
137
138
139
def get_tokens(self, *types: str) -> 'list[Token]':
    """Return tokens having any of the given ``types``."""
    return [t for t in self.tokens if t.type in types]

get_value(type, default=None)

Return value of a token with the given type.

If there are no matches, return default. If there are multiple matches, return the value of the first match.

Source code in src/robot/parsing/model/statements.py 
149
150
151
152
153
154
155
156
def get_value(self, type: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a token with the given ``type``.

    If there are no matches, return ``default``. If there are multiple
    matches, return the value of the first match.
    """
    token = self.get_token(type)
    return token.value if token else default

get_values(*types)

Return values of tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
158
159
160
def get_values(self, *types: str) -> 'tuple[str, ...]':
    """Return values of tokens having any of the given ``types``."""
    return tuple(t.value for t in self.tokens if t.type in types)

Statement

Bases: Node, ABC

Source code in src/robot/parsing/model/statements.py 
 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
206
207
208
209
210
211
212
213
class Statement(Node, ABC):
    _attributes = ('type', 'tokens') + Node._attributes
    type: str
    handles_types: 'ClassVar[tuple[str, ...]]' = ()
    statement_handlers: 'ClassVar[dict[str, Type[Statement]]]' = {}
    # Accepted configuration options. If the value is a tuple, it lists accepted
    # values. If the used value contains a variable, it cannot be validated.
    options: 'dict[str, tuple|None]' = {}

    def __init__(self, tokens: 'Sequence[Token]', errors: 'Sequence[str]' = ()):
        self.tokens = tuple(tokens)
        self.errors = tuple(errors)

    @property
    def lineno(self) -> int:
        return self.tokens[0].lineno if self.tokens else -1

    @property
    def col_offset(self) -> int:
        return self.tokens[0].col_offset if self.tokens else -1

    @property
    def end_lineno(self) -> int:
        return self.tokens[-1].lineno if self.tokens else -1

    @property
    def end_col_offset(self) -> int:
        return self.tokens[-1].end_col_offset if self.tokens else -1

    @classmethod
    def register(cls, subcls: Type[T]) -> Type[T]:
        types = subcls.handles_types or (subcls.type,)
        for typ in types:
            cls.statement_handlers[typ] = subcls
        return subcls

    @classmethod
    def from_tokens(cls, tokens: 'Sequence[Token]') -> 'Statement':
        """Create a statement from given tokens.

        Statement type is got automatically from token types.

        This classmethod should be called from :class:`Statement`, not from
        its subclasses. If you know the subclass to use, simply create an
        instance of it directly.
        """
        handlers = cls.statement_handlers
        for token in tokens:
            if token.type in handlers:
                return handlers[token.type](tokens)
        if any(token.type == Token.ASSIGN for token in tokens):
            return KeywordCall(tokens)
        return EmptyLine(tokens)

    @classmethod
    @abstractmethod
    def from_params(cls, *args, **kwargs) -> 'Statement':
        """Create a statement from passed parameters.

        Required and optional arguments in general match class properties.
        Values are used to create matching tokens.

        Most implementations support following general properties:

        - ``separator`` whitespace inserted between each token. Default is four spaces.
        - ``indent`` whitespace inserted before first token. Default is four spaces.
        - ``eol`` end of line sign. Default is ``'\\n'``.

        This classmethod should be called from the :class:`Statement` subclass
        to create, not from the :class:`Statement` class itself.
        """
        raise NotImplementedError

    @property
    def data_tokens(self) -> 'list[Token]':
        return [t for t in self.tokens if t.type not in Token.NON_DATA_TOKENS]

    def get_token(self, *types: str) -> 'Token|None':
        """Return a token with any of the given ``types``.

        If there are no matches, return ``None``. If there are multiple
        matches, return the first match.
        """
        for token in self.tokens:
            if token.type in types:
                return token
        return None

    def get_tokens(self, *types: str) -> 'list[Token]':
        """Return tokens having any of the given ``types``."""
        return [t for t in self.tokens if t.type in types]

    @overload
    def get_value(self, type: str, default: str) -> str:
        ...

    @overload
    def get_value(self, type: str, default: None = None) -> 'str|None':
        ...

    def get_value(self, type: str, default: 'str|None' = None) -> 'str|None':
        """Return value of a token with the given ``type``.

        If there are no matches, return ``default``. If there are multiple
        matches, return the value of the first match.
        """
        token = self.get_token(type)
        return token.value if token else default

    def get_values(self, *types: str) -> 'tuple[str, ...]':
        """Return values of tokens having any of the given ``types``."""
        return tuple(t.value for t in self.tokens if t.type in types)

    def get_option(self, name: str, default: 'str|None' = None) -> 'str|None':
        """Return value of a configuration option with the given ``name``.

        If the option has not been used, return ``default``.

        If the option has been used multiple times, values are joined together.
        This is typically an error situation and validated elsewhere.

        New in Robot Framework 6.1.
        """
        return self._get_options().get(name, default)

    def _get_options(self) -> 'dict[str, str]':
        return dict(opt.split('=', 1) for opt in self.get_values(Token.OPTION))

    @property
    def lines(self) -> 'Iterator[list[Token]]':
        line = []
        for token in self.tokens:
            line.append(token)
            if token.type == Token.EOL:
                yield line
                line = []
        if line:
            yield line

    def validate(self, ctx: 'ValidationContext'):
        pass

    def _validate_options(self):
        for name, value in self._get_options().items():
            if self.options[name] is not None:
                expected = self.options[name]
                if value.upper() not in expected and not contains_variable(value):
                    self.errors += (f"{self.type} option '{name}' does not accept "
                                    f"value '{value}'. Valid values are "
                                    f"{seq2str(expected)}.",)

    def __iter__(self) -> 'Iterator[Token]':
        return iter(self.tokens)

    def __len__(self) -> int:
        return len(self.tokens)

    def __getitem__(self, item) -> Token:
        return self.tokens[item]

    def __repr__(self) -> str:
        name = type(self).__name__
        tokens = f'tokens={list(self.tokens)}'
        errors = f', errors={list(self.errors)}' if self.errors else ''
        return f'{name}({tokens}{errors})'

from_params(*args, **kwargs) abstractmethod classmethod

Create a statement from passed parameters.

Required and optional arguments in general match class properties. Values are used to create matching tokens.

Most implementations support following general properties:

  • separator whitespace inserted between each token. Default is four spaces.
  • indent whitespace inserted before first token. Default is four spaces.
  • eol end of line sign. Default is '\n'.

This classmethod should be called from the :class:Statement subclass to create, not from the :class:Statement class itself.

Source code in src/robot/parsing/model/statements.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@classmethod
@abstractmethod
def from_params(cls, *args, **kwargs) -> 'Statement':
    """Create a statement from passed parameters.

    Required and optional arguments in general match class properties.
    Values are used to create matching tokens.

    Most implementations support following general properties:

    - ``separator`` whitespace inserted between each token. Default is four spaces.
    - ``indent`` whitespace inserted before first token. Default is four spaces.
    - ``eol`` end of line sign. Default is ``'\\n'``.

    This classmethod should be called from the :class:`Statement` subclass
    to create, not from the :class:`Statement` class itself.
    """
    raise NotImplementedError

from_tokens(tokens) classmethod

Create a statement from given tokens.

Statement type is got automatically from token types.

This classmethod should be called from :class:Statement, not from its subclasses. If you know the subclass to use, simply create an instance of it directly.

Source code in src/robot/parsing/model/statements.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def from_tokens(cls, tokens: 'Sequence[Token]') -> 'Statement':
    """Create a statement from given tokens.

    Statement type is got automatically from token types.

    This classmethod should be called from :class:`Statement`, not from
    its subclasses. If you know the subclass to use, simply create an
    instance of it directly.
    """
    handlers = cls.statement_handlers
    for token in tokens:
        if token.type in handlers:
            return handlers[token.type](tokens)
    if any(token.type == Token.ASSIGN for token in tokens):
        return KeywordCall(tokens)
    return EmptyLine(tokens)

get_option(name, default=None)

Return value of a configuration option with the given name.

If the option has not been used, return default.

If the option has been used multiple times, values are joined together. This is typically an error situation and validated elsewhere.

New in Robot Framework 6.1.

Source code in src/robot/parsing/model/statements.py 
162
163
164
165
166
167
168
169
170
171
172
def get_option(self, name: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a configuration option with the given ``name``.

    If the option has not been used, return ``default``.

    If the option has been used multiple times, values are joined together.
    This is typically an error situation and validated elsewhere.

    New in Robot Framework 6.1.
    """
    return self._get_options().get(name, default)

get_token(*types)

Return a token with any of the given types.

If there are no matches, return None. If there are multiple matches, return the first match.

Source code in src/robot/parsing/model/statements.py 
126
127
128
129
130
131
132
133
134
135
def get_token(self, *types: str) -> 'Token|None':
    """Return a token with any of the given ``types``.

    If there are no matches, return ``None``. If there are multiple
    matches, return the first match.
    """
    for token in self.tokens:
        if token.type in types:
            return token
    return None

get_tokens(*types)

Return tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
137
138
139
def get_tokens(self, *types: str) -> 'list[Token]':
    """Return tokens having any of the given ``types``."""
    return [t for t in self.tokens if t.type in types]

get_value(type, default=None)

Return value of a token with the given type.

If there are no matches, return default. If there are multiple matches, return the value of the first match.

Source code in src/robot/parsing/model/statements.py 
149
150
151
152
153
154
155
156
def get_value(self, type: str, default: 'str|None' = None) -> 'str|None':
    """Return value of a token with the given ``type``.

    If there are no matches, return ``default``. If there are multiple
    matches, return the value of the first match.
    """
    token = self.get_token(type)
    return token.value if token else default

get_values(*types)

Return values of tokens having any of the given types.

Source code in src/robot/parsing/model/statements.py 
158
159
160
def get_values(self, *types: str) -> 'tuple[str, ...]':
    """Return values of tokens having any of the given ``types``."""
    return tuple(t.value for t in self.tokens if t.type in types)