Robot Framework
standardtypes.py
Go to the documentation of this file.
1 # Copyright 2008-2015 Nokia Networks
2 # Copyright 2016- Robot Framework Foundation
3 #
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at
7 #
8 # http://www.apache.org/licenses/LICENSE-2.0
9 #
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
15 
16 from datetime import date, datetime, timedelta
17 from decimal import Decimal
18 from pathlib import Path
19 
20 
21 STANDARD_TYPE_DOCS = {
22  bool: '''\
23 Strings ``TRUE``, ``YES``, ``ON`` and ``1`` are converted to Boolean ``True``,
24 the empty string as well as strings ``FALSE``, ``NO``, ``OFF`` and ``0``
25 are converted to Boolean ``False``, and the string ``NONE`` is converted
26 to the Python ``None`` object. Other strings and other accepted values are
27 passed as-is, allowing keywords to handle them specially if
28 needed. All string comparisons are case-insensitive.
29 
30 Examples: ``TRUE`` (converted to ``True``), ``off`` (converted to ``False``),
31 ``example`` (used as-is)
32 ''',
33  int: '''\
34 Conversion is done using Python's [https://docs.python.org/library/functions.html#int|int]
35 built-in function. Floating point
36 numbers are accepted only if they can be represented as integers exactly.
37 For example, ``1.0`` is accepted and ``1.1`` is not.
38 
39 Starting from RF 4.1, it is possible to use hexadecimal, octal and binary
40 numbers by prefixing values with ``0x``, ``0o`` and ``0b``, respectively.
41 
42 Starting from RF 4.1, spaces and underscores can be used as visual separators
43 for digit grouping purposes.
44 
45 Examples: ``42``, ``-1``, ``0b1010``, ``10 000 000``, ``0xBAD_C0FFEE``
46 ''',
47  float: '''\
48 Conversion is done using Python's
49 [https://docs.python.org/library/functions.html#float|float] built-in function.
50 
51 Starting from RF 4.1, spaces and underscores can be used as visual separators
52 for digit grouping purposes.
53 
54 Examples: ``3.14``, ``2.9979e8``, ``10 000.000 01``
55 ''',
56  Decimal: '''\
57 Conversion is done using Python's
58 [https://docs.python.org/library/decimal.html#decimal.Decimal|Decimal] class.
59 
60 Starting from RF 4.1, spaces and underscores can be used as visual separators
61 for digit grouping purposes.
62 
63 Examples: ``3.14``, ``10 000.000 01``
64 ''',
65  str: 'All arguments are converted to Unicode strings.',
66  bytes: '''\
67 Strings are converted to bytes so that each Unicode code point
68 below 256 is directly mapped to a matching byte. Higher code
69 points are not allowed. Robot Framework's ``\\xHH`` escape syntax is
70 convenient with bytes having non-printable values.
71 
72 Examples: ``good``, ``hyvä`` (same as ``hyv\\xE4``), ``\\x00`` (the null byte)
73 ''',
74  bytearray: 'Set below to same value as `bytes`.',
75  datetime: '''\
76 Strings are expected to be a timestamp in
77 [https://en.wikipedia.org/wiki/ISO_8601|ISO 8601] like
78 format ``YYYY-MM-DD hh:mm:ss.mmmmmm``, where any non-digit
79 character can be used as a separator or separators can be
80 omitted altogether. Additionally, only the date part is
81 mandatory, all possibly missing time components are considered
82 to be zeros.
83 
84 Integers and floats are considered to represent seconds since
85 the [https://en.wikipedia.org/wiki/Unix_time|Unix epoch].
86 
87 Examples: ``2022-02-09T16:39:43.632269``, ``2022-02-09 16:39``,
88 ``${1644417583.632269}`` (Epoch time)
89 ''',
90  date: '''\
91 Strings are expected to be a timestamp in
92 [https://en.wikipedia.org/wiki/ISO_8601|ISO 8601] like date format
93 ``YYYY-MM-DD``, where any non-digit character can be used as a separator
94 or separators can be omitted altogether. Possible time components are
95 only allowed if they are zeros.
96 
97 Examples: ``2022-02-09``, ``2022-02-09 00:00``
98 ''',
99  timedelta: '''\
100 Strings are expected to represent a time interval in one of
101 the time formats Robot Framework supports:
102 - a number representing seconds like ``42`` or ``10.5``
103 - a time string like ``1 hour 2 seconds`` or ``1h 2s``
104 - a "timer" string like ``01:02`` (1 minute 2 seconds) or ``01:00:03`` (1 hour 3 seconds)
105 
106 Integers and floats are considered to be seconds.
107 
108 See the [https://robotframework.org/robotframework/|Robot Framework User Guide]
109 for more details about the supported time formats.
110 ''',
111  Path: '''\
112 Strings are converted [https://docs.python.org/library/pathlib.html|Path] objects.
113 On Windows ``/`` is converted to ``\\`` automatically.
114 
115 Examples: ``/tmp/absolute/path``, ``relative/path/to/file.ext``, ``name.txt``
116 ''',
117  type(None): '''\
118 String ``NONE`` (case-insensitive) is converted to Python ``None`` object.
119 Other values cause an error.
120 ''',
121  list: '''\
122 Strings must be Python [https://docs.python.org/library/stdtypes.html#list|list]
123 literals. They are converted to actual lists using the
124 [https://docs.python.org/library/ast.html#ast.literal_eval|ast.literal_eval]
125 function. They can contain any values ``ast.literal_eval`` supports, including
126 lists and other containers.
127 
128 If the type has nested types like ``list[int]``, items are converted
129 to those types automatically. This in new in Robot Framework 6.0.
130 
131 Examples: ``['one', 'two']``, ``[('one', 1), ('two', 2)]``
132 ''',
133  tuple: '''\
134 Strings must be Python [https://docs.python.org/library/stdtypes.html#tuple|tuple]
135 literals. They are converted to actual tuples using the
136 [https://docs.python.org/library/ast.html#ast.literal_eval|ast.literal_eval]
137 function. They can contain any values ``ast.literal_eval`` supports, including
138 tuples and other containers.
139 
140 If the type has nested types like ``tuple[str, int, int]``, items are converted
141 to those types automatically. This in new in Robot Framework 6.0.
142 
143 Examples: ``('one', 'two')``, ``(('one', 1), ('two', 2))``
144 ''',
145  dict: '''\
146 Strings must be Python [https://docs.python.org/library/stdtypes.html#dict|dictionary]
147 literals. They are converted to actual dictionaries using the
148 [https://docs.python.org/library/ast.html#ast.literal_eval|ast.literal_eval]
149 function. They can contain any values ``ast.literal_eval`` supports, including
150 dictionaries and other containers.
151 
152 If the type has nested types like ``dict[str, int]``, items are converted
153 to those types automatically. This in new in Robot Framework 6.0.
154 
155 Examples: ``{'a': 1, 'b': 2}``, ``{'key': 1, 'nested': {'key': 2}}``
156 ''',
157  set: '''\
158 Strings must be Python [https://docs.python.org/library/stdtypes.html#set|set]
159 literals. They are converted to actual sets using the
160 [https://docs.python.org/library/ast.html#ast.literal_eval|ast.literal_eval]
161 function. They can contain any values ``ast.literal_eval`` supports.
162 
163 If the type has nested types like ``set[int]``, items are converted
164 to those types automatically. This in new in Robot Framework 6.0.
165 
166 Examples: ``{1, 2, 3, 42}``, ``set()`` (an empty set)
167 ''',
168  frozenset: '''\
169 Strings must be Python [https://docs.python.org/library/stdtypes.html#set|set]
170 literals. They are converted to actual sets using the
171 [https://docs.python.org/library/ast.html#ast.literal_eval|ast.literal_eval]
172 function and then converted to ``frozenset`` objects. They can contain
173 any values ``ast.literal_eval`` supports.
174 
175 If the type has nested types like ``frozenset[int]``, items are converted
176 to those types automatically. This in new in Robot Framework 6.0.
177 
178 Examples: ``{1, 2, 3, 42}``, ``set()`` (an empty set)
179 '''
180 }
181 
182 STANDARD_TYPE_DOCS[bytearray] = STANDARD_TYPE_DOCS[bytes]