robotframework 6.1rc1__zip → 7.0__zip

robotframework-7.0/src/robot/running/arguments/typeinfo.py

@@ -0,0 +1,317 @@
+#  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 collections.abc import Mapping, Sequence, Set
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, ForwardRef, get_type_hints, Literal, Union
+
+from robot.conf import Languages, LanguagesLike
+from robot.errors import DataError
+from robot.utils import (has_args, is_union, NOT_SET, plural_or_not as s, setter,
+                         SetterAwareType, type_name, type_repr, typeddict_types)
+
+from ..context import EXECUTION_CONTEXTS
+from .customconverters import CustomArgumentConverters
+from .typeconverters import TypeConverter
+
+
+TYPE_NAMES = {
+    '...': Ellipsis,
+    'ellipsis': Ellipsis,
+    'any': Any,
+    'str': str,
+    'string': str,
+    'unicode': str,
+    'bool': bool,
+    'boolean': bool,
+    'int': int,
+    'integer': int,
+    'long': int,
+    'float': float,
+    'double': float,
+    'decimal': Decimal,
+    'bytes': bytes,
+    'bytearray': bytearray,
+    'datetime': datetime,
+    'date': date,
+    'timedelta': timedelta,
+    'path': Path,
+    'none': type(None),
+    'list': list,
+    'sequence': list,
+    'tuple': tuple,
+    'dictionary': dict,
+    'dict': dict,
+    'mapping': dict,
+    'map': dict,
+    'set': set,
+    'frozenset': frozenset,
+    'union': Union,
+    'literal': Literal
+}
+LITERAL_TYPES = (int, str, bytes, bool, Enum, type(None))
+
+
+class TypeInfo(metaclass=SetterAwareType):
+    """Represents an argument type.
+
+    Normally created using the :meth:`from_type_hint` classmethod.
+    With unions and parametrized types, :attr:`nested` contains nested types.
+
+    Values can be converted according to this type info by using the
+    :meth:`convert` method.
+
+    Part of the public API starting from Robot Framework 7.0. In such usage
+    should be imported via the :mod:`robot.api` package.
+    """
+    is_typed_dict = False
+    __slots__ = ('name', 'type')
+
+    def __init__(self, name: 'str|None' = None,
+                 type: Any = NOT_SET,
+                 nested: 'Sequence[TypeInfo]|None' = None):
+        if type is NOT_SET:
+            type = TYPE_NAMES.get(name.lower()) if name else None
+        self.name = name
+        self.type = type
+        self.nested = nested
+
+    @setter
+    def nested(self, nested: 'Sequence[TypeInfo]') -> 'tuple[TypeInfo, ...]|None':
+        """Nested types as a tuple of ``TypeInfo`` objects.
+
+        Used with parameterized types and unions.
+        """
+        typ = self.type
+        if self.is_union:
+            self._validate_union(nested)
+        elif nested is None:
+            return None
+        elif typ is None:
+            return tuple(nested)
+        elif typ is Literal:
+            self._validate_literal(nested)
+        elif not isinstance(typ, type):
+            self._report_nested_error(nested)
+        elif issubclass(typ, tuple):
+            if nested[-1].type is Ellipsis:
+                self._validate_nested_count(nested, 2, 'Homogenous tuple', offset=-1)
+        elif issubclass(typ, Sequence) and not issubclass(typ, (str, bytes, bytearray)):
+            self._validate_nested_count(nested, 1)
+        elif issubclass(typ, Set):
+            self._validate_nested_count(nested, 1)
+        elif issubclass(typ, Mapping):
+            self._validate_nested_count(nested, 2)
+        elif typ in TYPE_NAMES.values():
+            self._report_nested_error(nested)
+        return tuple(nested)
+
+    def _validate_union(self, nested):
+        if not nested:
+            raise DataError('Union cannot be empty.')
+
+    def _validate_literal(self, nested):
+        if not nested:
+            raise DataError('Literal cannot be empty.')
+        for info in nested:
+            if not isinstance(info.type, LITERAL_TYPES):
+                raise DataError(f'Literal supports only integers, strings, bytes, '
+                                f'Booleans, enums and None, value {info.name} is '
+                                f'{type_name(info.type)}.')
+
+    def _validate_nested_count(self, nested, expected, kind=None, offset=0):
+        if len(nested) != expected:
+            self._report_nested_error(nested, expected, kind, offset)
+
+    def _report_nested_error(self, nested, expected=0, kind=None, offset=0):
+        expected += offset
+        actual = len(nested) + offset
+        args = ', '.join(str(n) for n in nested)
+        kind = kind or f"'{self.name}{'[]' if expected > 0 else ''}'"
+        if expected == 0:
+            raise DataError(f"{kind} does not accept parameters, "
+                            f"'{self.name}[{args}]' has {actual}.")
+        raise DataError(f"{kind} requires exactly {expected} parameter{s(expected)}, "
+                        f"'{self.name}[{args}]' has {actual}.")
+
+    @property
+    def is_union(self):
+        return self.name == 'Union'
+
+    @classmethod
+    def from_type_hint(cls, hint: Any) -> 'TypeInfo':
+        """Construct a ``TypeInfo`` based on a type hint.
+
+        The type hint can be in various different formats:
+
+        - an actual type such as ``int``
+        - a parameterized type such as ``list[int]``
+        - a union such as ``int | float``
+        - a string such as ``'int'``, ``'list[int]'`` or ``'int | float'``
+        - a ``TypedDict`` (represented as a :class:`TypedDictInfo`)
+        - a sequence of supported type hints to create a union from such as
+          ``[int, float]`` or ``('int', 'list[int]')``
+
+        In special cases, for example with dictionaries or sequences, using the
+        more specialized methods like :meth:`from_dict` or :meth:`from_sequence`
+        may be more appropriate than using this generic method.
+        """
+        if hint is NOT_SET:
+            return cls()
+        if isinstance(hint, ForwardRef):
+            hint = hint.__forward_arg__
+        if isinstance(hint, typeddict_types):
+            return TypedDictInfo(hint.__name__, hint)
+        if is_union(hint):
+            nested = [cls.from_type_hint(a) for a in hint.__args__]
+            return cls('Union', nested=nested)
+        if hasattr(hint, '__origin__'):
+            if hint.__origin__ is Literal:
+                nested = [cls(repr(a) if not isinstance(a, Enum) else a.name, a)
+                          for a in hint.__args__]
+            elif has_args(hint):
+                nested = [cls.from_type_hint(a) for a in hint.__args__]
+            else:
+                nested = None
+            return cls(type_repr(hint, nested=False), hint.__origin__, nested)
+        if isinstance(hint, str):
+            return cls.from_string(hint)
+        if isinstance(hint, (tuple, list)):
+            return cls.from_sequence(hint)
+        if isinstance(hint, type):
+            return cls(type_repr(hint), hint)
+        if hint is None:
+            return cls('None', type(None))
+        if hint is Union:    # Plain `Union` without params.
+            return cls('Union')
+        if hint is Any:
+            return cls('Any', hint)
+        if hint is Ellipsis:
+            return cls('...', hint)
+        return cls(str(hint))
+
+    @classmethod
+    def from_type(cls, hint: type) -> 'TypeInfo':
+        """Construct a ``TypeInfo`` based on an actual type.
+
+        Use :meth:`from_type_hint` if the type hint can also be something else
+        than a concrete type such as a string.
+        """
+        return cls(type_repr(hint), hint)
+
+    @classmethod
+    def from_string(cls, hint: str) -> 'TypeInfo':
+        """Construct a ``TypeInfo`` based on a string.
+
+        In addition to just types names or their aliases like ``int`` or ``integer``,
+        supports also parameterized types like ``list[int]`` as well as unions like
+        ``int | float``.
+
+        Use :meth:`from_type_hint` if the type hint can also be something else
+        than a string such as an actual type.
+        """
+        # Needs to be imported here due to cyclic dependency.
+        from .typeinfoparser import TypeInfoParser
+        try:
+            return TypeInfoParser(hint).parse()
+        except ValueError as err:
+            raise DataError(str(err))
+
+    @classmethod
+    def from_sequence(cls, sequence: 'tuple|list') -> 'TypeInfo':
+        """Construct a ``TypeInfo`` based on a sequence of types.
+
+        Types can be actual types, strings, or anything else accepted by
+        :meth:`from_type_hint`. If the sequence contains just one type,
+        a ``TypeInfo`` created based on it is returned. If there are more
+        types, the returned ``TypeInfo`` represents a union. Using an empty
+        sequence is an error.
+
+        Use :meth:`from_type_hint` if other types than sequences need to
+        supported.
+        """
+        infos = []
+        for typ in sequence:
+            info = cls.from_type_hint(typ)
+            if info.is_union:
+                infos.extend(info.nested)
+            else:
+                infos.append(info)
+        if len(infos) == 1:
+            return infos[0]
+        return cls('Union', nested=infos)
+
+    def convert(self, value: Any,
+                name: 'str|None' = None,
+                custom_converters: 'CustomArgumentConverters|dict|None' = None,
+                languages: 'LanguagesLike' = None,
+                kind: str = 'Argument'):
+        """Convert ``value`` based on type information this ``TypeInfo`` contains.
+
+        :param value: Value to convert.
+        :param name: Name of the argument or other thing to convert.
+            Used only for error reporting.
+        :param custom_converters: Custom argument converters.
+        :param languages: Language configuration. During execution, uses the
+            current language configuration by default.
+        :param kind: Type of the thing to be converted.
+            Used only for error reporting.
+        :raises: ``TypeError`` if there is no converter for this type or
+            ``ValueError`` is conversion fails.
+        :return: Converted value.
+        """
+        if isinstance(custom_converters, dict):
+            custom_converters = CustomArgumentConverters.from_dict(custom_converters)
+        if not languages and EXECUTION_CONTEXTS.current:
+            languages = EXECUTION_CONTEXTS.current.languages
+        elif not isinstance(languages, Languages):
+            languages = Languages(languages)
+        converter = TypeConverter.converter_for(self, custom_converters, languages)
+        if not converter:
+            raise TypeError(f"No converter found for '{self}'.")
+        return converter.convert(value, name, kind)
+
+    def __str__(self):
+        if self.is_union:
+            return ' | '.join(str(n) for n in self.nested)
+        name = self.name or ''
+        if self.nested is None:
+            return name
+        nested = ', '.join(str(n) for n in self.nested)
+        return f'{name}[{nested}]'
+
+    def __bool__(self):
+        return self.name is not None
+
+
+class TypedDictInfo(TypeInfo):
+    """Represents ``TypedDict`` used as an argument."""
+
+    is_typed_dict = True
+    __slots__ = ('annotations', 'required')
+
+    def __init__(self, name: str, type: type):
+        super().__init__(name, type)
+        try:
+            type_hints = get_type_hints(type)
+        except Exception:
+            type_hints = type.__annotations__
+        self.annotations = {name: TypeInfo.from_type_hint(hint)
+                            for name, hint in type_hints.items()}
+        # __required_keys__ is new in Python 3.9.
+        self.required = getattr(type, '__required_keys__', frozenset())

robotframework-7.0/src/robot/running/arguments/typeinfoparser.py

@@ -0,0 +1,219 @@
+#  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 ast import literal_eval
+from enum import auto, Enum
+from dataclasses import dataclass
+from typing import Literal
+
+from .typeinfo import LITERAL_TYPES, TypeInfo
+
+
+class TokenType(Enum):
+    NAME = auto()
+    LEFT_SQUARE = auto()
+    RIGHT_SQUARE = auto()
+    PIPE = auto()
+    COMMA = auto()
+
+    def __repr__(self):
+        return str(self)
+
+
+@dataclass
+class Token:
+    type: TokenType
+    value: str
+    position: int = -1
+
+
+class TypeInfoTokenizer:
+    markers = {
+        '[': TokenType.LEFT_SQUARE,
+        ']': TokenType.RIGHT_SQUARE,
+        '|': TokenType.PIPE,
+        ',': TokenType.COMMA,
+    }
+
+    def __init__(self, source: str):
+        self.source = source
+        self.tokens: 'list[Token]' = []
+        self.start = 0
+        self.current = 0
+
+    @property
+    def at_end(self) -> bool:
+        return self.current >= len(self.source)
+
+    def tokenize(self) -> 'list[Token]':
+        while not self.at_end:
+            self.start = self.current
+            char = self.advance()
+            if char in self.markers:
+                self.add_token(self.markers[char])
+            elif char.strip():
+                self.name()
+        return self.tokens
+
+    def advance(self) -> str:
+        char = self.source[self.current]
+        self.current += 1
+        return char
+
+    def peek(self) -> 'str|None':
+        try:
+            return self.source[self.current]
+        except IndexError:
+            return None
+
+    def name(self):
+        end_at = set(self.markers) | {None}
+        closing_quote = None
+        char = self.source[self.current-1]
+        if char in ('"', "'"):
+            end_at = {None}
+            closing_quote = char
+        elif char == 'b' and self.peek() in ('"', "'"):
+            end_at = {None}
+            closing_quote = self.advance()
+        while True:
+            char = self.peek()
+            if char in end_at:
+                break
+            self.current += 1
+            if char == closing_quote:
+                break
+        self.add_token(TokenType.NAME)
+
+    def add_token(self, type: TokenType):
+        value = self.source[self.start:self.current].strip()
+        self.tokens.append(Token(type, value, self.start))
+
+
+class TypeInfoParser:
+
+    def __init__(self, source: str):
+        self.source = source
+        self.tokens: 'list[Token]' = []
+        self.current = 0
+
+    @property
+    def at_end(self) -> bool:
+        return self.peek() is None
+
+    def parse(self) -> TypeInfo:
+        self.tokens = TypeInfoTokenizer(self.source).tokenize()
+        info = self.type()
+        if not self.at_end:
+            self.error(f"Extra content after '{info}'.")
+        return info
+
+    def type(self) -> TypeInfo:
+        if not self.check(TokenType.NAME):
+            self.error('Type name missing.')
+        info = TypeInfo(self.advance().value)
+        if self.match(TokenType.LEFT_SQUARE):
+            info.nested = self.params(literal=info.type is Literal)
+        if self.match(TokenType.PIPE):
+            nested = [info] + self.union()
+            info = TypeInfo('Union', nested=nested)
+        return info
+
+    def params(self, literal: bool = False) -> 'list[TypeInfo]':
+        params = []
+        prev = None
+        while True:
+            token = self.peek()
+            if not token:
+                self.error("Closing ']' missing.")
+            if token.type is TokenType.RIGHT_SQUARE:
+                self.advance()
+                break
+            if token.type is TokenType.COMMA:
+                if not prev or prev.type is TokenType.COMMA:
+                    self.error("Type missing before ','.")
+                self.advance()
+                prev = token
+                continue
+            if token.type is TokenType.NAME:
+                param = self.type()
+            elif token.type is TokenType.LEFT_SQUARE:
+                self.advance()
+                param = TypeInfo()
+                param.nested = self.params()
+            if literal:
+                param = self._literal_param(param)
+            params.append(param)
+            prev = token
+        if literal and not params:
+            self.error('Literal cannot be empty.')
+        return params
+
+    def _literal_param(self, param: TypeInfo) -> TypeInfo:
+        try:
+            if param.name is None:
+                raise ValueError
+            try:
+                value = literal_eval(param.name)
+            except ValueError:
+                if param.name.isidentifier():
+                    return TypeInfo(param.name, None)
+                raise
+            if not isinstance(value, LITERAL_TYPES):
+                raise ValueError
+        except (ValueError, SyntaxError):
+            self.error(f"Invalid literal value {str(param)!r}.")
+        else:
+            return TypeInfo(repr(value), value)
+
+    def union(self) -> 'list[TypeInfo]':
+        types = []
+        while not types or self.match(TokenType.PIPE):
+            info = self.type()
+            if info.is_union:
+                types.extend(info.nested)
+            else:
+                types.append(info)
+        return types
+
+    def match(self, *types: TokenType) -> bool:
+        for typ in types:
+            if self.check(typ):
+                self.advance()
+                return True
+        return False
+
+    def check(self, expected: TokenType) -> bool:
+        peeked = self.peek()
+        return peeked and peeked.type == expected
+
+    def advance(self) -> 'Token|None':
+        token = self.peek()
+        if token:
+            self.current += 1
+        return token
+
+    def peek(self) -> 'Token|None':
+        try:
+            return self.tokens[self.current]
+        except IndexError:
+            return None
+
+    def error(self, message: str, token: 'Token|None' = None):
+        if not token:
+            token = self.peek()
+        position = f'index {token.position}' if token else 'end'
+        raise ValueError(f"Parsing type {self.source!r} failed: "
+                         f"Error at {position}: {message}")

robotframework-7.0/src/robot/running/arguments/typevalidator.py

@@ -0,0 +1,60 @@
+#  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 collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING
+
+from robot.errors import DataError
+from robot.utils import (is_dict_like, is_list_like, plural_or_not as s,
+                         seq2str, type_name)
+
+from .typeinfo import TypeInfo
+
+if TYPE_CHECKING:
+    from .argumentspec import ArgumentSpec
+
+
+class TypeValidator:
+
+    def __init__(self, spec: 'ArgumentSpec'):
+        self.spec = spec
+
+    def validate(self, types: 'Mapping|Sequence|None') -> 'dict[str, TypeInfo]|None':
+        if types is None:
+            return None
+        if not types:
+            return {}
+        if is_dict_like(types):
+            self._validate_type_dict(types)
+        elif is_list_like(types):
+            types = self._type_list_to_dict(types)
+        else:
+            raise DataError(f'Type information must be given as a dictionary or '
+                            f'a list, got {type_name(types)}.')
+        return {k: TypeInfo.from_type_hint(types[k]) for k in types}
+
+    def _validate_type_dict(self, types: Mapping):
+        names = set(self.spec.argument_names)
+        extra = [t for t in types if t not in names]
+        if extra:
+            raise DataError(f'Type information given to non-existing '
+                            f'argument{s(extra)} {seq2str(sorted(extra))}.')
+
+    def _type_list_to_dict(self, types: Sequence) -> dict:
+        names = self.spec.argument_names
+        if len(types) > len(names):
+            raise DataError(f'Type information given to {len(types)} argument{s(types)} '
+                            f'but keyword has only {len(names)} argument{s(names)}.')
+        return {name: value for name, value in zip(names, types) if value}