robot.libraries package¶
Package hosting Robot Framework standard test libraries.
Libraries are mainly used externally in the test data, but they can be
also used by custom test libraries if there is a need. Especially
the BuiltIn
library is often useful
when there is a need to interact with the framework.
Because libraries are documented using Robot Framework’s own documentation syntax, the generated API docs are not that well formed. It is thus better to find the generated library documentations, for example, via the http://robotframework.org web site.
Submodules¶
robot.libraries.BuiltIn module¶
-
class
robot.libraries.BuiltIn.
BuiltIn
[source]¶ Bases:
robot.libraries.BuiltIn._Verify
,robot.libraries.BuiltIn._Converter
,robot.libraries.BuiltIn._Variables
,robot.libraries.BuiltIn._RunKeyword
,robot.libraries.BuiltIn._Control
,robot.libraries.BuiltIn._Misc
An always available standard library with often needed keywords.
BuiltIn
is Robot Framework’s standard library that provides a set of generic keywords needed often. It is imported automatically and thus always available. The provided keywords can be used, for example, for verifications (e.g. Should Be Equal, Should Contain), conversions (e.g. Convert To Integer) and for various other purposes (e.g. Log, Sleep, Run Keyword If, Set Global Variable).== Table of contents ==
%TOC%
= HTML error messages =
Many of the keywords accept an optional error message to use if the keyword fails, and it is possible to use HTML in these messages by prefixing them with
*HTML*
. See Fail keyword for a usage example. Notice that using HTML in messages is not limited to BuiltIn library but works with any error message.= Using variables with keywords creating or accessing variables =
This library has special keywords Set Global Variable, Set Suite Variable, Set Test Variable and Set Local Variable for creating variables in different scopes. These keywords take the variable name and its value as arguments. The name can be given using the normal
${variable}
syntax or in escaped format either like$variable
or\${variable}
. For example, these are typically equivalent and create new suite level variable${name}
with valuevalue
:A problem with using the normal
${variable}
syntax is that these keywords cannot easily know is the idea to create a variable with exactly that name or does that variable actually contain the name of the variable to create. If the variable does not initially exist, it will always be created. If it exists and its value is a variable name either in the normal or in the escaped syntax, variable with _that_ name is created instead. For example, if${name}
variable would exist and contain value$example
, these examples would create different variables:Because the behavior when using the normal
${variable}
syntax depends on the possible existing value of the variable, it is highly recommended to use the escaped ``$variable`` or ``${variable}`` format instead.This same problem occurs also with special keywords for accessing variables Get Variable Value, Variable Should Exist and Variable Should Not Exist.
= Evaluating expressions =
Many keywords, such as Evaluate, Run Keyword If and Should Be True, accept an expression that is evaluated in Python.
== Evaluation namespace ==
Expressions are evaluated using Python’s [http://docs.python.org/library/functions.html#eval|eval] function so that all Python built-ins like
len()
andint()
are available. In addition to that, all unrecognized variables are considered to be modules that are automatically imported. It is possible to use all available Python modules, including the standard modules and the installed third party modules.Evaluate also allows configuring the execution namespace with a custom namespace and with custom modules to be imported. The latter functionality is useful in special cases where the automatic module import does not work such as when using nested modules like
rootmod.submod
or list comprehensions. See the documentation of the Evaluate keyword for mode details.== Variables in expressions ==
When a variable is used in the expressing using the normal
${variable}
syntax, its value is replaced before the expression is evaluated. This means that the value used in the expression will be the string representation of the variable value, not the variable value itself. This is not a problem with numbers and other objects that have a string representation that can be evaluated directly, but with other objects the behavior depends on the string representation. Most importantly, strings must always be quoted, and if they can contain newlines, they must be triple quoted.Actual variables values are also available in the evaluation namespace. They can be accessed using special variable syntax without the curly braces like
$variable
. These variables should never be quoted.Using the
$variable
syntax slows down expression evaluation a little. This should not typically matter, but should be taken into account if complex expressions are evaluated often and there are strict time constrains.Notice that instead of creating complicated expressions, it is often better to move the logic into a library. That eases maintenance and can also enhance execution speed.
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Keywords verifying something that allow dropping actual and expected values from the possible error message also consider stringno values
to be false. Other strings are considered true unless the keyword documentation explicitly states otherwise, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
= Pattern matching =
Many keywords accept arguments as either glob or regular expression patterns.
== Glob patterns ==
Some keywords, for example Should Match, support so called [http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where:
Unlike with glob patterns normally, path separator characters
/
and\
and the newline character\n
are matches by the above wildcards.== Regular expressions ==
Some keywords, for example Should Match Regexp, support [http://en.wikipedia.org/wiki/Regular_expression|regular expressions] that are more powerful but also more complicated that glob patterns. The regular expression support is implemented using Python’s [http://docs.python.org/library/re.html|re module] and its documentation should be consulted for more information about the syntax.
Because the backslash character (
\
) is an escape character in Robot Framework test data, possible backslash characters in regular expressions need to be escaped with another backslash like\\d\\w+
. Strings that may contain special characters but should be handled as literal strings, can be escaped with the Regexp Escape keyword.= Multiline string comparison =
Should Be Equal and Should Be Equal As Strings report the failures using [http://en.wikipedia.org/wiki/Diff_utility#Unified_format|unified diff format] if both strings have more than two lines.
Results in the following error message:
= String representations =
Several keywords log values explicitly (e.g. Log) or implicitly (e.g. Should Be Equal when there are failures). By default, keywords log values using human-readable string representation, which means that strings like
Hello
and numbers like42
are logged as-is. Most of the time this is the desired behavior, but there are some problems as well:- It is not possible to see difference between different objects that
have the same string representation like string
42
and integer42
. Should Be Equal and some other keywords add the type information to the error message in these cases, though. - Non-printable characters such as the null byte are not visible.
- Trailing whitespace is not visible.
- Different newlines (
\r\n
on Windows,\n
elsewhere) cannot be separated from each others. - There are several Unicode characters that are different but look the
same. One example is the Latin
a
(\u0061
) and the Cyrillicа
(\u0430
). Error messages likea != а
are not very helpful. - Some Unicode characters can be represented using
[https://en.wikipedia.org/wiki/Unicode_equivalence|different forms].
For example,
ä
can be represented either as a single code point\u00e4
or using two combined code points\u0061
and\u0308
. Such forms are considered canonically equivalent, but strings containing them are not considered equal when compared in Python. Error messages likeä != ä
are not that helpful either. - Containers such as lists and dictionaries are formatted into a single line making it hard to see individual items they contain.
To overcome the above problems, some keywords such as Log and Should Be Equal have an optional
formatter
argument that can be used to configure the string representation. The supported values arestr
(default),repr
, andascii
that work similarly as [https://docs.python.org/library/functions.html|Python built-in functions] with same names. More detailed semantics are explained below.== str ==
Use the human-readable string representation. Equivalent to using
str()
in Python. This is the default.== repr ==
Use the machine-readable string representation. Similar to using
repr()
in Python, which means that strings likeHello
are logged like'Hello'
, newlines and non-printable characters are escaped like\n
and\x00
, and so on. Non-ASCII characters are shown as-is likeä
.In this mode bigger lists, dictionaries and other containers are pretty-printed so that there is one item per row.
== ascii ==
Same as using
ascii()
in Python. Similar to usingrepr
explained above but with the following differences:- Non-ASCII characters are escaped like
\xe4
instead of showing them as-is likeä
. This makes it easier to see differences between Unicode characters that look the same but are not equal. - Containers are not pretty-printed.
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
call_method
(object, method_name, *args, **kwargs)¶ Calls the named method of the given object with the provided arguments.
The possible return value from the method is returned and can be assigned to a variable. Keyword fails both if the object does not have a method with the given name or if executing the method raises an exception.
Possible equal signs in arguments must be escaped with a backslash like
\=
.
-
catenate
(*items)¶ Catenates the given items together and returns the resulted string.
By default, items are catenated with spaces, but if the first item contains the string
SEPARATOR=<sep>
, the separator<sep>
is used instead. Items are converted into strings when necessary.
-
comment
(*messages)¶ Displays the given messages in the log file as keyword arguments.
This keyword does nothing with the arguments it receives, but as they are visible in the log, this keyword can be used to display simple messages. Given arguments are ignored so thoroughly that they can even contain non-existing variables. If you are interested about variable values, you can use the Log or Log Many keywords.
-
continue_for_loop
()¶ Skips the current FOR loop iteration and continues from the next.
—
NOTE: Robot Framework 5.0 added support for native
CONTINUE
statement that is recommended over this keyword. In the examples below,Continue For Loop
can simply be replaced withCONTINUE
. In addition to that, nativeIF
syntax (new in RF 4.0) or inlineIF
syntax (new in RF 5.0) can be used instead ofRun Keyword If
. For example, the first example below could be written like this instead:This keyword will eventually be deprecated and removed.
—
Skips the remaining keywords in the current FOR loop iteration and continues from the next one. Starting from Robot Framework 5.0, this keyword can only be used inside a loop, not in a keyword used in a loop.
See Continue For Loop If to conditionally continue a FOR loop without using Run Keyword If or other wrapper keywords.
-
continue_for_loop_if
(condition)¶ Skips the current FOR loop iteration if the
condition
is true.—
NOTE: Robot Framework 5.0 added support for native
CONTINUE
statement and for inlineIF
, and that combination should be used instead of this keyword. For example,Continue For Loop If
usage in the example below could be replaced withThis keyword will eventually be deprecated and removed.
—
A wrapper for Continue For Loop to continue a FOR loop based on the given condition. The condition is evaluated using the same semantics as with Should Be True keyword.
-
convert_to_binary
(item, base=None, prefix=None, length=None)¶ Converts the given item to a binary string.
The
item
, with an optionalbase
, is first converted to an integer using Convert To Integer internally. After that it is converted to a binary number (base 2) represented as a string such as1011
.The returned value can contain an optional
prefix
and can be required to be of minimumlength
(excluding the prefix and a possible minus sign). If the value is initially shorter than the required length, it is padded with zeros.See also Convert To Integer, Convert To Octal and Convert To Hex.
-
convert_to_boolean
(item)¶ Converts the given item to Boolean true or false.
Handles strings
True
andFalse
(case-insensitive) as expected, otherwise returns item’s [http://docs.python.org/library/stdtypes.html#truth|truth value] using Python’sbool()
method.
-
convert_to_bytes
(input, input_type='text')¶ Converts the given
input
to bytes according to theinput_type
.Valid input types are listed below:
text:
Converts text to bytes character by character. All characters with ordinal below 256 can be used and are converted to bytes with same values. Many characters are easiest to represent using escapes like\x00
or\xff
. Supports both Unicode strings and bytes.int:
Converts integers separated by spaces to bytes. Similarly as with Convert To Integer, it is possible to use binary, octal, or hex values by prefixing the values with0b
,0o
, or0x
, respectively.hex:
Converts hexadecimal values to bytes. Single byte is always two characters long (e.g.01
orFF
). Spaces are ignored and can be used freely as a visual separator.bin:
Converts binary values to bytes. Single byte is always eight characters long (e.g.00001010
). Spaces are ignored and can be used freely as a visual separator.
In addition to giving the input as a string, it is possible to use lists or other iterables containing individual characters or numbers. In that case numbers do not need to be padded to certain length and they cannot contain extra spaces.
Use Encode String To Bytes in
String
library if you need to convert text to bytes using a certain encoding.
-
convert_to_hex
(item, base=None, prefix=None, length=None, lowercase=False)¶ Converts the given item to a hexadecimal string.
The
item
, with an optionalbase
, is first converted to an integer using Convert To Integer internally. After that it is converted to a hexadecimal number (base 16) represented as a string such asFF0A
.The returned value can contain an optional
prefix
and can be required to be of minimumlength
(excluding the prefix and a possible minus sign). If the value is initially shorter than the required length, it is padded with zeros.By default the value is returned as an upper case string, but the
lowercase
argument a true value (see Boolean arguments) turns the value (but not the given prefix) to lower case.See also Convert To Integer, Convert To Binary and Convert To Octal.
-
convert_to_integer
(item, base=None)¶ Converts the given item to an integer number.
If the given item is a string, it is by default expected to be an integer in base 10. There are two ways to convert from other bases:
- Give base explicitly to the keyword as
base
argument. - Prefix the given string with the base so that
0b
means binary (base 2),0o
means octal (base 8), and0x
means hex (base 16). The prefix is considered only whenbase
argument is not given and may itself be prefixed with a plus or minus sign.
The syntax is case-insensitive and possible spaces are ignored.
See also Convert To Number, Convert To Binary, Convert To Octal, Convert To Hex, and Convert To Bytes.
- Give base explicitly to the keyword as
-
convert_to_number
(item, precision=None)¶ Converts the given item to a floating point number.
If the optional
precision
is positive or zero, the returned number is rounded to that number of decimal digits. Negative precision means that the number is rounded to the closest multiple of 10 to the power of the absolute precision. If a number is equally close to a certain precision, it is always rounded away from zero.Notice that machines generally cannot store floating point numbers accurately. This may cause surprises with these numbers in general and also when they are rounded. For more information see, for example, these resources:
- http://docs.python.org/tutorial/floatingpoint.html
- http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition
If you want to avoid possible problems with floating point numbers, you can implement custom keywords using Python’s [http://docs.python.org/library/decimal.html|decimal] or [http://docs.python.org/library/fractions.html|fractions] modules.
If you need an integer number, use Convert To Integer instead.
-
convert_to_octal
(item, base=None, prefix=None, length=None)¶ Converts the given item to an octal string.
The
item
, with an optionalbase
, is first converted to an integer using Convert To Integer internally. After that it is converted to an octal number (base 8) represented as a string such as775
.The returned value can contain an optional
prefix
and can be required to be of minimumlength
(excluding the prefix and a possible minus sign). If the value is initially shorter than the required length, it is padded with zeros.See also Convert To Integer, Convert To Binary and Convert To Hex.
-
convert_to_string
(item)¶ Converts the given item to a Unicode string.
Strings are also [https://en.wikipedia.org/wiki/Unicode_equivalence| NFC normalized].
Use Encode String To Bytes and Decode Bytes To String keywords in
String
library if you need to convert between Unicode and byte strings using different encodings. Use Convert To Bytes if you just want to create byte strings.
-
create_dictionary
(*items)¶ Creates and returns a dictionary based on the given
items
.Items are typically given using the
key=value
syntax same way as&{dictionary}
variables are created in the Variable table. Both keys and values can contain variables, and possible equal sign in key can be escaped with a backslash likeescaped\=key=value
. It is also possible to get items from existing dictionaries by simply using them like&{dict}
.Alternatively items can be specified so that keys and values are given separately. This and the
key=value
syntax can even be combined, but separately given items must be first. If same key is used multiple times, the last value has precedence.The returned dictionary is ordered, and values with strings as keys can also be accessed using a convenient dot-access syntax like
${dict.key}
. Technically the returned dictionary is Robot Framework’s ownDotDict
instance. If there is a need, it can be converted into a regular Pythondict
instance by using the Convert To Dictionary keyword from the Collections library.
-
create_list
(*items)¶ Returns a list containing given items.
The returned list can be assigned both to
${scalar}
and@{list}
variables.
-
dry_run_active
¶ Return True/False depending on is dry-run active or not.
Can be used by libraries and other extensions. Notice that library keywords are not run at all in dry-run, but library
__init__
can utilize this information.New in Robot Framework 6.1.
-
evaluate
(expression, modules=None, namespace=None)¶ Evaluates the given expression in Python and returns the result.
expression
is evaluated in Python as explained in the Evaluating expressions section.modules
argument can be used to specify a comma separated list of Python modules to be imported and added to the evaluation namespace.namespace
argument can be used to pass a custom evaluation namespace as a dictionary. Possiblemodules
are added to this namespace.Variables used like
${variable}
are replaced in the expression before evaluation. Variables are also available in the evaluation namespace and can be accessed using the special$variable
syntax as explained in the Evaluating expressions section.Starting from Robot Framework 3.2, modules used in the expression are imported automatically. There are, however, two cases where they need to be explicitly specified using the
modules
argument:- When nested modules like
rootmod.submod
are implemented so that the root module does not automatically import sub modules. This is illustrated by theselenium.webdriver
example below. - When using a module in the expression part of a list comprehension.
This is illustrated by the
json
example below.
NOTE: Prior to Robot Framework 3.2 using
modules=rootmod.submod
was not enough to make the root module itself available in the evaluation namespace. It needed to be taken into use explicitly likemodules=rootmod, rootmod.submod
.- When nested modules like
-
exit_for_loop
()¶ Stops executing the enclosing FOR loop.
—
NOTE: Robot Framework 5.0 added support for native
BREAK
statement that is recommended over this keyword. In the examples below,Exit For Loop
can simply be replaced withBREAK
. In addition to that, nativeIF
syntax (new in RF 4.0) or inlineIF
syntax (new in RF 5.0) can be used instead ofRun Keyword If
. For example, the first example below could be written like this instead:This keyword will eventually be deprecated and removed.
—
Exits the enclosing FOR loop and continues execution after it. Starting from Robot Framework 5.0, this keyword can only be used inside a loop, not in a keyword used in a loop.
See Exit For Loop If to conditionally exit a FOR loop without using Run Keyword If or other wrapper keywords.
-
exit_for_loop_if
(condition)¶ Stops executing the enclosing FOR loop if the
condition
is true.—
NOTE: Robot Framework 5.0 added support for native
BREAK
statement and for inlineIF
, and that combination should be used instead of this keyword. For example,Exit For Loop If
usage in the example below could be replaced withThis keyword will eventually be deprecated and removed.
—
A wrapper for Exit For Loop to exit a FOR loop based on the given condition. The condition is evaluated using the same semantics as with Should Be True keyword.
-
fail
(msg=None, *tags)¶ Fails the test with the given message and optionally alters its tags.
The error message is specified using the
msg
argument. It is possible to use HTML in the given error message, similarly as with any other keyword accepting an error message, by prefixing the error with*HTML*
.It is possible to modify tags of the current test case by passing tags after the message. Tags starting with a hyphen (e.g.
-regression
) are removed and others added. Tags are modified using Set Tags and Remove Tags internally, and the semantics setting and removing them are the same as with these keywords.See Fatal Error if you need to stop the whole test execution.
-
fatal_error
(msg=None)¶ Stops the whole test execution.
The test or suite where this keyword is used fails with the provided message, and subsequent tests fail with a canned message. Possible teardowns will nevertheless be executed.
See Fail if you only want to stop one test case unconditionally.
-
get_count
(container, item)¶ Returns and logs how many times
item
is found fromcontainer
.This keyword works with Python strings and lists and all objects that either have
count
method or can be converted to Python lists.
-
get_length
(item)¶ Returns and logs the length of the given item as an integer.
The item can be anything that has a length, for example, a string, a list, or a mapping. The keyword first tries to get the length with the Python function
len
, which calls the item’s__len__
method internally. If that fails, the keyword tries to call the item’s possiblelength
andsize
methods directly. The final attempt is trying to get the value of the item’slength
attribute. If all these attempts are unsuccessful, the keyword fails.See also Length Should Be, Should Be Empty and Should Not Be Empty.
-
get_library_instance
(name=None, all=False)¶ Returns the currently active instance of the specified library.
This keyword makes it easy for libraries to interact with other libraries that have state. This is illustrated by the Python example below:
It is also possible to use this keyword in the test data and pass the returned library instance to another keyword. If a library is imported with a custom name, the
name
used to get the instance must be that name and not the original library name.If the optional argument
all
is given a true value, then a dictionary mapping all library names to instances will be returned.
-
get_time
(format='timestamp', time_='NOW')¶ Returns the given time in the requested format.
NOTE: DateTime library contains much more flexible keywords for getting the current date and time and for date and time handling in general.
How time is returned is determined based on the given
format
string as follows. Note that all checks are case-insensitive.- If
format
contains the wordepoch
, the time is returned in seconds after the UNIX epoch (1970-01-01 00:00:00 UTC). The return value is always an integer. - If
format
contains any of the wordsyear
,month
,day
,hour
,min
, orsec
, only the selected parts are returned. The order of the returned parts is always the one in the previous sentence and the order of words informat
is not significant. The parts are returned as zero-padded strings (e.g. May ->05
). - Otherwise (and by default) the time is returned as a
timestamp string in the format
2006-02-24 15:08:31
.
By default this keyword returns the current local time, but that can be altered using
time
argument as explained below. Note that all checks involving strings are case-insensitive.- If
time
is a number, or a string that can be converted to a number, it is interpreted as seconds since the UNIX epoch. This documentation was originally written about 1177654467 seconds after the epoch. - If
time
is a timestamp, that time will be used. Valid timestamp formats areYYYY-MM-DD hh:mm:ss
andYYYYMMDD hhmmss
. - If
time
is equal toNOW
(default), the current local time is used. - If
time
is equal toUTC
, the current time in [http://en.wikipedia.org/wiki/Coordinated_Universal_Time|UTC] is used. - If
time
is in the format likeNOW - 1 day
orUTC + 1 hour 30 min
, the current local/UTC time plus/minus the time specified with the time string is used. The time string format is described in an appendix of Robot Framework User Guide.
UTC time is 2006-03-29 12:06:21):
- If
-
get_variable_value
(name, default=None)¶ Returns variable value or
default
if the variable does not exist.The name of the variable can be given either as a normal variable name like
${name}
or in escaped format like$name
or\${name}
. For the reasons explained in the Using variables with keywords creating or accessing variables section, using the escaped format is recommended.${x}
gets value of${a}
if${a}
exists and stringdefault
otherwise${y}
gets value of${a}
if${a}
exists and value of${b}
otherwise${z}
is set to PythonNone
if it does not exist previously
-
get_variables
(no_decoration=False)¶ Returns a dictionary containing all variables in the current scope.
Variables are returned as a special dictionary that allows accessing variables in space, case, and underscore insensitive manner similarly as accessing variables in the test data. This dictionary supports all same operations as normal Python dictionaries and, for example, Collections library can be used to access or modify it. Modifying the returned dictionary has no effect on the variables available in the current scope.
By default variables are returned with
${}
,@{}
or&{}
decoration based on variable types. Giving a true value (see Boolean arguments) to the optional argumentno_decoration
will return the variables without the decoration.
-
import_library
(name, *args)¶ Imports a library with the given name and optional arguments.
This functionality allows dynamic importing of libraries while tests are running. That may be necessary, if the library itself is dynamic and not yet available when test data is processed. In a normal case, libraries should be imported using the Library setting in the Setting section.
This keyword supports importing libraries both using library names and physical paths. When paths are used, they must be given in absolute format or found from [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path| search path]. Forward slashes can be used as path separators in all operating systems.
It is possible to pass arguments to the imported library and also named argument syntax works if the library supports it.
WITH NAME
syntax can be used to give a custom name to the imported library.
-
import_resource
(path)¶ Imports a resource file with the given path.
Resources imported with this keyword are set into the test suite scope similarly when importing them in the Setting table using the Resource setting.
The given path must be absolute or found from [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#module-search-path|search path]. Forward slashes can be used as path separator regardless the operating system.
-
import_variables
(path, *args)¶ Imports a variable file with the given path and optional arguments.
Variables imported with this keyword are set into the test suite scope similarly when importing them in the Setting table using the Variables setting. These variables override possible existing variables with the same names. This functionality can thus be used to import new variables, for example, for each test in a test suite.
The given path must be absolute or found from [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html##module-search-path|search path]. Forward slashes can be used as path separator regardless the operating system.
-
keyword_should_exist
(name, msg=None)¶ Fails unless the given keyword exists in the current scope.
Fails also if there is more than one keyword with the same name. Works both with the short name (e.g.
Log
) and the full name (e.g.BuiltIn.Log
).The default error message can be overridden with the
msg
argument.See also Variable Should Exist.
-
length_should_be
(item, length, msg=None)¶ Verifies that the length of the given item is correct.
The length of the item is got using the Get Length keyword. The default error message can be overridden with the
msg
argument.
-
log
(message, level='INFO', html=False, console=False, repr='DEPRECATED', formatter='str')¶ Logs the given message with the given level.
Valid levels are TRACE, DEBUG, INFO (default), WARN and ERROR. In addition to that, there are pseudo log levels HTML and CONSOLE that both log messages using INFO.
Messages below the current active log level are ignored. See Set Log Level keyword and
--loglevel
command line option for more details about setting the level.Messages logged with the WARN or ERROR levels are automatically visible also in the console and in the Test Execution Errors section in the log file.
If the
html
argument is given a true value (see Boolean arguments) or the HTML pseudo log level is used, the message is considered to be HTML and special characters such as<
are not escaped. For example, logging<img src="image.png">
creates an image in this case, but otherwise the message is that exact string. When using the HTML pseudo level, the messages is logged using the INFO level.If the
console
argument is true or the CONSOLE pseudo level is used, the message is written both to the console and to the log file. When using the CONSOLE pseudo level, the message is logged using the INFO level. If the message should not be logged to the log file or there are special formatting needs, use the Log To Console keyword instead.The
formatter
argument controls how to format the string representation of the message. Possible values arestr
(default),repr
,ascii
,len
, andtype
. They work similarly to Python built-in functions with same names. When usingrepr
, bigger lists, dictionaries and other containers are also pretty-printed so that there is one item per row. For more details see String representations.The old way to control string representation was using the
repr
argument. This argument has been deprecated andformatter=repr
should be used instead.See Log Many if you want to log multiple messages in one go, and Log To Console if you only want to write to the console.
Formatter options
type
andlen
are new in Robot Framework 5.0. The CONSOLE level is new in Robot Framework 6.1.
-
log_many
(*messages)¶ Logs the given messages as separate entries using the INFO level.
Supports also logging list and dictionary variable items individually.
See Log and Log To Console keywords if you want to use alternative log levels, use HTML, or log to the console.
-
log_to_console
(message, stream='STDOUT', no_newline=False, format='')¶ Logs the given message to the console.
By default uses the standard output stream. Using the standard error stream is possible by giving the
stream
argument valueSTDERR
(case-insensitive).By default appends a newline to the logged message. This can be disabled by giving the
no_newline
argument a true value (see Boolean arguments).By default adds no alignment formatting. The
format
argument allows, for example, alignment and customized padding of the log message. Please see the [https://docs.python.org/3/library/string.html#formatspec|format specification] for detailed alignment possibilities. This argument is new in Robot Framework 5.0.This keyword does not log the message to the normal log file. Use Log keyword, possibly with argument
console
, if that is desired.
-
log_variables
(level='INFO')¶ Logs all variables in the current scope with given log level.
-
no_operation
()¶ Does absolutely nothing.
-
pass_execution
(message, *tags)¶ Skips rest of the current test, setup, or teardown with PASS status.
This keyword can be used anywhere in the test data, but the place where used affects the behavior:
- When used in any setup or teardown (suite, test or keyword), passes that setup or teardown. Possible keyword teardowns of the started keywords are executed. Does not affect execution or statuses otherwise.
- When used in a test outside setup or teardown, passes that particular test case. Possible test and keyword teardowns are executed.
Possible continuable failures before this keyword is used, as well as failures in executed teardowns, will fail the execution.
It is mandatory to give a message explaining why execution was passed. By default the message is considered plain text, but starting it with
*HTML*
allows using HTML formatting.It is also possible to modify test tags passing tags after the message similarly as with Fail keyword. Tags starting with a hyphen (e.g.
-regression
) are removed and others added. Tags are modified using Set Tags and Remove Tags internally, and the semantics setting and removing them are the same as with these keywords.This keyword is typically wrapped to some other keyword, such as Run Keyword If, to pass based on a condition. The most common case can be handled also with Pass Execution If:
Passing execution in the middle of a test, setup or teardown should be used with care. In the worst case it leads to tests that skip all the parts that could actually uncover problems in the tested application. In cases where execution cannot continue do to external factors, it is often safer to fail the test case and make it non-critical.
-
pass_execution_if
(condition, message, *tags)¶ Conditionally skips rest of the current test, setup, or teardown with PASS status.
A wrapper for Pass Execution to skip rest of the current test, setup or teardown based the given
condition
. The condition is evaluated similarly as with Should Be True keyword, andmessage
and*tags
have same semantics as with Pass Execution.
-
regexp_escape
(*patterns)¶ Returns each argument string escaped for use as a regular expression.
This keyword can be used to escape strings to be used with Should Match Regexp and Should Not Match Regexp keywords.
Escaping is done with Python’s
re.escape()
function.
-
reload_library
(name_or_instance)¶ Rechecks what keywords the specified library provides.
Can be called explicitly in the test data or by a library itself when keywords it provides have changed.
The library can be specified by its name or as the active instance of the library. The latter is especially useful if the library itself calls this keyword as a method.
Removes given
tags
from the current test or all tests in a suite.Tags can be given exactly or using a pattern with
*
,?
and[chars]
acting as wildcards. See the Glob patterns section for more information.This keyword can affect either one test case or all test cases in a test suite similarly as Set Tags keyword.
The current tags are available as a built-in variable
@{TEST TAGS}
.See Set Tags if you want to add certain tags and Fail if you want to fail the test case after setting and/or removing tags.
-
repeat_keyword
(repeat, name, *args)¶ Executes the specified keyword multiple times.
name
andargs
define the keyword that is executed similarly as with Run Keyword.repeat
specifies how many times (as a count) or how long time (as a timeout) the keyword should be executed.If
repeat
is given as count, it specifies how many times the keyword should be executed.repeat
can be given as an integer or as a string that can be converted to an integer. If it is a string, it can have postfixtimes
orx
(case and space insensitive) to make the expression more explicit.If
repeat
is given as timeout, it must be in Robot Framework’s time format (e.g.1 minute
,2 min 3 s
). Using a number alone (e.g.1
or1.5
) does not work in this context.If
repeat
is zero or negative, the keyword is not executed at all. This keyword fails immediately if any of the execution rounds fails.
-
replace_variables
(text)¶ Replaces variables in the given text with their current values.
If the text contains undefined variables, this keyword fails. If the given
text
contains only a single variable, its value is returned as-is and it can be any object. Otherwise this keyword always returns a string.The file
template.txt
containsHello ${NAME}!
and variable${NAME}
has the valueRobot
.
-
return_from_keyword
(*return_values)¶ Returns from the enclosing user keyword.
—
NOTE: Robot Framework 5.0 added support for native
RETURN
statement that is recommended over this keyword. In the examples below,Return From Keyword
can simply be replaced withRETURN
. In addition to that, nativeIF
syntax (new in RF 4.0) or inlineIF
syntax (new in RF 5.0) can be used instead ofRun Keyword If
. For example, the first example below could be written like this instead:This keyword will eventually be deprecated and removed.
—
This keyword can be used to return from a user keyword with PASS status without executing it fully. It is also possible to return values similarly as with the
[Return]
setting. For more detailed information about working with the return values, see the User Guide.This keyword is typically wrapped to some other keyword, such as Run Keyword If, to return based on a condition:
It is possible to use this keyword to return from a keyword also inside a for loop. That, as well as returning values, is demonstrated by the Find Index keyword in the following somewhat advanced example. Notice that it is often a good idea to move this kind of complicated logic into a library.
The most common use case, returning based on an expression, can be accomplished directly with Return From Keyword If. See also Run Keyword And Return and Run Keyword And Return If.
-
return_from_keyword_if
(condition, *return_values)¶ Returns from the enclosing user keyword if
condition
is true.—
NOTE: Robot Framework 5.0 added support for native
RETURN
statement and for inlineIF
, and that combination should be used instead of this keyword. For example,Return From Keyword
usage in the example below could be replaced withThis keyword will eventually be deprecated and removed.
—
A wrapper for Return From Keyword to return based on the given condition. The condition is evaluated using the same semantics as with Should Be True keyword.
Given the same example as in Return From Keyword, we can rewrite the Find Index keyword as follows:
See also Run Keyword And Return and Run Keyword And Return If.
-
robot_running
¶ Return True/False depending on is Robot Framework running or not.
Can be used by libraries and other extensions.
New in Robot Framework 6.1.
-
run_keyword
(name, *args)¶ Executes the given keyword with the given arguments.
Because the name of the keyword to execute is given as an argument, it can be a variable and thus set dynamically, e.g. from a return value of another keyword or from the command line.
-
run_keyword_and_continue_on_failure
(name, *args)¶ Runs the keyword and continues execution even if a failure occurs.
The keyword name and arguments work as with Run Keyword.
The execution is not continued if the failure is caused by invalid syntax, timeout, or fatal exception.
-
run_keyword_and_expect_error
(expected_error, name, *args)¶ Runs the keyword and checks that the expected error occurred.
The keyword to execute and its arguments are specified using
name
and*args
exactly like with Run Keyword.The expected error must be given in the same format as in Robot Framework reports. By default it is interpreted as a glob pattern with
*
,?
and[chars]
as wildcards, but that can be changed by using various prefixes explained in the table below. Prefixes are case-sensitive and they must be separated from the actual message with a colon and an optional space likePREFIX: Message
orPREFIX:Message
.See the Pattern matching section for more information about glob patterns and regular expressions.
If the expected error occurs, the error message is returned and it can be further processed or tested if needed. If there is no error, or the error does not match the expected error, this keyword fails.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword.
NOTE: Regular expression matching used to require only the beginning of the error to match the given pattern. That was changed in Robot Framework 5.0 and nowadays the pattern must match the error fully. To match only the beginning, add
.*
at the end of the pattern likeREGEXP: Start.*
.NOTE: Robot Framework 5.0 introduced native TRY/EXCEPT functionality that is generally recommended for error handling. It supports same pattern matching syntax as this keyword.
-
run_keyword_and_ignore_error
(name, *args)¶ Runs the given keyword with the given arguments and ignores possible error.
This keyword returns two values, so that the first is either string
PASS
orFAIL
, depending on the status of the executed keyword. The second value is either the return value of the keyword or the received error message. See Run Keyword And Return Status If you are only interested in the execution status.The keyword name and arguments work as in Run Keyword. See Run Keyword If for a usage example.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword. Otherwise this keyword itself never fails.
NOTE: Robot Framework 5.0 introduced native TRY/EXCEPT functionality that is generally recommended for error handling.
-
run_keyword_and_return
(name, *args)¶ Runs the specified keyword and returns from the enclosing user keyword.
The keyword to execute is defined with
name
and*args
exactly like with Run Keyword. After running the keyword, returns from the enclosing user keyword and passes possible return value from the executed keyword further. Returning from a keyword has exactly same semantics as with Return From Keyword.Use Run Keyword And Return If if you want to run keyword and return based on a condition.
-
run_keyword_and_return_if
(condition, name, *args)¶ Runs the specified keyword and returns from the enclosing user keyword.
A wrapper for Run Keyword And Return to run and return based on the given
condition
. The condition is evaluated using the same semantics as with Should Be True keyword.Use Return From Keyword If if you want to return a certain value based on a condition.
-
run_keyword_and_return_status
(name, *args)¶ Runs the given keyword with given arguments and returns the status as a Boolean value.
This keyword returns Boolean
True
if the keyword that is executed succeeds andFalse
if it fails. This is useful, for example, in combination with Run Keyword If. If you are interested in the error message or return value, use Run Keyword And Ignore Error instead.The keyword name and arguments work as in Run Keyword.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword. Otherwise this keyword itself never fails.
-
run_keyword_and_warn_on_failure
(name, *args)¶ Runs the specified keyword logs a warning if the keyword fails.
This keyword is similar to Run Keyword And Ignore Error but if the executed keyword fails, the error message is logged as a warning to make it more visible. Returns status and possible return value or error message exactly like Run Keyword And Ignore Error does.
Errors caused by invalid syntax, timeouts, or fatal exceptions are not caught by this keyword. Otherwise this keyword itself never fails.
New in Robot Framework 4.0.
-
run_keyword_if
(condition, name, *args)¶ Runs the given keyword with the given arguments, if
condition
is true.NOTE: Robot Framework 4.0 introduced built-in IF/ELSE support and using that is generally recommended over using this keyword.
The given
condition
is evaluated in Python as explained in the Evaluating expressions section, andname
and*args
have same semantics as with Run Keyword.In this example, only either
Some Action
orAnother Action
is executed, based on the value of the${status}
variable.Variables used like
${variable}
, as in the examples above, are replaced in the expression before evaluation. Variables are also available in the evaluation namespace and can be accessed using special$variable
syntax as explained in the Evaluating expressions section.This keyword supports also optional ELSE and ELSE IF branches. Both of them are defined in
*args
and must use exactly formatELSE
orELSE IF
, respectively. ELSE branches must contain first the name of the keyword to execute and then its possible arguments. ELSE IF branches must first contain a condition, like the first argument to this keyword, and then the keyword to execute and its possible arguments. It is possible to have ELSE branch after ELSE IF and to have multiple ELSE IF branches. Nested Run Keyword If usage is not supported when using ELSE and/or ELSE IF branches.Given previous example, if/else construct can also be created like this:
The return value of this keyword is the return value of the actually executed keyword or Python
None
if no keyword was executed (i.e. ifcondition
was false). Hence, it is recommended to use ELSE and/or ELSE IF branches to conditionally assign return values from keyword to variables (see Set Variable If you need to set fixed values conditionally). This is illustrated by the example below:In this example, ${var2} will be set to
None
if ${condition} is false.Notice that
ELSE
andELSE IF
control words must be used explicitly and thus cannot come from variables. If you need to use literalELSE
andELSE IF
strings as arguments, you can escape them with a backslash like\ELSE
and\ELSE IF
.
-
run_keyword_if_all_tests_passed
(name, *args)¶ Runs the given keyword with the given arguments, if all tests passed.
This keyword can only be used in a suite teardown. Trying to use it anywhere else results in an error.
Otherwise, this keyword works exactly like Run Keyword, see its documentation for more details.
-
run_keyword_if_any_tests_failed
(name, *args)¶ Runs the given keyword with the given arguments, if one or more tests failed.
This keyword can only be used in a suite teardown. Trying to use it anywhere else results in an error.
Otherwise, this keyword works exactly like Run Keyword, see its documentation for more details.
-
run_keyword_if_test_failed
(name, *args)¶ Runs the given keyword with the given arguments, if the test failed.
This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error.
Otherwise, this keyword works exactly like Run Keyword, see its documentation for more details.
-
run_keyword_if_test_passed
(name, *args)¶ Runs the given keyword with the given arguments, if the test passed.
This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error.
Otherwise, this keyword works exactly like Run Keyword, see its documentation for more details.
-
run_keyword_if_timeout_occurred
(name, *args)¶ Runs the given keyword if either a test or a keyword timeout has occurred.
This keyword can only be used in a test teardown. Trying to use it anywhere else results in an error.
Otherwise, this keyword works exactly like Run Keyword, see its documentation for more details.
-
run_keyword_unless
(condition, name, *args)¶ DEPRECATED since RF 5.0. Use Native IF/ELSE or `Run Keyword If` instead.
Runs the given keyword with the given arguments if
condition
is false.See Run Keyword If for more information and an example. Notice that this keyword does not support ELSE or ELSE IF branches like Run Keyword If does.
-
run_keywords
(*keywords)¶ Executes all the given keywords in a sequence.
This keyword is mainly useful in setups and teardowns when they need to take care of multiple actions and creating a new higher level user keyword would be an overkill.
By default all arguments are expected to be keywords to be executed.
Keywords can also be run with arguments using upper case
AND
as a separator between keywords. The keywords are executed so that the first argument is the first keyword and proceeding arguments until the firstAND
are arguments to it. First argument after the firstAND
is the second keyword and proceeding arguments until the nextAND
are its arguments. And so on.Notice that the
AND
control argument must be used explicitly and cannot itself come from a variable. If you need to use literalAND
string as argument, you can either use variables or escape it with a backslash like\AND
.
-
set_global_variable
(name, *values)¶ Makes a variable available globally in all tests and suites.
Variables set with this keyword are globally available in all subsequent test suites, test cases and user keywords. Also variables created Variables sections are overridden. Variables assigned locally based on keyword return values or by using Set Suite Variable, Set Test Variable or Set Local Variable override these variables in that scope, but the global value is not changed in those cases.
In practice setting variables with this keyword has the same effect as using command line options
--variable
and--variablefile
. Because this keyword can change variables everywhere, it should be used with care.See Set Suite Variable for more information and usage examples. See also the Using variables with keywords creating or accessing variables section for information why it is recommended to give the variable name in escaped format like
$name
or\${name}
instead of the normal${name}
.
-
set_library_search_order
(*search_order)¶ Sets the resolution order to use when a name matches multiple keywords.
The library search order is used to resolve conflicts when a keyword name that is used matches multiple keyword implementations. The first library (or resource, see below) containing the keyword is selected and that keyword implementation used. If the keyword is not found from any library (or resource), execution fails the same way as when the search order is not set.
When this keyword is used, there is no need to use the long
LibraryName.Keyword Name
notation. For example, instead of havingyou can have
This keyword can be used also to set the order of keywords in different resource files. In this case resource names must be given without paths or extensions like:
NOTE: - The search order is valid only in the suite where this keyword is used. - Keywords in resources always have higher priority than
keywords in libraries regardless the search order.- The old order is returned and can be used to reset the search order later.
- Calling this keyword without arguments removes possible search order.
- Library and resource names in the search order are both case and space insensitive.
-
set_local_variable
(name, *values)¶ Makes a variable available everywhere within the local scope.
Variables set with this keyword are available within the local scope of the currently executed test case or in the local scope of the keyword in which they are defined. For example, if you set a variable in a user keyword, it is available only in that keyword. Other test cases or keywords will not see variables set with this keyword.
This keyword is equivalent to a normal variable assignment based on a keyword return value. For example,
are equivalent with
The main use case for this keyword is creating local variables in libraries.
See Set Suite Variable for more information and usage examples. See also the Using variables with keywords creating or accessing variables section for information why it is recommended to give the variable name in escaped format like
$name
or\${name}
instead of the normal${name}
.See also Set Global Variable and Set Test Variable.
-
set_log_level
(level)¶ Sets the log threshold to the specified level and returns the old level.
Messages below the level will not logged. The default logging level is INFO, but it can be overridden with the command line option
--loglevel
.The available levels: TRACE, DEBUG, INFO (default), WARN, ERROR and NONE (no logging).
-
set_suite_documentation
(doc, append=False, top=False)¶ Sets documentation for the current test suite.
By default the possible existing documentation is overwritten, but this can be changed using the optional
append
argument similarly as with Set Test Message keyword.This keyword sets the documentation of the current suite by default. If the optional
top
argument is given a true value (see Boolean arguments), the documentation of the top level suite is altered instead.The documentation of the current suite is available as a built-in variable
${SUITE DOCUMENTATION}
.
-
set_suite_metadata
(name, value, append=False, top=False)¶ Sets metadata for the current test suite.
By default possible existing metadata values are overwritten, but this can be changed using the optional
append
argument similarly as with Set Test Message keyword.This keyword sets the metadata of the current suite by default. If the optional
top
argument is given a true value (see Boolean arguments), the metadata of the top level suite is altered instead.The metadata of the current suite is available as a built-in variable
${SUITE METADATA}
in a Python dictionary. Notice that modifying this variable directly has no effect on the actual metadata the suite has.
-
set_suite_variable
(name, *values)¶ Makes a variable available everywhere within the scope of the current suite.
Variables set with this keyword are available everywhere within the scope of the currently executed test suite. Setting variables with this keyword thus has the same effect as creating them using the Variables section in the data file or importing them from variable files.
Possible child test suites do not see variables set with this keyword by default, but that can be controlled by using
children=<option>
as the last argument. If the specified<option>
is given a true value (see Boolean arguments), the variable is set also to the child suites. Parent and sibling suites will never see variables set with this keyword.The name of the variable can be given either as a normal variable name like
${NAME}
or in escaped format as\${NAME}
or$NAME
. For the reasons explained in the Using variables with keywords creating or accessing variables section, using the escaped format is highly recommended.Variable value can be specified using the same syntax as when variables are created in the Variables section. Same way as in that section, it is possible to create scalar values, lists and dictionaries. The type is got from the variable name prefix
$
,@
and&
, respectively.If a variable already exists within the new scope, its value will be overwritten. If a variable already exists within the current scope, the value can be left empty and the variable within the new scope gets the value within the current scope.
To override an existing value with an empty value, use built-in variables
${EMPTY}
,@{EMPTY}
or&{EMPTY}
:See also Set Global Variable, Set Test Variable and Set Local Variable.
Adds given
tags
for the current test or all tests in a suite.When this keyword is used inside a test case, that test gets the specified tags and other tests are not affected.
If this keyword is used in a suite setup, all test cases in that suite, recursively, gets the given tags. It is a failure to use this keyword in a suite teardown.
The current tags are available as a built-in variable
@{TEST TAGS}
.See Remove Tags if you want to remove certain tags and Fail if you want to fail the test case after setting and/or removing tags.
-
set_task_variable
(name, *values)¶ Makes a variable available everywhere within the scope of the current task.
This is an alias for Set Test Variable that is more applicable when creating tasks, not tests.
-
set_test_documentation
(doc, append=False)¶ Sets documentation for the current test case.
By default the possible existing documentation is overwritten, but this can be changed using the optional
append
argument similarly as with Set Test Message keyword.The current test documentation is available as a built-in variable
${TEST DOCUMENTATION}
. This keyword can not be used in suite setup or suite teardown.
-
set_test_message
(message, append=False)¶ Sets message for the current test case.
If the optional
append
argument is given a true value (see Boolean arguments), the givenmessage
is added after the possible earlier message by joining the messages with a space.In test teardown this keyword can alter the possible failure message, but otherwise failures override messages set by this keyword. Notice that in teardown the message is available as a built-in variable
${TEST MESSAGE}
.It is possible to use HTML format in the message by starting the message with
*HTML*
.This keyword can not be used in suite setup or suite teardown.
-
set_test_variable
(name, *values)¶ Makes a variable available everywhere within the scope of the current test.
Variables set with this keyword are available everywhere within the scope of the currently executed test case. For example, if you set a variable in a user keyword, it is available both in the test case level and also in all other user keywords used in the current test. Other test cases will not see variables set with this keyword. It is an error to call Set Test Variable outside the scope of a test (e.g. in a Suite Setup or Teardown).
See Set Suite Variable for more information and usage examples. See also the Using variables with keywords creating or accessing variables section for information why it is recommended to give the variable name in escaped format like
$name
or\${name}
instead of the normal${name}
.When creating automated tasks, not tests, it is possible to use Set Task Variable. See also Set Global Variable and Set Local Variable.
-
set_variable
(*values)¶ Returns the given values which can then be assigned to a variables.
This keyword is mainly used for setting scalar variables. Additionally it can be used for converting a scalar variable containing a list to a list variable or to multiple scalar variables. It is recommended to use Create List when creating new lists.
Variables created with this keyword are available only in the scope where they are created. See Set Global Variable, Set Test Variable and Set Suite Variable for information on how to set variables so that they are available also in a larger scope.
-
set_variable_if
(condition, *values)¶ Sets variable based on the given condition.
The basic usage is giving a condition and two values. The given condition is first evaluated the same way as with the Should Be True keyword. If the condition is true, then the first value is returned, and otherwise the second value is returned. The second value can also be omitted, in which case it has a default value None. This usage is illustrated in the examples below, where
${rc}
is assumed to be zero.It is also possible to have ‘else if’ support by replacing the second value with another condition, and having two new values after it. If the first condition is not true, the second is evaluated and one of the values after it is returned based on its truth value. This can be continued by adding more conditions without a limit.
Use Get Variable Value if you need to set variables dynamically based on whether a variable exist or not.
-
should_be_empty
(item, msg=None)¶ Verifies that the given item is empty.
The length of the item is got using the Get Length keyword. The default error message can be overridden with the
msg
argument.
-
should_be_equal
(first, second, msg=None, values=True, ignore_case=False, formatter='str', strip_spaces=False, collapse_spaces=False)¶ Fails if the given objects are unequal.
Optional
msg
,values
andformatter
arguments specify how to construct the error message if this keyword fails:- If
msg
is not given, the error message is<first> != <second>
. - If
msg
is given andvalues
gets a true value (default), the error message is<msg>: <first> != <second>
. - If
msg
is given andvalues
gets a false value (see Boolean arguments), the error message is simply<msg>
. formatter
controls how to format the values. Possible values arestr
(default),repr
andascii
, and they work similarly as Python built-in functions with same names. See String representations for more details.
If
ignore_case
is given a true value (see Boolean arguments) and both arguments are strings, comparison is done case-insensitively. If both arguments are multiline strings, this keyword uses multiline string comparison.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.- If
-
should_be_equal_as_integers
(first, second, msg=None, values=True, base=None)¶ Fails if objects are unequal after converting them to integers.
See Convert To Integer for information how to convert integers from other bases than 10 using
base
argument or0b/0o/0x
prefixes.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.
-
should_be_equal_as_numbers
(first, second, msg=None, values=True, precision=6)¶ Fails if objects are unequal after converting them to real numbers.
The conversion is done with Convert To Number keyword using the given
precision
.As discussed in the documentation of Convert To Number, machines generally cannot store floating point numbers accurately. Because of this limitation, comparing floats for equality is problematic and a correct approach to use depends on the context. This keyword uses a very naive approach of rounding the numbers before comparing them, which is both prone to rounding errors and does not work very well if numbers are really big or small. For more information about comparing floats, and ideas on how to implement your own context specific comparison algorithm, see http://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/.
If you want to avoid possible problems with floating point numbers, you can implement custom keywords using Python’s [http://docs.python.org/library/decimal.html|decimal] or [http://docs.python.org/library/fractions.html|fractions] modules.
See Should Not Be Equal As Numbers for a negative version of this keyword and Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.
-
should_be_equal_as_strings
(first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, formatter='str', collapse_spaces=False)¶ Fails if objects are unequal after converting them to strings.
See Should Be Equal for an explanation on how to override the default error message with
msg
,values
andformatter
.If
ignore_case
is given a true value (see Boolean arguments), comparison is done case-insensitively. If both arguments are multiline strings, this keyword uses multiline string comparison.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.Strings are always [https://en.wikipedia.org/wiki/Unicode_equivalence|NFC normalized].
strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_be_true
(condition, msg=None)¶ Fails if the given condition is not true.
If
condition
is a string (e.g.${rc} < 10
), it is evaluated as a Python expression as explained in Evaluating expressions and the keyword status is decided based on the result. If a non-string item is given, the status is got directly from its [http://docs.python.org/library/stdtypes.html#truth|truth value].The default error message (
<condition> should be true
) is not very informative, but it can be overridden with themsg
argument.Variables used like
${variable}
, as in the examples above, are replaced in the expression before evaluation. Variables are also available in the evaluation namespace, and can be accessed using special$variable
syntax as explained in the Evaluating expressions section.
-
should_contain
(container, item, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if
container
does not containitem
one or more times.Works with strings, lists, and anything that supports Python’s
in
operator.See Should Be Equal for an explanation on how to override the default error message with arguments
msg
andvalues
.If
ignore_case
is given a true value (see Boolean arguments) and compared items are strings, it indicates that comparison should be case-insensitive. If thecontainer
is a list-like object, string items in it are compared case-insensitively.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_contain_any
(container, *items, **configuration)¶ Fails if
container
does not contain any of the*items
.Works with strings, lists, and anything that supports Python’s
in
operator.Supports additional configuration parameters
msg
,values
,ignore_case
andstrip_spaces
, andcollapse_spaces
which have exactly the same semantics as arguments with same names have with Should Contain. These arguments must always be given usingname=value
syntax after allitems
.Note that possible equal signs in
items
must be escaped with a backslash (e.g.foo\=bar
) to avoid them to be passed in as**configuration
.
-
should_contain_x_times
(container, item, count, msg=None, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if
container
does not containitem
count
times.Works with strings, lists and all objects that Get Count works with. The default error message can be overridden with
msg
and the actual count is always logged.If
ignore_case
is given a true value (see Boolean arguments) and compared items are strings, it indicates that comparison should be case-insensitive. If thecontainer
is a list-like object, string items in it are compared case-insensitively.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_end_with
(str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if the string
str1
does not end with the stringstr2
.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
, as well as for semantics of theignore_case
,strip_spaces
, andcollapse_spaces
options.
-
should_match
(string, pattern, msg=None, values=True, ignore_case=False)¶ Fails if the given
string
does not match the givenpattern
.Pattern matching is similar as matching files in a shell with
*
,?
and[chars]
acting as wildcards. See the Glob patterns section for more information.If
ignore_case
is given a true value (see Boolean arguments) and compared items are strings, it indicates that comparison should be case-insensitive.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.
-
should_match_regexp
(string, pattern, msg=None, values=True, flags=None)¶ Fails if
string
does not matchpattern
as a regular expression.See the Regular expressions section for more information about regular expressions and how to use then in Robot Framework test data.
Notice that the given pattern does not need to match the whole string. For example, the pattern
ello
matches the stringHello world!
. If a full match is needed, the^
and$
characters can be used to denote the beginning and end of the string, respectively. For example,^ello$
only matches the exact stringello
.Possible flags altering how the expression is parsed (e.g.
re.IGNORECASE
,re.MULTILINE
) can be given using theflags
argument (e.g.flags=IGNORECASE | MULTILINE
) or embedded to the pattern (e.g.(?im)pattern
).If this keyword passes, it returns the portion of the string that matched the pattern. Additionally, the possible captured groups are returned.
See the Should Be Equal keyword for an explanation on how to override the default error message with the
msg
andvalues
arguments.The
flags
argument is new in Robot Framework 6.0.
-
should_not_be_empty
(item, msg=None)¶ Verifies that the given item is not empty.
The length of the item is got using the Get Length keyword. The default error message can be overridden with the
msg
argument.
-
should_not_be_equal
(first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if the given objects are equal.
See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.If
ignore_case
is given a true value (see Boolean arguments) and both arguments are strings, comparison is done case-insensitively.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_not_be_equal_as_integers
(first, second, msg=None, values=True, base=None)¶ Fails if objects are equal after converting them to integers.
See Convert To Integer for information how to convert integers from other bases than 10 using
base
argument or0b/0o/0x
prefixes.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.See Should Be Equal As Integers for some usage examples.
-
should_not_be_equal_as_numbers
(first, second, msg=None, values=True, precision=6)¶ Fails if objects are equal after converting them to real numbers.
The conversion is done with Convert To Number keyword using the given
precision
.See Should Be Equal As Numbers for examples on how to use
precision
and why it does not always work as expected. See also Should Be Equal for an explanation on how to override the default error message withmsg
andvalues
.
-
should_not_be_equal_as_strings
(first, second, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if objects are equal after converting them to strings.
See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
.If
ignore_case
is given a true value (see Boolean arguments), comparison is done case-insensitively.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.Strings are always [https://en.wikipedia.org/wiki/Unicode_equivalence| NFC normalized].
strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_not_be_true
(condition, msg=None)¶ Fails if the given condition is true.
See Should Be True for details about how
condition
is evaluated and howmsg
can be used to override the default error message.
-
should_not_contain
(container, item, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if
container
containsitem
one or more times.Works with strings, lists, and anything that supports Python’s
in
operator.See Should Be Equal for an explanation on how to override the default error message with arguments
msg
andvalues
.ignore_case
has exactly the same semantics as with Should Contain.If
strip_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done without leading and trailing spaces. Ifstrip_spaces
is given a string valueLEADING
orTRAILING
(case-insensitive), the comparison is done without leading or trailing spaces, respectively.If
collapse_spaces
is given a true value (see Boolean arguments) and both arguments are strings, the comparison is done with all white spaces replaced by a single space character.strip_spaces
is new in Robot Framework 4.0 andcollapse_spaces
is new in Robot Framework 4.1.
-
should_not_contain_any
(container, *items, **configuration)¶ Fails if
container
contains one or more of the*items
.Works with strings, lists, and anything that supports Python’s
in
operator.Supports additional configuration parameters
msg
,values
,ignore_case
andstrip_spaces
, andcollapse_spaces
which have exactly the same semantics as arguments with same names have with Should Contain. These arguments must always be given usingname=value
syntax after allitems
.Note that possible equal signs in
items
must be escaped with a backslash (e.g.foo\=bar
) to avoid them to be passed in as**configuration
.
-
should_not_end_with
(str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if the string
str1
ends with the stringstr2
.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
, as well as for semantics of theignore_case
,strip_spaces
, andcollapse_spaces
options.
-
should_not_match
(string, pattern, msg=None, values=True, ignore_case=False)¶ Fails if the given
string
matches the givenpattern
.Pattern matching is similar as matching files in a shell with
*
,?
and[chars]
acting as wildcards. See the Glob patterns section for more information.If
ignore_case
is given a true value (see Boolean arguments), the comparison is case-insensitive.See Should Be Equal for an explanation on how to override the default error message with
msg
and ``values`.
-
should_not_match_regexp
(string, pattern, msg=None, values=True, flags=None)¶ Fails if
string
matchespattern
as a regular expression.See Should Match Regexp for more information about arguments.
-
should_not_start_with
(str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if the string
str1
starts with the stringstr2
.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
, as well as for semantics of theignore_case
,strip_spaces
, andcollapse_spaces
options.
-
should_start_with
(str1, str2, msg=None, values=True, ignore_case=False, strip_spaces=False, collapse_spaces=False)¶ Fails if the string
str1
does not start with the stringstr2
.See Should Be Equal for an explanation on how to override the default error message with
msg
andvalues
, as well as for semantics of theignore_case
,strip_spaces
, andcollapse_spaces
options.
-
skip
(msg='Skipped with Skip keyword.')¶ Skips the rest of the current test.
Skips the remaining keywords in the current test and sets the given message to the test. If the test has teardown, it will be executed.
-
skip_if
(condition, msg=None)¶ Skips the rest of the current test if the
condition
is True.Skips the remaining keywords in the current test and sets the given message to the test. If
msg
is not given, thecondition
will be used as the message. If the test has teardown, it will be executed.If the
condition
evaluates to False, does nothing.
-
sleep
(time_, reason=None)¶ Pauses the test executed for the given time.
time
may be either a number or a time string. Time strings are in a format such as1 day 2 hours 3 minutes 4 seconds 5milliseconds
or1d 2h 3m 4s 5ms
, and they are fully explained in an appendix of Robot Framework User Guide. Providing a value without specifying minutes or seconds, defaults to seconds. Optional reason can be used to explain why sleeping is necessary. Both the time slept and the reason are logged.
-
variable_should_exist
(name, msg=None)¶ Fails unless the given variable exists within the current scope.
The name of the variable can be given either as a normal variable name like
${name}
or in escaped format like$name
or\${name}
. For the reasons explained in the Using variables with keywords creating or accessing variables section, using the escaped format is recommended.The default error message can be overridden with the
msg
argument.See also Variable Should Not Exist and Keyword Should Exist.
-
variable_should_not_exist
(name, msg=None)¶ Fails if the given variable exists within the current scope.
The name of the variable can be given either as a normal variable name like
${name}
or in escaped format like$name
or\${name}
. For the reasons explained in the Using variables with keywords creating or accessing variables section, using the escaped format is recommended.The default error message can be overridden with the
msg
argument.See also Variable Should Exist and Keyword Should Exist.
-
wait_until_keyword_succeeds
(retry, retry_interval, name, *args)¶ Runs the specified keyword and retries if it fails.
name
andargs
define the keyword that is executed similarly as with Run Keyword. How long to retry running the keyword is defined usingretry
argument either as timeout or count.retry_interval
is the time to wait between execution attempts.If
retry
is given as timeout, it must be in Robot Framework’s time format (e.g.1 minute
,2 min 3 s
,4.5
) that is explained in an appendix of Robot Framework User Guide. If it is given as count, it must havetimes
orx
postfix (e.g.5 times
,10 x
).retry_interval
must always be given in Robot Framework’s time format.By default
retry_interval
is the time to wait _after_ a keyword has failed. For example, if the first run takes 2 seconds and the retry interval is 3 seconds, the second run starts 5 seconds after the first run started. Ifretry_interval
start with prefixstrict:
, the execution time of the previous keyword is subtracted from the retry time. With the earlier example the second run would thus start 3 seconds after the first run started. A warning is logged if keyword execution time is longer than a strict interval.If the keyword does not succeed regardless of retries, this keyword fails. If the executed keyword passes, its return value is returned.
All normal failures are caught by this keyword. Errors caused by invalid syntax, test or keyword timeouts, or fatal exceptions (caused e.g. by Fatal Error) are not caught.
Running the same keyword multiple times inside this keyword can create lots of output and considerably increase the size of the generated output files. It is possible to remove unnecessary keywords from the outputs using
--RemoveKeywords WUKS
command line option.Support for “strict” retry interval is new in Robot Framework 4.1.
- It is not possible to see difference between different objects that
have the same string representation like string
-
exception
robot.libraries.BuiltIn.
RobotNotRunningError
[source]¶ Bases:
AttributeError
Used when something cannot be done because Robot is not running.
Based on AttributeError to be backwards compatible with RF < 2.8.5. May later be based directly on Exception, so new code should except this exception explicitly.
-
add_note
()¶ Exception.add_note(note) – add a note to the exception
-
args
¶
-
name
¶ attribute name
-
obj
¶ object
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
robot.libraries.BuiltIn.
register_run_keyword
(library, keyword, args_to_process=0, deprecation_warning=True)[source]¶ Tell Robot Framework that this keyword runs other keywords internally.
NOTE: This API will change in the future. For more information see https://github.com/robotframework/robotframework/issues/2190.
Parameters: - library – Name of the library the keyword belongs to.
- keyword – Name of the keyword itself.
- args_to_process – How many arguments to process normally before passing them to the keyword. Other arguments are not touched at all.
- deprecation_warning – Set to ``False```to avoid the warning.
Registered keywords are handled specially by Robot so that:
- Their arguments are not resolved normally (use
args_to_process
to control that). This basically means not replacing variables or handling escapes. - They are not stopped by timeouts.
- If there are conflicts with keyword names, these keywords have lower precedence than other keywords.
Main use cases are:
- Library keyword is using BuiltIn.run_keyword internally to execute other keywords. Registering the caller as a “run keyword variant” avoids variables and escapes in arguments being resolved multiple times. All arguments passed to run_keyword can and should be left unresolved.
- Keyword has some need to not resolve variables in arguments. This way variable values are not logged anywhere by Robot automatically.
As mentioned above, this API will likely be reimplemented in the future or there could be new API for library keywords to execute other keywords. External libraries can nevertheless use this API if they really need it and are aware of the possible breaking changes in the future.
from robot.libraries.BuiltIn import BuiltIn, register_run_keyword
register_run_keyword(__name__, ‘My Run Keyword’)
from robot.libraries.BuiltIn import BuiltIn, register_run_keyword
- class MyLibrary:
# Process one argument normally to get expression resolved. register_run_keyword(‘MyLibrary’, ‘my_run_keyword_if’, args_to_process=1)
robot.libraries.Collections module¶
-
class
robot.libraries.Collections.
Collections
[source]¶ Bases:
robot.libraries.Collections._List
,robot.libraries.Collections._Dictionary
A library providing keywords for handling lists and dictionaries.
Collections
is Robot Framework’s standard library that provides a set of keywords for handling Python lists and dictionaries. This library has keywords, for example, for modifying and getting values from lists and dictionaries (e.g. Append To List, Get From Dictionary) and for verifying their contents (e.g. Lists Should Be Equal, Dictionary Should Contain Value).== Table of contents ==
%TOC%
= Related keywords in BuiltIn =
Following keywords in the BuiltIn library can also be used with lists and dictionaries:
= Using with list-like and dictionary-like objects =
List keywords that do not alter the given list can also be used with tuples, and to some extend also with other iterables. Convert To List can be used to convert tuples and other iterables to Python
list
objects.Similarly dictionary keywords can, for most parts, be used with other mappings. Convert To Dictionary can be used if real Python
dict
objects are needed.= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Keywords verifying something that allow dropping actual and expected values from the possible error message also consider stringno values
to be false. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
Considering
OFF
and0
false is new in Robot Framework 3.1.= Data in examples =
List related keywords use variables in format
${Lx}
in their examples. They mean lists with as many alphabetic characters as specified byx
. For example,${L1}
means['a']
and${L3}
means['a', 'b', 'c']
.Dictionary keywords use similar
${Dx}
variables. For example,${D1}
means{'a': 1}
and${D3}
means{'a': 1, 'b': 2, 'c': 3}
.-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
should_contain_match
(list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False)[source]¶ Fails if
pattern
is not found inlist
.By default, pattern matching is similar to matching files in a shell and is case-sensitive and whitespace-sensitive. In the pattern syntax,
*
matches to anything and?
matches to any single character. You can also prependglob=
to your pattern to explicitly use this pattern matching behavior.If you prepend
regexp=
to your pattern, your pattern will be used according to the Python [http://docs.python.org/library/re.html|re module] regular expression syntax. Important note: Backslashes are an escape character, and must be escaped with another backslash (e.g.regexp=\\d{6}
to search for\d{6}
). See BuiltIn.Should Match Regexp for more details.If
case_insensitive
is given a true value (see Boolean arguments), the pattern matching will ignore case.If
whitespace_insensitive
is given a true value (see Boolean arguments), the pattern matching will ignore whitespace.Non-string values in lists are ignored when matching patterns.
Use the
msg
argument to override the default error message.See also
Should Not Contain Match
.
-
should_not_contain_match
(list, pattern, msg=None, case_insensitive=False, whitespace_insensitive=False)[source]¶ Fails if
pattern
is found inlist
.Exact opposite of Should Contain Match keyword. See that keyword for information about arguments and usage in general.
-
get_matches
(list, pattern, case_insensitive=False, whitespace_insensitive=False)[source]¶ Returns a list of matches to
pattern
inlist
.For more information on
pattern
,case_insensitive
, andwhitespace_insensitive
, see Should Contain Match.
-
get_match_count
(list, pattern, case_insensitive=False, whitespace_insensitive=False)[source]¶ Returns the count of matches to
pattern
inlist
.For more information on
pattern
,case_insensitive
, andwhitespace_insensitive
, see Should Contain Match.
-
append_to_list
(list_, *values)¶ Adds
values
to the end oflist
.
-
combine_lists
(*lists)¶ Combines the given
lists
together and returns the result.The given lists are not altered by this keyword.
-
convert_to_dictionary
(item)¶ Converts the given
item
to a Pythondict
type.Mainly useful for converting other mappings to normal dictionaries. This includes converting Robot Framework’s own
DotDict
instances that it uses if variables are created using the&{var}
syntax.Use Create Dictionary from the BuiltIn library for constructing new dictionaries.
-
convert_to_list
(item)¶ Converts the given
item
to a Pythonlist
type.Mainly useful for converting tuples and other iterable to lists. Use Create List from the BuiltIn library for constructing new lists.
-
copy_dictionary
(dictionary, deepcopy=False)¶ Returns a copy of the given dictionary.
The
deepcopy
argument controls should the returned dictionary be a [https://docs.python.org/library/copy.html|shallow or deep copy]. By default returns a shallow copy, but that can be changed by givingdeepcopy
a true value (see Boolean arguments). This is a new option in Robot Framework 3.1.2. Earlier versions always returned shallow copies.The given dictionary is never altered by this keyword.
-
copy_list
(list_, deepcopy=False)¶ Returns a copy of the given list.
If the optional
deepcopy
is given a true value, the returned list is a deep copy. New option in Robot Framework 3.1.2.The given list is never altered by this keyword.
-
count_values_in_list
(list_, value, start=0, end=None)¶ Returns the number of occurrences of the given
value
inlist
.The search can be narrowed to the selected sublist by the
start
andend
indexes having the same semantics as with Get Slice From List keyword. The given list is never altered by this keyword.
-
dictionaries_should_be_equal
(dict1, dict2, msg=None, values=True, ignore_keys=None)¶ Fails if the given dictionaries are not equal.
First the equality of dictionaries’ keys is checked and after that all the key value pairs. If there are differences between the values, those are listed in the error message. The types of the dictionaries do not need to be same.
ignore_keys
can be used to provide a list of keys to ignore in the comparison. It can be an actual list or a Python list literal. This option is new in Robot Framework 6.1.See Lists Should Be Equal for more information about configuring the error message with
msg
andvalues
arguments.
-
dictionary_should_contain_item
(dictionary, key, value, msg=None)¶ An item of
key
/value
must be found in adictionary
.Value is converted to unicode for comparison.
Use the
msg
argument to override the default error message.
-
dictionary_should_contain_key
(dictionary, key, msg=None)¶ Fails if
key
is not found fromdictionary
.Use the
msg
argument to override the default error message.
-
dictionary_should_contain_sub_dictionary
(dict1, dict2, msg=None, values=True)¶ Fails unless all items in
dict2
are found fromdict1
.See Lists Should Be Equal for more information about configuring the error message with
msg
andvalues
arguments.
-
dictionary_should_contain_value
(dictionary, value, msg=None)¶ Fails if
value
is not found fromdictionary
.Use the
msg
argument to override the default error message.
-
dictionary_should_not_contain_key
(dictionary, key, msg=None)¶ Fails if
key
is found fromdictionary
.Use the
msg
argument to override the default error message.
-
dictionary_should_not_contain_value
(dictionary, value, msg=None)¶ Fails if
value
is found fromdictionary
.Use the
msg
argument to override the default error message.
-
get_dictionary_items
(dictionary, sort_keys=True)¶ Returns items of the given
dictionary
as a list.Uses Get Dictionary Keys to get keys and then returns corresponding items. By default keys are sorted and items returned in that order, but this can be changed by giving
sort_keys
a false value (see Boolean arguments). Notice that with Python 3.5 and earlier dictionary order is undefined unless using ordered dictionaries.Items are returned as a flat list so that first item is a key, second item is a corresponding value, third item is the second key, and so on.
The given
dictionary
is never altered by this keyword.sort_keys
is a new option in Robot Framework 3.1.2. Earlier items were always sorted based on keys.
-
get_dictionary_keys
(dictionary, sort_keys=True)¶ Returns keys of the given
dictionary
as a list.By default keys are returned in sorted order (assuming they are sortable), but they can be returned in the original order by giving
sort_keys
a false value (see Boolean arguments). Notice that with Python 3.5 and earlier dictionary order is undefined unless using ordered dictionaries.The given
dictionary
is never altered by this keyword.sort_keys
is a new option in Robot Framework 3.1.2. Earlier keys were always sorted.
-
get_dictionary_values
(dictionary, sort_keys=True)¶ Returns values of the given
dictionary
as a list.Uses Get Dictionary Keys to get keys and then returns corresponding values. By default keys are sorted and values returned in that order, but this can be changed by giving
sort_keys
a false value (see Boolean arguments). Notice that with Python 3.5 and earlier dictionary order is undefined unless using ordered dictionaries.The given
dictionary
is never altered by this keyword.sort_keys
is a new option in Robot Framework 3.1.2. Earlier values were always sorted based on keys.
-
get_from_dictionary
(dictionary, key, default=)¶ Returns a value from the given
dictionary
based on the givenkey
.If the given
key
cannot be found from thedictionary
, this keyword fails. If optionaldefault
value is given, it will be returned instead of failing.The given dictionary is never altered by this keyword.
Support for
default
is new in Robot Framework 6.0.
-
get_from_list
(list_, index)¶ Returns the value specified with an
index
fromlist
.The given list is never altered by this keyword.
Index
0
means the first position,1
the second, and so on. Similarly,-1
is the last position,-2
the second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer.
-
get_index_from_list
(list_, value, start=0, end=None)¶ Returns the index of the first occurrence of the
value
on the list.The search can be narrowed to the selected sublist by the
start
andend
indexes having the same semantics as with Get Slice From List keyword. In case the value is not found, -1 is returned. The given list is never altered by this keyword.
-
get_slice_from_list
(list_, start=0, end=None)¶ Returns a slice of the given list between
start
andend
indexes.The given list is never altered by this keyword.
If both
start
andend
are given, a sublist containing values fromstart
toend
is returned. This is the same aslist[start:end]
in Python. To get all items from the beginning, use 0 as the start value, and to get all items until and including the end, useNone
(default) as the end value.Using
start
orend
not found on the list is the same as using the largest (or smallest) available index.
-
insert_into_list
(list_, index, value)¶ Inserts
value
intolist
to the position specified withindex
.Index
0
adds the value into the first position,1
to the second, and so on. Inserting from right works with negative indices so that-1
is the second last position,-2
third last, and so on. Use Append To List to add items to the end of the list.If the absolute value of the index is greater than the length of the list, the value is added at the end (positive index) or the beginning (negative index). An index can be given either as an integer or a string that can be converted to an integer.
-
keep_in_dictionary
(dictionary, *keys)¶ Keeps the given
keys
in thedictionary
and removes all other.If the given
key
cannot be found from thedictionary
, it is ignored.
-
list_should_contain_sub_list
(list1, list2, msg=None, values=True)¶ Fails if not all elements in
list2
are found inlist1
.The order of values and the number of values are not taken into account.
See Lists Should Be Equal for more information about configuring the error message with
msg
andvalues
arguments.
-
list_should_contain_value
(list_, value, msg=None)¶ Fails if the
value
is not found fromlist
.Use the
msg
argument to override the default error message.
-
list_should_not_contain_duplicates
(list_, msg=None)¶ Fails if any element in the
list
is found from it more than once.The default error message lists all the elements that were found from the
list
multiple times, but it can be overridden by giving a custommsg
. All multiple times found items and their counts are also logged.This keyword works with all iterables that can be converted to a list. The original iterable is never altered.
-
list_should_not_contain_value
(list_, value, msg=None)¶ Fails if the
value
is found fromlist
.Use the
msg
argument to override the default error message.
-
lists_should_be_equal
(list1, list2, msg=None, values=True, names=None, ignore_order=False)¶ Fails if given lists are unequal.
The keyword first verifies that the lists have equal lengths, and then it checks are all their values equal. Possible differences between the values are listed in the default error message like
Index 4: ABC != Abc
. The types of the lists do not need to be the same. For example, Python tuple and list with same content are considered equal.The error message can be configured using
msg
andvalues
arguments: - Ifmsg
is not given, the default error message is used. - Ifmsg
is given andvalues
gets a value considered true(see Boolean arguments), the error message starts with the givenmsg
followed by a newline and the default message.- If
msg
is given andvalues
is not given a true value, the error message is just the givenmsg
.
The optional
names
argument can be used for naming the indices shown in the default error message. It can either be a list of names matching the indices in the lists or a dictionary where keys are indices that need to be named. It is not necessary to name all indices. When using a dictionary, keys can be either integers or strings that can be converted to integers.If the items in index 2 would differ in the above examples, the error message would contain a row like
Index 2 (email): name@foo.com != name@bar.com
.The optional
ignore_order
argument can be used to ignore the order of the elements in the lists. Using it requires items to be sortable. This is new in Robot Framework 3.2.- If
-
log_dictionary
(dictionary, level='INFO')¶ Logs the size and contents of the
dictionary
using givenlevel
.Valid levels are TRACE, DEBUG, INFO (default), and WARN.
If you only want to log the size, use keyword Get Length from the BuiltIn library.
-
log_list
(list_, level='INFO')¶ Logs the length and contents of the
list
using givenlevel
.Valid levels are TRACE, DEBUG, INFO (default), and WARN.
If you only want to the length, use keyword Get Length from the BuiltIn library.
-
pop_from_dictionary
(dictionary, key, default=)¶ Pops the given
key
from thedictionary
and returns its value.By default the keyword fails if the given
key
cannot be found from thedictionary
. If optionaldefault
value is given, it will be returned instead of failing.
-
remove_duplicates
(list_)¶ Returns a list without duplicates based on the given
list
.Creates and returns a new list that contains all items in the given list so that one item can appear only once. Order of the items in the new list is the same as in the original except for missing duplicates. Number of the removed duplicates is logged.
-
remove_from_dictionary
(dictionary, *keys)¶ Removes the given
keys
from thedictionary
.If the given
key
cannot be found from thedictionary
, it is ignored.
-
remove_from_list
(list_, index)¶ Removes and returns the value specified with an
index
fromlist
.Index
0
means the first position,1
the second and so on. Similarly,-1
is the last position,-2
the second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer.
-
remove_values_from_list
(list_, *values)¶ Removes all occurrences of given
values
fromlist
.It is not an error if a value does not exist in the list at all.
-
reverse_list
(list_)¶ Reverses the given list in place.
Note that the given list is changed and nothing is returned. Use Copy List first, if you need to keep also the original order.
-
set_list_value
(list_, index, value)¶ Sets the value of
list
specified byindex
to the givenvalue
.Index
0
means the first position,1
the second and so on. Similarly,-1
is the last position,-2
second last, and so on. Using an index that does not exist on the list causes an error. The index can be either an integer or a string that can be converted to an integer.Starting from Robot Framework 6.1, it is also possible to use the native item assignment syntax. This is equivalent to the above:
-
set_to_dictionary
(dictionary, *key_value_pairs, **items)¶ Adds the given
key_value_pairs
and/oritems
to thedictionary
.If given items already exist in the dictionary, their values are updated.
It is easiest to specify items using the
name=value
syntax:A limitation of the above syntax is that keys must be strings. That can be avoided by passing keys and values as separate arguments:
Starting from Robot Framework 6.1, it is also possible to use the native item assignment syntax. This is equivalent to the above:
-
sort_list
(list_)¶ Sorts the given list in place.
Sorting fails if items in the list are not comparable with each others. On Python 2 most objects are comparable, but on Python 3 comparing, for example, strings with numbers is not possible.
Note that the given list is changed and nothing is returned. Use Copy List first, if you need to keep also the original order.
-
robot.libraries.DateTime module¶
A library for handling date and time values.
DateTime
is a Robot Framework standard library that supports creating and
converting date and time values (e.g. Get Current Date, Convert Time),
as well as doing simple calculations with them (e.g. Subtract Time From Date,
Add Time To Time). It supports dates and times in various formats, and can
also be used by other libraries programmatically.
== Table of contents ==
%TOC%
= Terminology =
In the context of this library, date
and time
generally have the following
meanings:
date
: An entity with both date and time components but without any- time zone information. For example,
2014-06-11 10:07:42
.
time
: A time interval. For example,1 hour 20 minutes
or01:20:00
.
This terminology differs from what Python’s standard
[http://docs.python.org/library/datetime.html|datetime] module uses.
Basically its
[http://docs.python.org/library/datetime.html#datetime-objects|datetime] and
[http://docs.python.org/library/datetime.html#timedelta-objects|timedelta]
objects match date
and time
as defined by this library.
= Date formats =
Dates can be given to and received from keywords in timestamp, custom timestamp, Python datetime and epoch time formats. These formats are discussed thoroughly in subsequent sections.
Input format is determined automatically based on the given date except when
using custom timestamps, in which case it needs to be given using
date_format
argument. Default result format is timestamp, but it can
be overridden using result_format
argument.
== Timestamp ==
If a date is given as a string, it is always considered to be a timestamp.
If no custom formatting is given using date_format
argument, the timestamp
is expected to be in [http://en.wikipedia.org/wiki/ISO_8601|ISO 8601] like
format YYYY-MM-DD hh:mm:ss.mil
, where any non-digit character can be used
as a separator or separators can be omitted altogether. Additionally,
only the date part is mandatory, all possibly missing time components are
considered to be zeros.
Dates can also be returned in the same YYYY-MM-DD hh:mm:ss.mil
format by
using timestamp
value with result_format
argument. This is also the
default format that keywords returning dates use. Milliseconds can be excluded
using exclude_millis
as explained in Millisecond handling section.
== Custom timestamp ==
It is possible to use custom timestamps in both input and output.
The custom format is same as accepted by Python’s
[http://docs.python.org/library/datetime.html#strftime-strptime-behavior|
datetime.strptime] function. For example, the default timestamp discussed
in the previous section would match %Y-%m-%d %H:%M:%S.%f
.
When using a custom timestamp in input, it must be specified using
date_format
argument. The actual input value must be a string that matches
the specified format exactly. When using a custom timestamp in output, it must
be given using result_format
argument.
== Python datetime ==
Python’s standard
[http://docs.python.org/library/datetime.html#datetime-objects|datetime]
objects can be used both in input and output. In input they are recognized
automatically, and in output it is possible to get them by giving datetime
value to result_format
argument.
One nice benefit with datetime objects is that they have different time components available as attributes that can be easily accessed using the extended variable syntax.
== Epoch time ==
Epoch time is the time in seconds since the
[http://en.wikipedia.org/wiki/Unix_time|UNIX epoch] i.e. 00:00:00.000 (UTC)
January 1, 1970. To give a date as an epoch time, it must be given as a number
(integer or float), not as a string. To return a date as an epoch time,
it is possible to use epoch
value with result_format
argument.
Epoch times are returned as floating point numbers.
Notice that epoch times are independent on time zones and thus same
around the world at a certain time. For example, epoch times returned
by Get Current Date are not affected by the time_zone
argument.
What local time a certain epoch time matches then depends on the time zone.
Following examples demonstrate using epoch times. They are tested in Finland, and due to the reasons explained above they would fail on other time zones.
== Earliest supported date ==
The earliest date that is supported depends on the date format and to some extent on the platform:
- Timestamps support year 1900 and above.
- Python datetime objects support year 1 and above.
- Epoch time supports 1970 and above on Windows.
- On other platforms epoch time supports 1900 and above or even earlier.
= Time formats =
Similarly as dates, times can be given to and received from keywords in various different formats. Supported formats are number, time string (verbose and compact), timer string and Python timedelta.
Input format for time is always determined automatically based on the input.
Result format is number by default, but it can be customised using
result_format
argument.
== Number ==
Time given as a number is interpreted to be seconds. It can be given either as an integer or a float, or it can be a string that can be converted to a number.
To return a time as a number, result_format
argument must have value
number
, which is also the default. Returned number is always a float.
== Time string ==
Time strings are strings in format like 1 minute 42 seconds
or 1min 42s
.
The basic idea of this format is having first a number and then a text
specifying what time that number represents. Numbers can be either
integers or floating point numbers, the whole format is case and space
insensitive, and it is possible to add a minus prefix to specify negative
times. The available time specifiers are:
days
,day
,d
hours
,hour
,h
minutes
,minute
,mins
,min
,m
seconds
,second
,secs
,sec
,s
milliseconds
,millisecond
,millis
,ms
microseconds
,microsecond
,us
,μs
(new in RF 6.0)nanoseconds
,nanosecond
,ns
(new in RF 6.0)
When returning a time string, it is possible to select between verbose
and compact
representations using result_format
argument. The verbose
format uses long specifiers day
, hour
, minute
, second
and
millisecond
, and adds s
at the end when needed. The compact format uses
shorter specifiers d
, h
, min
, s
and ms
, and even drops
the space between the number and the specifier.
== Timer string ==
Timer string is a string given in timer like format hh:mm:ss.mil
. In this
format both hour and millisecond parts are optional, leading and trailing
zeros can be left out when they are not meaningful, and negative times can
be represented by adding a minus prefix.
To return a time as timer string, result_format
argument must be given
value timer
. Timer strings are by default returned in full hh:mm:ss.mil
format, but milliseconds can be excluded using exclude_millis
as explained
in Millisecond handling section.
== Python timedelta ==
Python’s standard
[http://docs.python.org/library/datetime.html#datetime.timedelta|timedelta]
objects are also supported both in input and in output. In input they are
recognized automatically, and in output it is possible to receive them by
giving timedelta
value to result_format
argument.
= Millisecond handling =
This library handles dates and times internally using the precision of the given input. With timestamp, time string, and timer string result formats seconds are, however, rounded to millisecond accuracy. Milliseconds may also be included even if there would be none.
All keywords returning dates or times have an option to leave milliseconds out
by giving a true value to exclude_millis
argument. If the argument is given
as a string, it is considered true unless it is empty or case-insensitively
equal to false
, none
or no
. Other argument types are tested using
same [http://docs.python.org/library/stdtypes.html#truth|rules as in
Python].
When milliseconds are excluded, seconds in returned dates and times are rounded to the nearest full second. With timestamp and timer string result formats, milliseconds will also be removed from the returned string altogether.
= Programmatic usage =
In addition to be used as normal library, this library is intended to provide a stable API for other libraries to use if they want to support same date and time formats as this library. All the provided keywords are available as functions that can be easily imported:
Additionally helper classes Date
and Time
can be used directly:
-
robot.libraries.DateTime.
get_current_date
(time_zone='local', increment=0, result_format='timestamp', exclude_millis=False)[source]¶ Returns current local or UTC time with an optional increment.
Arguments: -
time_zone:
Get the current time on this time zone. Currently onlylocal
(default) andUTC
are supported. Has no effect if date is returned as an epoch time.increment:
Optional time increment to add to the returned date in- one of the supported time formats. Can be negative.
result_format:
Format of the returned date (see date formats).exclude_millis:
When set to any true value, rounds and drops- milliseconds as explained in millisecond handling.
-
robot.libraries.DateTime.
convert_date
(date, result_format='timestamp', exclude_millis=False, date_format=None)[source]¶ Converts between supported date formats.
Arguments: -
date:
Date in one of the supported date formats. -result_format:
Format of the returned date. -exclude_millis:
When set to any true value, rounds and dropsmilliseconds as explained in millisecond handling.date_format:
Specifies possible custom timestamp format.
-
robot.libraries.DateTime.
convert_time
(time, result_format='number', exclude_millis=False)[source]¶ Converts between supported time formats.
Arguments: -
time:
Time in one of the supported time formats. -result_format:
Format of the returned time. -exclude_millis:
When set to any true value, rounds and dropsmilliseconds as explained in millisecond handling.
-
robot.libraries.DateTime.
subtract_date_from_date
(date1, date2, result_format='number', exclude_millis=False, date1_format=None, date2_format=None)[source]¶ Subtracts date from another date and returns time between.
Arguments: -
date1:
Date to subtract another date from in one of thesupported date formats.date2:
Date that is subtracted in one of the supported- date formats.
result_format:
Format of the returned time (see time formats).exclude_millis:
When set to any true value, rounds and drops- milliseconds as explained in millisecond handling.
date1_format:
Possible custom timestamp format ofdate1
.date2_format:
Possible custom timestamp format ofdate2
.
Examples:
-
robot.libraries.DateTime.
add_time_to_date
(date, time, result_format='timestamp', exclude_millis=False, date_format=None)[source]¶ Adds time to date and returns the resulting date.
Arguments: -
date:
Date to add time to in one of the supporteddate formats.time:
Time that is added in one of the supported- time formats.
result_format:
Format of the returned date.exclude_millis:
When set to any true value, rounds and drops- milliseconds as explained in millisecond handling.
date_format:
Possible custom timestamp format ofdate
.
-
robot.libraries.DateTime.
subtract_time_from_date
(date, time, result_format='timestamp', exclude_millis=False, date_format=None)[source]¶ Subtracts time from date and returns the resulting date.
Arguments: -
date:
Date to subtract time from in one of the supporteddate formats.time:
Time that is subtracted in one of the supported- time formats.
result_format:
Format of the returned date.exclude_millis:
When set to any true value, rounds and drops- milliseconds as explained in millisecond handling.
date_format:
Possible custom timestamp format ofdate
.
-
robot.libraries.DateTime.
add_time_to_time
(time1, time2, result_format='number', exclude_millis=False)[source]¶ Adds time to another time and returns the resulting time.
Arguments: -
time1:
First time in one of the supported time formats. -time2:
Second time in one of the supported time formats. -result_format:
Format of the returned time. -exclude_millis:
When set to any true value, rounds and dropsmilliseconds as explained in millisecond handling.
-
robot.libraries.DateTime.
subtract_time_from_time
(time1, time2, result_format='number', exclude_millis=False)[source]¶ Subtracts time from another time and returns the resulting time.
Arguments: -
time1:
Time to subtract another time from in one ofthe supported time formats.time2:
Time to subtract in one of the supported time formats.result_format:
Format of the returned time.exclude_millis:
When set to any true value, rounds and drops- milliseconds as explained in millisecond handling.
robot.libraries.Dialogs module¶
A library providing dialogs for interacting with users.
Dialogs
is Robot Framework’s standard library that provides means
for pausing the test or task execution and getting input from users.
Long lines in the provided messages are wrapped automatically. If you want
to wrap lines manually, you can add newlines using the \n
character
sequence.
The library has a known limitation that it cannot be used with timeouts.
-
robot.libraries.Dialogs.
pause_execution
(message='Execution paused. Press OK to continue.')[source]¶ Pauses execution until user clicks
Ok
button.message
is the message shown in the dialog.
-
robot.libraries.Dialogs.
execute_manual_step
(message, default_error='')[source]¶ Pauses execution until user sets the keyword status.
User can press either
PASS
orFAIL
button. In the latter case execution fails and an additional dialog is opened for defining the error message.message
is the instruction shown in the initial dialog anddefault_error
is the default value shown in the possible error message dialog.
-
robot.libraries.Dialogs.
get_value_from_user
(message, default_value='', hidden=False)[source]¶ Pauses execution and asks user to input a value.
Value typed by the user, or the possible default value, is returned. Returning an empty value is fine, but pressing
Cancel
fails the keyword.message
is the instruction shown in the dialog anddefault_value
is the possible default value shown in the input field.If
hidden
is given a true value, the value typed by the user is hidden.hidden
is considered true if it is a non-empty string not equal tofalse
,none
orno
, case-insensitively. If it is not a string, its truth value is got directly using same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].
-
robot.libraries.Dialogs.
get_selection_from_user
(message, *values)[source]¶ Pauses execution and asks user to select a value.
The selected value is returned. Pressing
Cancel
fails the keyword.message
is the instruction shown in the dialog andvalues
are the options given to the user.
-
robot.libraries.Dialogs.
get_selections_from_user
(message, *values)[source]¶ Pauses execution and asks user to select multiple values.
The selected values are returned as a list. Selecting no values is OK and in that case the returned list is empty. Pressing
Cancel
fails the keyword.message
is the instruction shown in the dialog andvalues
are the options given to the user.
robot.libraries.OperatingSystem module¶
-
class
robot.libraries.OperatingSystem.
OperatingSystem
[source]¶ Bases:
object
A library providing keywords for operating system related tasks.
OperatingSystem
is Robot Framework’s standard library that enables various operating system related tasks to be performed in the system where Robot Framework is running. It can, among other things, execute commands (e.g. Run), create and remove files and directories (e.g. Create File, Remove Directory), check whether files or directories exists or contain something (e.g. File Should Exist, Directory Should Be Empty) and manipulate environment variables (e.g. Set Environment Variable).== Table of contents ==
%TOC%
= Path separators =
Because Robot Framework uses the backslash (
\
) as an escape character in its data, using a literal backslash requires duplicating it like inc:\\path\\file.txt
. That can be inconvenient especially with longer Windows paths, and thus all keywords expecting paths as arguments convert forward slashes to backslashes automatically on Windows. This also means that paths like${CURDIR}/path/file.txt
are operating system independent.Notice that the automatic path separator conversion does not work if the path is only a part of an argument like with the Run keyword. In these cases the built-in variable
${/}
that contains\
or/
, depending on the operating system, can be used instead.= Pattern matching =
Many keywords accept arguments as either _glob_ or _regular expression_ patterns.
== Glob patterns ==
Some keywords, for example List Directory, support so called [http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where:
Unless otherwise noted, matching is case-insensitive on case-insensitive operating systems such as Windows.
== Regular expressions ==
Some keywords, for example Grep File, support [http://en.wikipedia.org/wiki/Regular_expression|regular expressions] that are more powerful but also more complicated that glob patterns. The regular expression support is implemented using Python’s [http://docs.python.org/library/re.html|re module] and its documentation should be consulted for more information about the syntax.
Because the backslash character (
\
) is an escape character in Robot Framework data, possible backslash characters in regular expressions need to be escaped with another backslash like\\d\\w+
. Strings that may contain special characters but should be handled as literal strings, can be escaped with the Regexp Escape keyword from the BuiltIn library.= Tilde expansion =
Paths beginning with
~
or~username
are expanded to the current or specified user’s home directory, respectively. The resulting path is operating system dependent, but typically e.g.~/robot
is expanded toC:\Users\<user>\robot
on Windows and/home/<user>/robot
on Unixes.=
pathlib.Path
support =Starting from Robot Framework 6.0, arguments representing paths can be given as [https://docs.python.org/3/library/pathlib.html pathlib.Path] instances in addition to strings.
All keywords returning paths return them as strings. This may change in the future so that the return value type matches the argument type.
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
= Example =
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
run
(command)[source]¶ Runs the given command in the system and returns the output.
The execution status of the command is not checked by this keyword, and it must be done separately based on the returned output. If the execution return code is needed, either Run And Return RC or Run And Return RC And Output can be used.
The standard error stream is automatically redirected to the standard output stream by adding
2>&1
after the executed command. This automatic redirection is done only when the executed command does not contain additional output redirections. You can thus freely forward the standard error somewhere else, for example, likemy_command 2>stderr.txt
.The returned output contains everything written into the standard output or error streams by the command (unless either of them is redirected explicitly). Many commands add an extra newline (
\n
) after the output to make it easier to read in the console. To ease processing the returned output, this possible trailing newline is stripped by this keyword.TIP: Run Process keyword provided by the [http://robotframework.org/robotframework/latest/libraries/Process.html| Process library] supports better process configuration and is generally recommended as a replacement for this keyword.
-
run_and_return_rc
(command)[source]¶ Runs the given command in the system and returns the return code.
The return code (RC) is returned as a positive integer in range from 0 to 255 as returned by the executed command. On some operating systems (notable Windows) original return codes can be something else, but this keyword always maps them to the 0-255 range. Since the RC is an integer, it must be checked e.g. with the keyword Should Be Equal As Integers instead of Should Be Equal (both are built-in keywords).
See Run and Run And Return RC And Output if you need to get the output of the executed command.
TIP: Run Process keyword provided by the [http://robotframework.org/robotframework/latest/libraries/Process.html| Process library] supports better process configuration and is generally recommended as a replacement for this keyword.
-
run_and_return_rc_and_output
(command)[source]¶ Runs the given command in the system and returns the RC and output.
The return code (RC) is returned similarly as with Run And Return RC and the output similarly as with Run.
TIP: Run Process keyword provided by the [http://robotframework.org/robotframework/latest/libraries/Process.html| Process library] supports better process configuration and is generally recommended as a replacement for this keyword.
-
get_file
(path, encoding='UTF-8', encoding_errors='strict')[source]¶ Returns the contents of a specified file.
This keyword reads the specified file and returns the contents. Line breaks in content are converted to platform independent form. See also Get Binary File.
encoding
defines the encoding of the file. The default value isUTF-8
, which means that UTF-8 and ASCII encoded files are read correctly. In addition to the encodings supported by the underlying Python implementation, the following special encoding values can be used:SYSTEM
: Use the default system encoding.CONSOLE
: Use the console encoding. Outside Windows this is same as the system encoding.
encoding_errors
argument controls what to do if decoding some bytes fails. All values accepted bydecode
method in Python are valid, but in practice the following values are most useful:strict
: Fail if characters cannot be decoded (default).ignore
: Ignore characters that cannot be decoded.replace
: Replace characters that cannot be decoded with a replacement character.
-
get_binary_file
(path)[source]¶ Returns the contents of a specified file.
This keyword reads the specified file and returns the contents as is. See also Get File.
-
grep_file
(path, pattern, encoding='UTF-8', encoding_errors='strict', regexp=False)[source]¶ Returns the lines of the specified file that match the
pattern
.This keyword reads a file from the file system using the defined
path
,encoding
andencoding_errors
similarly as Get File. A difference is that only the lines that match the givenpattern
are returned. Lines are returned as a single string concatenated back together with newlines and the number of matched lines is automatically logged. Possible trailing newline is never returned.A line matches if it contains the
pattern
anywhere in it i.e. it does not need to match the pattern fully. There are two supported pattern types:- By default the pattern is considered a _glob_ pattern where, for example,
*
and?
can be used as wildcards. - If the
regexp
argument is given a true value, the pattern is considered to be a _regular expression_. These patterns are more powerful but also more complicated than glob patterns. They often use the backslash character and it needs to be escaped in Robot Framework date like \.
For more information about glob and regular expression syntax, see the Pattern matching section. With this keyword matching is always case-sensitive.
Special encoding values
SYSTEM
andCONSOLE
that Get File supports are supported by this keyword only with Robot Framework 4.0 and newer.Support for regular expressions is new in Robot Framework 5.0.
- By default the pattern is considered a _glob_ pattern where, for example,
-
log_file
(path, encoding='UTF-8', encoding_errors='strict')[source]¶ Wrapper for Get File that also logs the returned file.
The file is logged with the INFO level. If you want something else, just use Get File and the built-in keyword Log with the desired level.
See Get File for more information about
encoding
andencoding_errors
arguments.
-
should_exist
(path, msg=None)[source]¶ Fails unless the given path (file or directory) exists.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
should_not_exist
(path, msg=None)[source]¶ Fails if the given path (file or directory) exists.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
file_should_exist
(path, msg=None)[source]¶ Fails unless the given
path
points to an existing file.The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
file_should_not_exist
(path, msg=None)[source]¶ Fails if the given path points to an existing file.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
directory_should_exist
(path, msg=None)[source]¶ Fails unless the given path points to an existing directory.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
directory_should_not_exist
(path, msg=None)[source]¶ Fails if the given path points to an existing file.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax.
The default error message can be overridden with the
msg
argument.
-
wait_until_removed
(path, timeout='1 minute')[source]¶ Waits until the given file or directory is removed.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax. If the path is a pattern, the keyword waits until all matching items are removed.
The optional
timeout
can be used to control the maximum time of waiting. The timeout is given as a timeout string, e.g. in a format15 seconds
,1min 10s
or just10
. The time string format is described in an appendix of Robot Framework User Guide.If the timeout is negative, the keyword is never timed-out. The keyword returns immediately, if the path does not exist in the first place.
-
wait_until_created
(path, timeout='1 minute')[source]¶ Waits until the given file or directory is created.
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax. If the path is a pattern, the keyword returns when an item matching it is created.
The optional
timeout
can be used to control the maximum time of waiting. The timeout is given as a timeout string, e.g. in a format15 seconds
,1min 10s
or just10
. The time string format is described in an appendix of Robot Framework User Guide.If the timeout is negative, the keyword is never timed-out. The keyword returns immediately, if the path already exists.
-
directory_should_be_empty
(path, msg=None)[source]¶ Fails unless the specified directory is empty.
The default error message can be overridden with the
msg
argument.
-
directory_should_not_be_empty
(path, msg=None)[source]¶ Fails if the specified directory is empty.
The default error message can be overridden with the
msg
argument.
-
file_should_be_empty
(path, msg=None)[source]¶ Fails unless the specified file is empty.
The default error message can be overridden with the
msg
argument.
-
file_should_not_be_empty
(path, msg=None)[source]¶ Fails if the specified file is empty.
The default error message can be overridden with the
msg
argument.
-
create_file
(path, content='', encoding='UTF-8')[source]¶ Creates a file with the given content and encoding.
If the directory where the file is created does not exist, it is automatically created along with possible missing intermediate directories. Possible existing file is overwritten.
On Windows newline characters (
\n
) in content are automatically converted to Windows native newline sequence (\r\n
).See Get File for more information about possible
encoding
values, including special valuesSYSTEM
andCONSOLE
.Use Append To File if you want to append to an existing file and Create Binary File if you need to write bytes without encoding. File Should Not Exist can be used to avoid overwriting existing files.
-
create_binary_file
(path, content)[source]¶ Creates a binary file with the given content.
If content is given as a Unicode string, it is first converted to bytes character by character. All characters with ordinal below 256 can be used and are converted to bytes with same values. Using characters with higher ordinal is an error.
Byte strings, and possible other types, are written to the file as is.
If the directory for the file does not exist, it is created, along with missing intermediate directories.
Use Create File if you want to create a text file using a certain encoding. File Should Not Exist can be used to avoid overwriting existing files.
-
append_to_file
(path, content, encoding='UTF-8')[source]¶ Appends the given content to the specified file.
If the file exists, the given text is written to its end. If the file does not exist, it is created.
Other than not overwriting possible existing files, this keyword works exactly like Create File. See its documentation for more details about the usage.
-
remove_file
(path)[source]¶ Removes a file with the given path.
Passes if the file does not exist, but fails if the path does not point to a regular file (e.g. it points to a directory).
The path can be given as an exact path or as a glob pattern. See the Glob patterns section for details about the supported syntax. If the path is a pattern, all files matching it are removed.
-
empty_directory
(path)[source]¶ Deletes all the content from the given directory.
Deletes both files and sub-directories, but the specified directory itself if not removed. Use Remove Directory if you want to remove the whole directory.
-
create_directory
(path)[source]¶ Creates the specified directory.
Also possible intermediate directories are created. Passes if the directory already exists, but fails if the path exists and is not a directory.
-
remove_directory
(path, recursive=False)[source]¶ Removes the directory pointed to by the given
path
.If the second argument
recursive
is given a true value (see Boolean arguments), the directory is removed recursively. Otherwise removing fails if the directory is not empty.If the directory pointed to by the
path
does not exist, the keyword passes, but it fails, if thepath
points to a file.
-
copy_file
(source, destination)[source]¶ Copies the source file into the destination.
Source must be a path to an existing file or a glob pattern (see Glob patterns) that matches exactly one file. How the destination is interpreted is explained below.
1) If the destination is an existing file, the source file is copied over it.
2) If the destination is an existing directory, the source file is copied into it. A possible file with the same name as the source is overwritten.
3) If the destination does not exist and it ends with a path separator (
/
or\
), it is considered a directory. That directory is created and a source file copied into it. Possible missing intermediate directories are also created.4) If the destination does not exist and it does not end with a path separator, it is considered a file. If the path to the file does not exist, it is created.
The resulting destination path is returned.
See also Copy Files, Move File, and Move Files.
-
move_file
(source, destination)[source]¶ Moves the source file into the destination.
Arguments have exactly same semantics as with Copy File keyword. Destination file path is returned.
If the source and destination are on the same filesystem, rename operation is used. Otherwise file is copied to the destination filesystem and then removed from the original filesystem.
See also Move Files, Copy File, and Copy Files.
-
copy_files
(*sources_and_destination)[source]¶ Copies specified files to the target directory.
Source files can be given as exact paths and as glob patterns (see Glob patterns). At least one source must be given, but it is not an error if it is a pattern that does not match anything.
Last argument must be the destination directory. If the destination does not exist, it will be created.
See also Copy File, Move File, and Move Files.
-
move_files
(*sources_and_destination)[source]¶ Moves specified files to the target directory.
Arguments have exactly same semantics as with Copy Files keyword.
See also Move File, Copy File, and Copy Files.
-
copy_directory
(source, destination)[source]¶ Copies the source directory into the destination.
If the destination exists, the source is copied under it. Otherwise the destination directory and the possible missing intermediate directories are created.
-
move_directory
(source, destination)[source]¶ Moves the source directory into a destination.
Uses Copy Directory keyword internally, and
source
anddestination
arguments have exactly same semantics as with that keyword.
-
get_environment_variable
(name, default=None)[source]¶ Returns the value of an environment variable with the given name.
If no environment variable is found, returns possible default value. If no default value is given, the keyword fails.
Returned variables are automatically decoded to Unicode using the system encoding.
Note that you can also access environment variables directly using the variable syntax
%{ENV_VAR_NAME}
.
-
set_environment_variable
(name, value)[source]¶ Sets an environment variable to a specified value.
Values are converted to strings automatically. Set variables are automatically encoded using the system encoding.
-
append_to_environment_variable
(name, *values, **config)[source]¶ Appends given
values
to environment variablename
.If the environment variable already exists, values are added after it, and otherwise a new environment variable is created.
Values are, by default, joined together using the operating system path separator (
;
on Windows,:
elsewhere). This can be changed by giving a separator after the values likeseparator=value
. No other configuration parameters are accepted.
-
remove_environment_variable
(*names)[source]¶ Deletes the specified environment variable.
Does nothing if the environment variable is not set.
It is possible to remove multiple variables by passing them to this keyword as separate arguments.
-
environment_variable_should_be_set
(name, msg=None)[source]¶ Fails if the specified environment variable is not set.
The default error message can be overridden with the
msg
argument.
-
environment_variable_should_not_be_set
(name, msg=None)[source]¶ Fails if the specified environment variable is set.
The default error message can be overridden with the
msg
argument.
-
get_environment_variables
()[source]¶ Returns currently available environment variables as a dictionary.
Both keys and values are decoded to Unicode using the system encoding. Altering the returned dictionary has no effect on the actual environment variables.
-
log_environment_variables
(level='INFO')[source]¶ Logs all environment variables using the given log level.
Environment variables are also returned the same way as with Get Environment Variables keyword.
-
join_path
(base, *parts)[source]¶ Joins the given path part(s) to the given base path.
The path separator (
/
or\
) is inserted when needed and the possible absolute paths handled as expected. The resulted path is also normalized.- ${path} = ‘my/path’
- ${p2} = ‘my/path’
- ${p3} = ‘my/path/my/file.txt’
- ${p4} = ‘/path’
- ${p5} = ‘/my/path2’
-
join_paths
(base, *paths)[source]¶ Joins given paths with base and returns resulted paths.
See Join Path for more information.
- @{p1} = [‘base/example’, ‘base/other’]
- @{p2} = [‘/example’, ‘/my/base/other’]
- @{p3} = [‘my/base/example/path’, ‘my/base/other’, ‘my/base/one/more’]
-
normalize_path
(path, case_normalize=False)[source]¶ Normalizes the given path.
- Collapses redundant separators and up-level references.
- Converts
/
to\
on Windows. - Replaces initial
~
or~user
by that user’s home directory. - If
case_normalize
is given a true value (see Boolean arguments) on Windows, converts the path to all lowercase. - Converts
pathlib.Path
instances tostr
. - ${path1} = ‘abc’
- ${path2} = ‘def’
- ${path3} = ‘abc/def/ghi’
- ${path4} = ‘/home/robot/stuff’
On Windows result would use
\
instead of/
and home directory would be different.
-
split_path
(path)[source]¶ Splits the given path from the last path separator (
/
or\
).The given path is first normalized (e.g. a possible trailing path separator is removed, special directories
..
and.
removed). The parts that are split are returned as separate components.- ${path1} = ‘abc’ & ${dir} = ‘def’
- ${path2} = ‘abc/def’ & ${file} = ‘ghi.txt’
- ${path3} = ‘def’ & ${d2} = ‘ghi’
-
split_extension
(path)[source]¶ Splits the extension from the given path.
The given path is first normalized (e.g. possible trailing path separators removed, special directories
..
and.
removed). The base path and extension are returned as separate components so that the dot used as an extension separator is removed. If the path contains no extension, an empty string is returned for it. Possible leading and trailing dots in the file name are never considered to be extension separators.- ${path} = ‘file’ & ${ext} = ‘extension’
- ${p2} = ‘path/file’ & ${e2} = ‘ext’
- ${p3} = ‘path/file’ & ${e3} = ‘’
- ${p4} = ‘p2/file’ & ${e4} = ‘ext’
- ${p5} = ‘path/.file’ & ${e5} = ‘ext’
- ${p6} = ‘path/.file’ & ${e6} = ‘’
-
get_modified_time
(path, format='timestamp')[source]¶ Returns the last modification time of a file or directory.
How time is returned is determined based on the given
format
string as follows. Note that all checks are case-insensitive. Returned time is also automatically logged.- If
format
contains the wordepoch
, the time is returned in seconds after the UNIX epoch. The return value is always an integer. - If
format
contains any of the wordsyear
,month
,day
,hour
,min
orsec
, only the selected parts are returned. The order of the returned parts is always the one in the previous sentence and the order of the words informat
is not significant. The parts are returned as zero-padded strings (e.g. May ->05
). - Otherwise, and by default, the time is returned as a
timestamp string in the format
2006-02-24 15:08:31
.
2006-03-29 15:06:21): - ${time} = ‘2006-03-29 15:06:21’ - ${secs} = 1143637581 - ${year} = ‘2006’ - ${y} = ‘2006’ & ${d} = ‘29’ - @{time} = [‘2006’, ‘03’, ‘29’, ‘15’, ‘06’, ‘21’]
- If
-
set_modified_time
(path, mtime)[source]¶ Sets the file modification and access times.
Changes the modification and access times of the given file to the value determined by
mtime
. The time can be given in different formats described below. Note that all checks involving strings are case-insensitive. Modified time can only be set to regular files.- If
mtime
is a number, or a string that can be converted to a number, it is interpreted as seconds since the UNIX epoch (1970-01-01 00:00:00 UTC). This documentation was originally written about 1177654467 seconds after the epoch. - If
mtime
is a timestamp, that time will be used. Valid timestamp formats areYYYY-MM-DD hh:mm:ss
andYYYYMMDD hhmmss
. - If
mtime
is equal toNOW
, the current local time is used. - If
mtime
is equal toUTC
, the current time in [http://en.wikipedia.org/wiki/Coordinated_Universal_Time|UTC] is used. - If
mtime
is in the format likeNOW - 1 day
orUTC + 1 hour 30 min
, the current local/UTC time plus/minus the time specified with the time string is used. The time string format is described in an appendix of Robot Framework User Guide.
- If
-
list_directory
(path, pattern=None, absolute=False)[source]¶ Returns and logs items in a directory, optionally filtered with
pattern
.File and directory names are returned in case-sensitive alphabetical order, e.g.
['A Name', 'Second', 'a lower case name', 'one more']
. Implicit directories.
and..
are not returned. The returned items are automatically logged.File and directory names are returned relative to the given path (e.g.
'file.txt'
) by default. If you want them be returned in absolute format (e.g.'/home/robot/file.txt'
), give theabsolute
argument a true value (see Boolean arguments).If
pattern
is given, only items matching it are returned. The pattern is considered to be a _glob pattern_ and the full syntax is explained in the Glob patterns section. With this keyword matching is always case-sensitive.
-
list_files_in_directory
(path, pattern=None, absolute=False)[source]¶ Wrapper for List Directory that returns only files.
-
list_directories_in_directory
(path, pattern=None, absolute=False)[source]¶ Wrapper for List Directory that returns only directories.
-
count_items_in_directory
(path, pattern=None)[source]¶ Returns and logs the number of all items in the given directory.
The argument
pattern
has the same semantics as with List Directory keyword. The count is returned as an integer, so it must be checked e.g. with the built-in keyword Should Be Equal As Integers.
-
count_files_in_directory
(path, pattern=None)[source]¶ Wrapper for Count Items In Directory returning only file count.
-
robot.libraries.Process module¶
-
class
robot.libraries.Process.
Process
[source]¶ Bases:
object
Robot Framework library for running processes.
This library utilizes Python’s [http://docs.python.org/library/subprocess.html|subprocess] module and its [http://docs.python.org/library/subprocess.html#popen-constructor|Popen] class.
The library has following main usages:
- Running processes in system and waiting for their completion using Run Process keyword.
- Starting processes on background using Start Process.
- Waiting started process to complete using Wait For Process or stopping them with Terminate Process or Terminate All Processes.
== Table of contents ==
%TOC%
= Specifying command and arguments =
Both Run Process and Start Process accept the command to execute and all arguments passed to the command as separate arguments. This makes usage convenient and also allows these keywords to automatically escape possible spaces and other special characters in commands and arguments. Notice that if a command accepts options that themselves accept values, these options and their values must be given as separate arguments.
When running processes in shell, it is also possible to give the whole command to execute as a single string. The command can then contain multiple commands to be run together. When using this approach, the caller is responsible on escaping.
Possible non-string arguments are converted to strings automatically.
= Process configuration =
Run Process and Start Process keywords can be configured using optional
**configuration
keyword arguments. Configuration arguments must be given after other arguments passed to these keywords and must use syntax likename=value
. Available configuration arguments are listed below and discussed further in sections afterwards.Note that because
**configuration
is passed usingname=value
syntax, possible equal signs in other arguments passed to Run Process and Start Process must be escaped with a backslash likename\=value
. See Run Process for an example.== Running processes in shell ==
The
shell
argument specifies whether to run the process in a shell or not. By default shell is not used, which means that shell specific commands, likecopy
anddir
on Windows, are not available. You can, however, run shell scripts and batch files without using a shell.Giving the
shell
argument any non-false value, such asshell=True
, changes the program to be executed in a shell. It allows using the shell capabilities, but can also make the process invocation operating system dependent. Having a shell between the actually started process and this library can also interfere communication with the process such as stopping it and reading its outputs. Because of these problems, it is recommended to use the shell only when absolutely necessary.When using a shell it is possible to give the whole command to execute as a single string. See Specifying command and arguments section for examples and more details in general.
== Current working directory ==
By default, the child process will be executed in the same directory as the parent process, the process running Robot Framework, is executed. This can be changed by giving an alternative location using the
cwd
argument. Forward slashes in the given path are automatically converted to backslashes on Windows.Standard output and error streams, when redirected to files, are also relative to the current working directory possibly set using the
cwd
argument.== Environment variables ==
By default the child process will get a copy of the parent process’s environment variables. The
env
argument can be used to give the child a custom environment as a Python dictionary. If there is a need to specify only certain environment variable, it is possible to use theenv:<name>=<value>
format to set or override only that named variables. It is also possible to use these two approaches together.== Standard output and error streams ==
By default processes are run so that their standard output and standard error streams are kept in the memory. This works fine normally, but if there is a lot of output, the output buffers may get full and the program can hang.
To avoid the above mentioned problems, it is possible to use
stdout
andstderr
arguments to specify files on the file system where to redirect the outputs. This can also be useful if other processes or other keywords need to read or manipulate the outputs somehow.Given
stdout
andstderr
paths are relative to the current working directory. Forward slashes in the given paths are automatically converted to backslashes on Windows.As a special feature, it is possible to redirect the standard error to the standard output by using
stderr=STDOUT
.Regardless are outputs redirected to files or not, they are accessible through the result object returned when the process ends. Commands are expected to write outputs using the console encoding, but output encoding can be configured using the
output_encoding
argument if needed.If you are not interested in outputs at all, you can explicitly ignore them by using a special value
DEVNULL
both withstdout
andstderr
. For example,stdout=DEVNULL
is the same as redirecting output on console with> /dev/null
on UNIX-like operating systems or> NUL
on Windows. This way the process will not hang even if there would be a lot of output, but naturally output is not available after execution either.Support for the special value
DEVNULL
is new in Robot Framework 3.2.Note that the created output files are not automatically removed after the test run. The user is responsible to remove them if needed.
== Standard input stream ==
The
stdin
argument makes it possible to pass information to the standard input stream of the started process. How its value is interpreted is explained in the table below.Values
PIPE
andNONE
are internally mapped directly tosubprocess.PIPE
andNone
, respectively, when calling [https://docs.python.org/3/library/subprocess.html#subprocess.Popen|subprocess.Popen]. The default behavior may change fromPIPE
toNONE
in future releases. If you depend on thePIPE
behavior, it is a good idea to use it explicitly.The support to configure
stdin
is new in Robot Framework 4.1.2.== Output encoding ==
Executed commands are, by default, expected to write outputs to the standard output and error streams using the encoding used by the system console. If the command uses some other encoding, that can be configured using the
output_encoding
argument. This is especially useful on Windows where the console uses a different encoding than rest of the system, and many commands use the general system encoding instead of the console encoding.The value used with the
output_encoding
argument must be a valid encoding and must match the encoding actually used by the command. As a convenience, it is possible to use stringsCONSOLE
andSYSTEM
to specify that the console or system encoding is used, respectively. If produced outputs use different encoding then configured, values got through the result object will be invalid.== Alias ==
A custom name given to the process that can be used when selecting the active process.
= Active process =
The library keeps record which of the started processes is currently active. By default it is the latest process started with Start Process, but Switch Process can be used to activate a different process. Using Run Process does not affect the active process.
The keywords that operate on started processes will use the active process by default, but it is possible to explicitly select a different process using the
handle
argument. The handle can be analias
explicitly given to Start Process or the process object returned by it.= Result object =
Run Process, Wait For Process and Terminate Process keywords return a result object that contains information about the process execution as its attributes. The same result object, or some of its attributes, can also be get using Get Process Result keyword. Attributes available in the object are documented in the table below.
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
Considering
OFF
and0
false is new in Robot Framework 3.1.= Example =
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
TERMINATE_TIMEOUT
= 30¶
-
KILL_TIMEOUT
= 10¶
-
run_process
(command, *arguments, **configuration)[source]¶ Runs a process and waits for it to complete.
command
and*arguments
specify the command to execute and arguments passed to it. See Specifying command and arguments for more details.**configuration
contains additional configuration related to starting processes and waiting for them to finish. See Process configuration for more details about configuration related to starting processes. Configuration related to waiting for processes consists oftimeout
andon_timeout
arguments that have same semantics as with Wait For Process keyword. By default there is no timeout, and if timeout is defined the default action on timeout isterminate
.Returns a result object containing information about the execution.
Note that possible equal signs in
*arguments
must be escaped with a backslash (e.g.name\=value
) to avoid them to be passed in as**configuration
.This keyword does not change the active process.
-
start_process
(command, *arguments, **configuration)[source]¶ Starts a new process on background.
See Specifying command and arguments and Process configuration for more information about the arguments, and Run Process keyword for related examples.
Makes the started process new active process. Returns the created [https://docs.python.org/3/library/subprocess.html#popen-constructor | subprocess.Popen] object which can be be used later to active this process.
Popen
attributes likepid
can also be accessed directly.Processes are started so that they create a new process group. This allows terminating and sending signals to possible child processes.
Start process and wait for it to end later using alias:
Use returned
Popen
object:Use started process in a pipeline with another process:
Returning a
subprocess.Popen
object is new in Robot Framework 5.0. Earlier versions returned a generic handle and getting the process object required using Get Process Object separately.
-
is_process_running
(handle=None)[source]¶ Checks is the process running or not.
If
handle
is not given, uses the current active process.Returns
True
if the process is still running andFalse
otherwise.
-
process_should_be_running
(handle=None, error_message='Process is not running.')[source]¶ Verifies that the process is running.
If
handle
is not given, uses the current active process.Fails if the process has stopped.
-
process_should_be_stopped
(handle=None, error_message='Process is running.')[source]¶ Verifies that the process is not running.
If
handle
is not given, uses the current active process.Fails if the process is still running.
-
wait_for_process
(handle=None, timeout=None, on_timeout='continue')[source]¶ Waits for the process to complete or to reach the given timeout.
The process to wait for must have been started earlier with Start Process. If
handle
is not given, uses the current active process.timeout
defines the maximum time to wait for the process. It can be given in [http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format| various time formats] supported by Robot Framework, for example,42
,42 s
, or1 minute 30 seconds
. The timeout is ignored if it is PythonNone
(default), stringNONE
(case-insensitively), zero, or negative.on_timeout
defines what to do if the timeout occurs. Possible values and corresponding actions are explained in the table below. Notice that reaching the timeout never fails the test.See Terminate Process keyword for more details how processes are terminated and killed.
If the process ends before the timeout or it is terminated or killed, this keyword returns a result object containing information about the execution. If the process is left running, Python
None
is returned instead.Ignoring timeout if it is string
NONE
, zero, or negative is new in Robot Framework 3.2.
-
terminate_process
(handle=None, kill=False)[source]¶ Stops the process gracefully or forcefully.
If
handle
is not given, uses the current active process.By default first tries to stop the process gracefully. If the process does not stop in 30 seconds, or
kill
argument is given a true value, (see Boolean arguments) kills the process forcefully. Stops also all the child processes of the originally started process.Waits for the process to stop after terminating it. Returns a result object containing information about the execution similarly as Wait For Process.
On Unix-like machines graceful termination is done using
TERM (15)
signal and killing usingKILL (9)
. Use Send Signal To Process instead if you just want to send either of these signals without waiting for the process to stop.On Windows graceful termination is done using
CTRL_BREAK_EVENT
event and killing using Win32 API functionTerminateProcess()
.Limitations: - On Windows forceful kill only stops the main process, not possible
child processes.
-
terminate_all_processes
(kill=False)[source]¶ Terminates all still running processes started by this library.
This keyword can be used in suite teardown or elsewhere to make sure that all processes are stopped,
By default tries to terminate processes gracefully, but can be configured to forcefully kill them immediately. See Terminate Process that this keyword uses internally for more details.
-
send_signal_to_process
(signal, handle=None, group=False)[source]¶ Sends the given
signal
to the specified process.If
handle
is not given, uses the current active process.Signal can be specified either as an integer as a signal name. In the latter case it is possible to give the name both with or without
SIG
prefix, but names are case-sensitive. For example, all the examples below send signalINT (2)
:This keyword is only supported on Unix-like machines, not on Windows. What signals are supported depends on the system. For a list of existing signals on your system, see the Unix man pages related to signal handling (typically
man signal
orman 7 signal
).By default sends the signal only to the parent process, not to possible child processes started by it. Notice that when running processes in shell, the shell is the parent process and it depends on the system does the shell propagate the signal to the actual started process.
To send the signal to the whole process group,
group
argument can be set to any true value (see Boolean arguments).
-
get_process_id
(handle=None)[source]¶ Returns the process ID (pid) of the process as an integer.
If
handle
is not given, uses the current active process.Starting from Robot Framework 5.0, it is also possible to directly access the
pid
attribute of thesubprocess.Popen
object returned by Start Process like${process.pid}
.
-
get_process_object
(handle=None)[source]¶ Return the underlying
subprocess.Popen
object.If
handle
is not given, uses the current active process.Starting from Robot Framework 5.0, Start Process returns the created
subprocess.Popen
object, not a generic handle, making this keyword mostly redundant.
-
get_process_result
(handle=None, rc=False, stdout=False, stderr=False, stdout_path=False, stderr_path=False)[source]¶ Returns the specified result object or some of its attributes.
The given
handle
specifies the process whose results should be returned. If nohandle
is given, results of the current active process are returned. In either case, the process must have been finishes before this keyword can be used. In practice this means that processes started with Start Process must be finished either with Wait For Process or Terminate Process before using this keyword.If no other arguments than the optional
handle
are given, a whole result object is returned. If one or more of the other arguments are given any true value, only the specified attributes of the result object are returned. These attributes are always returned in the same order as arguments are specified in the keyword signature. See Boolean arguments section for more details about true and false values.Although getting results of a previously executed process can be handy in general, the main use case for this keyword is returning results over the remote library interface. The remote interface does not support returning the whole result object, but individual attributes can be returned without problems.
-
switch_process
(handle)[source]¶ Makes the specified process the current active process.
The handle can be an identifier returned by Start Process or the
alias
given to it explicitly.
-
split_command_line
(args, escaping=False)[source]¶ Splits command line string into a list of arguments.
String is split from spaces, but argument surrounded in quotes may contain spaces in them.
If
escaping
is given a true value, then backslash is treated as an escape character. It can escape unquoted spaces, quotes inside quotes, and so on, but it also requires using doubling backslashes in Windows paths and elsewhere.
-
join_command_line
(*args)[source]¶ Joins arguments into one command line string.
In resulting command line string arguments are delimited with a space, arguments containing spaces are surrounded with quotes, and possible quotes are escaped with a backslash.
If this keyword is given only one argument and that is a list-like object, then the values of that list are joined instead.
robot.libraries.Remote module¶
-
class
robot.libraries.Remote.
Remote
(uri='http://127.0.0.1:8270', timeout=None)[source]¶ Bases:
object
Connects to a remote server at
uri
.Optional
timeout
can be used to specify a timeout to wait when initially connecting to the server and if a connection accidentally closes. Timeout can be given as seconds (e.g.60
) or using Robot Framework time format (e.g.60s
,2 minutes 10 seconds
).The default timeout is typically several minutes, but it depends on the operating system and its configuration. Notice that setting a timeout that is shorter than keyword execution time will interrupt the keyword.
-
ROBOT_LIBRARY_SCOPE
= 'TEST SUITE'¶
-
-
class
robot.libraries.Remote.
ArgumentCoercer
[source]¶ Bases:
object
-
binary
= re.compile('[\x00-\x08\x0b\x0c\x0e-\x1f]')¶
-
non_ascii
= re.compile('[\x80-ÿ]')¶
-
-
class
robot.libraries.Remote.
TimeoutHTTPTransport
(use_datetime=0, timeout=None)[source]¶ Bases:
xmlrpc.client.Transport
-
accept_gzip_encoding
= True¶
-
close
()¶
-
encode_threshold
= None¶
-
get_host_info
(host)¶
-
getparser
()¶
-
parse_response
(response)¶
-
request
(host, handler, request_body, verbose=False)¶
-
send_content
(connection, request_body)¶
-
send_headers
(connection, headers)¶
-
send_request
(host, handler, request_body, debug)¶
-
single_request
(host, handler, request_body, verbose=False)¶
-
user_agent
= 'Python-xmlrpc/3.11'¶
-
-
class
robot.libraries.Remote.
TimeoutHTTPSTransport
(use_datetime=0, timeout=None)[source]¶ Bases:
robot.libraries.Remote.TimeoutHTTPTransport
-
accept_gzip_encoding
= True¶
-
close
()¶
-
encode_threshold
= None¶
-
get_host_info
(host)¶
-
getparser
()¶
-
make_connection
(host)¶
-
parse_response
(response)¶
-
request
(host, handler, request_body, verbose=False)¶
-
send_content
(connection, request_body)¶
-
send_headers
(connection, headers)¶
-
send_request
(host, handler, request_body, debug)¶
-
single_request
(host, handler, request_body, verbose=False)¶
-
user_agent
= 'Python-xmlrpc/3.11'¶
-
robot.libraries.Reserved module¶
robot.libraries.Screenshot module¶
-
class
robot.libraries.Screenshot.
Screenshot
(screenshot_directory=None, screenshot_module=None)[source]¶ Bases:
object
Library for taking screenshots on the machine where tests are executed.
Taking the actual screenshot requires a suitable tool or module that may need to be installed separately. Taking screenshots also requires tests to be run with a physical or virtual display.
== Table of contents ==
%TOC%
= Supported screenshot taking tools and modules =
How screenshots are taken depends on the operating system. On OSX screenshots are taken using the built-in
screencapture
utility. On other operating systems you need to have one of the following tools or Python modules installed. You can specify the tool/module to use when importing the library. If no tool or module is specified, the first one found will be used.- wxPython :: http://wxpython.org :: Generic Python GUI toolkit.
- PyGTK :: http://pygtk.org :: This module is available by default on most Linux distributions.
- Pillow :: http://python-pillow.github.io :: Only works on Windows. Also the original PIL package is supported.
- Scrot :: http://en.wikipedia.org/wiki/Scrot :: Not used on Windows.
Install with
apt-get install scrot
or similar.
= Where screenshots are saved =
By default screenshots are saved into the same directory where the Robot Framework log file is written. If no log is created, screenshots are saved into the directory where the XML output file is written.
It is possible to specify a custom location for screenshots using
screenshot_directory
argument when importing the library and using Set Screenshot Directory keyword during execution. It is also possible to save screenshots using an absolute path.= ScreenCapLibrary =
[https://github.com/mihaiparvu/ScreenCapLibrary|ScreenCapLibrary] is an external Robot Framework library that can be used as an alternative, which additionally provides support for multiple formats, adjusting the quality, using GIFs and video capturing.
Configure where screenshots are saved.
If
screenshot_directory
is not given, screenshots are saved into same directory as the log file. The directory can also be set using Set Screenshot Directory keyword.screenshot_module
specifies the module or tool to use when using this library outside OSX. Possible values arewxPython
,PyGTK
,PIL
andscrot
, case-insensitively. If no value is given, the first module/tool found is used in that order.-
ROBOT_LIBRARY_SCOPE
= 'TEST SUITE'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
set_screenshot_directory
(path)[source]¶ Sets the directory where screenshots are saved.
It is possible to use
/
as a path separator in all operating systems. Path to the old directory is returned.The directory can also be set in importing.
-
take_screenshot
(name='screenshot', width='800px')[source]¶ Takes a screenshot in JPEG format and embeds it into the log file.
Name of the file where the screenshot is stored is derived from the given
name
. If thename
ends with extension.jpg
or.jpeg
, the screenshot will be stored with that exact name. Otherwise a unique name is created by adding an underscore, a running index and an extension to thename
.The name will be interpreted to be relative to the directory where the log file is written. It is also possible to use absolute paths. Using
/
as a path separator works in all operating systems.width
specifies the size of the screenshot in the log file.The path where the screenshot is saved is returned.
robot.libraries.String module¶
-
class
robot.libraries.String.
String
[source]¶ Bases:
object
A library for string manipulation and verification.
String
is Robot Framework’s standard library for manipulating strings (e.g. Replace String Using Regexp, Split To Lines) and verifying their contents (e.g. Should Be String).Following keywords from
BuiltIn
library can also be used with strings:- Catenate
- Get Length
- Length Should Be
- Should (Not) Be Empty
- Should (Not) Be Equal (As Strings/Integers/Numbers)
- Should (Not) Match (Regexp)
- Should (Not) Contain
- Should (Not) Start With
- Should (Not) End With
- Convert To String
- Convert To Bytes
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
convert_to_lower_case
(string)[source]¶ Converts string to lower case.
Uses Python’s standard [https://docs.python.org/library/stdtypes.html#str.lower|lower()] method.
-
convert_to_upper_case
(string)[source]¶ Converts string to upper case.
Uses Python’s standard [https://docs.python.org/library/stdtypes.html#str.upper|upper()] method.
-
convert_to_title_case
(string, exclude=None)[source]¶ Converts string to title case.
Uses the following algorithm:
- Split the string to words from whitespace characters (spaces, newlines, etc.).
- Exclude words that are not all lower case. This preserves, for example, “OK” and “iPhone”.
- Exclude also words listed in the optional
exclude
argument. - Title case the first alphabetical character of each word that has not been excluded.
- Join all words together so that original whitespace is preserved.
Explicitly excluded words can be given as a list or as a string with words separated by a comma and an optional space. Excluded words are actually considered to be regular expression patterns, so it is possible to use something like “example[.!?]?” to match the word “example” on it own and also if followed by “.”, “!” or “?”. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.
The reason this keyword does not use Python’s standard [https://docs.python.org/library/stdtypes.html#str.title|title()] method is that it can yield undesired results, for example, if strings contain upper case letters or special characters like apostrophes. It would, for example, convert “it’s an OK iPhone” to “It’S An Ok Iphone”.
New in Robot Framework 3.2.
-
encode_string_to_bytes
(string, encoding, errors='strict')[source]¶ Encodes the given Unicode
string
to bytes using the givenencoding
.errors
argument controls what to do if encoding some characters fails. All values accepted byencode
method in Python are valid, but in practice the following values are most useful:strict
: fail if characters cannot be encoded (default)ignore
: ignore characters that cannot be encodedreplace
: replace characters that cannot be encoded with a replacement character
Use Convert To Bytes in
BuiltIn
if you want to create bytes based on character or integer sequences. Use Decode Bytes To String if you need to convert byte strings to Unicode strings and Convert To String inBuiltIn
if you need to convert arbitrary objects to Unicode.
-
decode_bytes_to_string
(bytes, encoding, errors='strict')[source]¶ Decodes the given
bytes
to a Unicode string using the givenencoding
.errors
argument controls what to do if decoding some bytes fails. All values accepted bydecode
method in Python are valid, but in practice the following values are most useful:strict
: fail if characters cannot be decoded (default)ignore
: ignore characters that cannot be decodedreplace
: replace characters that cannot be decoded with a replacement character
Use Encode String To Bytes if you need to convert Unicode strings to byte strings, and Convert To String in
BuiltIn
if you need to convert arbitrary objects to Unicode strings.
-
format_string
(template, *positional, **named)[source]¶ Formats a
template
using the givenpositional
andnamed
arguments.The template can be either be a string or an absolute path to an existing file. In the latter case the file is read and its contents are used as the template. If the template file contains non-ASCII characters, it must be encoded using UTF-8.
The template is formatted using Python’s [https://docs.python.org/library/string.html#format-string-syntax|format string syntax]. Placeholders are marked using
{}
with possible field name and format specification inside. Literal curly braces can be inserted by doubling them like {{ and }}.New in Robot Framework 3.1.
-
split_to_lines
(string, start=0, end=None)[source]¶ Splits the given string to lines.
It is possible to get only a selection of lines from
start
toend
so thatstart
index is inclusive andend
is exclusive. Line numbering starts from 0, and it is possible to use negative indices to refer to lines from the end.Lines are returned without the newlines. The number of returned lines is automatically logged.
Use Get Line if you only need to get a single line.
-
get_line
(string, line_number)[source]¶ Returns the specified line from the given
string
.Line numbering starts from 0 and it is possible to use negative indices to refer to lines from the end. The line is returned without the newline character.
Use Split To Lines if all lines are needed.
-
get_lines_containing_string
(string, pattern, case_insensitive=False)[source]¶ Returns lines of the given
string
that contain thepattern
.The
pattern
is always considered to be a normal string, not a glob or regexp pattern. A line matches if thepattern
is found anywhere on it.The match is case-sensitive by default, but giving
case_insensitive
a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal tofalse
,none
orno
. If the value is not a string, its truth value is got directly in Python.Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged.
See Get Lines Matching Pattern and Get Lines Matching Regexp if you need more complex pattern matching.
-
get_lines_matching_pattern
(string, pattern, case_insensitive=False)[source]¶ Returns lines of the given
string
that match thepattern
.The
pattern
is a _glob pattern_ where:A line matches only if it matches the
pattern
fully.The match is case-sensitive by default, but giving
case_insensitive
a true value makes it case-insensitive. The value is considered true if it is a non-empty string that is not equal tofalse
,none
orno
. If the value is not a string, its truth value is got directly in Python.Lines are returned as one string catenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged.
See Get Lines Matching Regexp if you need more complex patterns and Get Lines Containing String if searching literal strings is enough.
-
get_lines_matching_regexp
(string, pattern, partial_match=False, flags=None)[source]¶ Returns lines of the given
string
that match the regexppattern
.See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.
Lines match only if they match the pattern fully by default, but partial matching can be enabled by giving the
partial_match
argument a true value. The value is considered true if it is a non-empty string that is not equal tofalse
,none
orno
. If the value is not a string, its truth value is got directly in Python.If the pattern is empty, it matches only empty lines by default. When partial matching is enabled, empty pattern matches all lines.
Possible flags altering how the expression is parsed (e.g.
re.IGNORECASE
,re.VERBOSE
) can be given using theflags
argument (e.g.flags=IGNORECASE | VERBOSE
) or embedded to the pattern (e.g.(?ix)pattern
).Lines are returned as one string concatenated back together with newlines. Possible trailing newline is never returned. The number of matching lines is automatically logged.
See Get Lines Matching Pattern and Get Lines Containing String if you do not need the full regular expression powers (and complexity).
The
flags
argument is new in Robot Framework 6.0.
-
get_regexp_matches
(string, pattern, *groups, flags=None)[source]¶ Returns a list of all non-overlapping matches in the given string.
string
is the string to find matches from andpattern
is the regular expression. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.If no groups are used, the returned list contains full matches. If one group is used, the list contains only contents of that group. If multiple groups are used, the list contains tuples that contain individual group contents. All groups can be given as indexes (starting from 1) and named groups also as names.
Possible flags altering how the expression is parsed (e.g.
re.IGNORECASE
,re.MULTILINE
) can be given using theflags
argument (e.g.flags=IGNORECASE | MULTILINE
) or embedded to the pattern (e.g.(?im)pattern
).The
flags
argument is new in Robot Framework 6.0.
-
replace_string
(string, search_for, replace_with, count=-1)[source]¶ Replaces
search_for
in the givenstring
withreplace_with
.search_for
is used as a literal string. See Replace String Using Regexp if more powerful pattern matching is needed. If you need to just remove a string see Remove String.If the optional argument
count
is given, only that many occurrences from left are replaced. Negativecount
means that all occurrences are replaced (default behaviour) and zero means that nothing is done.A modified version of the string is returned and the original string is not altered.
-
replace_string_using_regexp
(string, pattern, replace_with, count=-1, flags=None)[source]¶ Replaces
pattern
in the givenstring
withreplace_with
.This keyword is otherwise identical to Replace String, but the
pattern
to search for is considered to be a regular expression. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.Possible flags altering how the expression is parsed (e.g.
re.IGNORECASE
,re.MULTILINE
) can be given using theflags
argument (e.g.flags=IGNORECASE | MULTILINE
) or embedded to the pattern (e.g.(?im)pattern
).If you need to just remove a string see Remove String Using Regexp.
The
flags
argument is new in Robot Framework 6.0.
-
remove_string
(string, *removables)[source]¶ Removes all
removables
from the givenstring
.removables
are used as literal strings. Each removable will be matched to a temporary string from which preceding removables have been already removed. See second example below.Use Remove String Using Regexp if more powerful pattern matching is needed. If only a certain number of matches should be removed, Replace String or Replace String Using Regexp can be used.
A modified version of the string is returned and the original string is not altered.
-
remove_string_using_regexp
(string, *patterns, flags=None)[source]¶ Removes
patterns
from the givenstring
.This keyword is otherwise identical to Remove String, but the
patterns
to search for are considered to be a regular expression. See Replace String Using Regexp for more information about the regular expression syntax. That keyword can also be used if there is a need to remove only a certain number of occurrences.Possible flags altering how the expression is parsed (e.g.
re.IGNORECASE
,re.MULTILINE
) can be given using theflags
argument (e.g.flags=IGNORECASE | MULTILINE
) or embedded to the pattern (e.g.(?im)pattern
).The
flags
argument is new in Robot Framework 6.0.
-
split_string
(string, separator=None, max_split=-1)[source]¶ Splits the
string
usingseparator
as a delimiter string.If a
separator
is not given, any whitespace string is a separator. In that case also possible consecutive whitespace as well as leading and trailing whitespace is ignored.Split words are returned as a list. If the optional
max_split
is given, at mostmax_split
splits are done, and the returned list will have maximummax_split + 1
elements.See Split String From Right if you want to start splitting from right, and Fetch From Left and Fetch From Right if you only want to get first/last part of the string.
-
split_string_from_right
(string, separator=None, max_split=-1)[source]¶ Splits the
string
usingseparator
starting from right.Same as Split String, but splitting is started from right. This has an effect only when
max_split
is given.
-
fetch_from_left
(string, marker)[source]¶ Returns contents of the
string
before the first occurrence ofmarker
.If the
marker
is not found, whole string is returned.See also Fetch From Right, Split String and Split String From Right.
-
fetch_from_right
(string, marker)[source]¶ Returns contents of the
string
after the last occurrence ofmarker
.If the
marker
is not found, whole string is returned.See also Fetch From Left, Split String and Split String From Right.
-
generate_random_string
(length=8, chars='[LETTERS][NUMBERS]')[source]¶ Generates a string with a desired
length
from the givenchars
.length
can be given as a number, a string representation of a number, or as a range of numbers, such as5-10
. When a range of values is given the range will be selected by random within the range.The population sequence
chars
contains the characters to use when generating the random string. It can contain any characters, and it is possible to use special markers explained in the table below:Giving
length
as a range of values is new in Robot Framework 5.0.
-
get_substring
(string, start, end=None)[source]¶ Returns a substring from
start
index toend
index.The
start
index is inclusive andend
is exclusive. Indexing starts from 0, and it is possible to use negative indices to refer to characters from the end.
-
strip_string
(string, mode='both', characters=None)[source]¶ Remove leading and/or trailing whitespaces from the given string.
mode
is eitherleft
to remove leading characters,right
to remove trailing characters,both
(default) to remove the characters from both sides of the string ornone
to return the unmodified string.If the optional
characters
is given, it must be a string and the characters in the string will be stripped in the string. Please note, that this is not a substring to be removed but a list of characters, see the example below.
-
should_be_string
(item, msg=None)[source]¶ Fails if the given
item
is not a string.The default error message can be overridden with the optional
msg
argument.
-
should_not_be_string
(item, msg=None)[source]¶ Fails if the given
item
is a string.The default error message can be overridden with the optional
msg
argument.
-
should_be_unicode_string
(item, msg=None)[source]¶ Fails if the given
item
is not a Unicode string.On Python 3 this keyword behaves exactly the same way Should Be String. That keyword should be used instead and this keyword will be deprecated.
-
should_be_byte_string
(item, msg=None)[source]¶ Fails if the given
item
is not a byte string.Use Should Be String if you want to verify the
item
is a string.The default error message can be overridden with the optional
msg
argument.
-
should_be_lower_case
(string, msg=None)[source]¶ Fails if the given
string
is not in lower case.For example,
'string'
and'with specials!'
would pass, and'String'
,''
and' '
would fail.The default error message can be overridden with the optional
msg
argument.See also Should Be Upper Case and Should Be Title Case.
-
should_be_upper_case
(string, msg=None)[source]¶ Fails if the given
string
is not in upper case.For example,
'STRING'
and'WITH SPECIALS!'
would pass, and'String'
,''
and' '
would fail.The default error message can be overridden with the optional
msg
argument.See also Should Be Title Case and Should Be Lower Case.
-
should_be_title_case
(string, msg=None, exclude=None)[source]¶ Fails if given
string
is not title.string
is a title cased string if there is at least one upper case letter in each word.For example,
'This Is Title'
and'OK, Give Me My iPhone'
would pass.'all words lower'
and'Word In lower'
would fail.This logic changed in Robot Framework 4.0 to be compatible with Convert to Title Case. See Convert to Title Case for title case algorithm and reasoning.
The default error message can be overridden with the optional
msg
argument.Words can be explicitly excluded with the optional
exclude
argument.Explicitly excluded words can be given as a list or as a string with words separated by a comma and an optional space. Excluded words are actually considered to be regular expression patterns, so it is possible to use something like “example[.!?]?” to match the word “example” on it own and also if followed by “.”, “!” or “?”. See BuiltIn.Should Match Regexp for more information about Python regular expression syntax in general and how to use it in Robot Framework data in particular.
See also Should Be Upper Case and Should Be Lower Case.
robot.libraries.Telnet module¶
-
class
robot.libraries.Telnet.
Telnet
(timeout='3 seconds', newline='CRLF', prompt=None, prompt_is_regexp=False, encoding='UTF-8', encoding_errors='ignore', default_log_level='INFO', window_size=None, environ_user=None, terminal_emulation=False, terminal_type=None, telnetlib_log_level='TRACE', connection_timeout=None)[source]¶ Bases:
object
A library providing communication over Telnet connections.
Telnet
is Robot Framework’s standard library that makes it possible to connect to Telnet servers and execute commands on the opened connections.== Table of contents ==
%TOC%
= Connections =
The first step of using
Telnet
is opening a connection with Open Connection keyword. Typically the next step is logging in with Login keyword, and in the end the opened connection can be closed with Close Connection.It is possible to open multiple connections and switch the active one using Switch Connection. Close All Connections can be used to close all the connections, which is especially useful in suite teardowns to guarantee that all connections are always closed.
= Writing and reading =
After opening a connection and possibly logging in, commands can be executed or text written to the connection for other reasons using Write and Write Bare keywords. The main difference between these two is that the former adds a [#Configuration|configurable newline] after the text automatically.
After writing something to the connection, the resulting output can be read using Read, Read Until, Read Until Regexp, and Read Until Prompt keywords. Which one to use depends on the context, but the latest one is often the most convenient.
As a convenience when running a command, it is possible to use Execute Command that simply uses Write and Read Until Prompt internally. Write Until Expected Output is useful if you need to wait until writing something produces a desired output.
Written and read text is automatically encoded/decoded using a [#Configuration|configured encoding].
The ANSI escape codes, like cursor movement and color codes, are normally returned as part of the read operation. If an escape code occurs in middle of a search pattern it may also prevent finding the searched string. Terminal emulation can be used to process these escape codes as they would be if a real terminal would be in use.
= Configuration =
Many aspects related the connections can be easily configured either globally or per connection basis. Global configuration is done when [#Importing|library is imported], and these values can be overridden per connection by Open Connection or with setting specific keywords Set Timeout, Set Newline, Set Prompt, Set Encoding, Set Default Log Level and Set Telnetlib Log Level.
Values of
environ_user
,window_size
,terminal_emulation
, andterminal_type
can not be changed after opening the connection.== Timeout ==
Timeout defines how long is the maximum time to wait when reading output. It is used internally by Read Until, Read Until Regexp, Read Until Prompt, and Login keywords. The default value is 3 seconds.
== Connection Timeout ==
Connection Timeout defines how long is the maximum time to wait when opening the telnet connection. It is used internally by Open Connection. The default value is the system global default timeout.
== Newline ==
Newline defines which line separator Write keyword should use. The default value is
CRLF
that is typically used by Telnet connections.Newline can be given either in escaped format using
\n
and\r
or with specialLF
andCR
syntax.== Prompt ==
Often the easiest way to read the output of a command is reading all the output until the next prompt with Read Until Prompt. It also makes it easier, and faster, to verify did Login succeed.
Prompt can be specified either as a normal string or a regular expression. The latter is especially useful if the prompt changes as a result of the executed commands. Prompt can be set to be a regular expression by giving
prompt_is_regexp
argument a true value (see Boolean arguments).== Encoding ==
To ease handling text containing non-ASCII characters, all written text is encoded and read text decoded by default. The default encoding is UTF-8 that works also with ASCII. Encoding can be disabled by using a special encoding value
NONE
. This is mainly useful if you need to get the bytes received from the connection as-is.Notice that when writing to the connection, only Unicode strings are encoded using the defined encoding. Byte strings are expected to be already encoded correctly. Notice also that normal text in data is passed to the library as Unicode and you need to use variables to use bytes.
It is also possible to configure the error handler to use if encoding or decoding characters fails. Accepted values are the same that encode/decode functions in Python strings accept. In practice the following values are the most useful:
ignore
: ignore characters that cannot be encoded (default)strict
: fail if characters cannot be encodedreplace
: replace characters that cannot be encoded with a replacement character
== Default log level ==
Default log level specifies the log level keywords use for logging unless they are given an explicit log level. The default value is
INFO
, and changing it, for example, toDEBUG
can be a good idea if there is lot of unnecessary output that makes log files big.== Terminal type ==
By default the Telnet library does not negotiate any specific terminal type with the server. If a specific terminal type, for example
vt100
, is desired, the terminal type can be configured in importing and with Open Connection.== Window size ==
Window size for negotiation with the server can be configured when importing the library and with Open Connection.
== USER environment variable ==
Telnet protocol allows the
USER
environment variable to be sent when connecting to the server. On some servers it may happen that there is no login prompt, and on those cases this configuration option will allow still to define the desired username. The optionenviron_user
can be used in importing and with Open Connection.= Terminal emulation =
Telnet library supports terminal emulation with [http://pyte.readthedocs.io|Pyte]. Terminal emulation will process the output in a virtual screen. This means that ANSI escape codes, like cursor movements, and also control characters, like carriage returns and backspaces, have the same effect on the result as they would have on a normal terminal screen. For example the sequence
acdc\x1b[3Dbba
will result in outputabba
.Terminal emulation is taken into use by giving
terminal_emulation
argument a true value (see Boolean arguments) either in the library initialization or with Open Connection.As Pyte approximates vt-style terminal, you may also want to set the terminal type as
vt100
. We also recommend that you increase the window size, as the terminal emulation will break all lines that are longer than the window row length.When terminal emulation is used, the newline and encoding can not be changed anymore after opening the connection.
As a prerequisite for using terminal emulation, you need to have Pyte installed. Due to backwards incompatible changes in Pyte, different Robot Framework versions support different Pyte versions:
- Pyte 0.6 and newer are supported by Robot Framework 3.0.3.
Latest Pyte version can be installed (or upgraded) with
pip install --upgrade pyte
. - Pyte 0.5.2 and older are supported by Robot Framework 3.0.2 and earlier.
Pyte 0.5.2 can be installed with
pip install pyte==0.5.2
.
= Logging =
All keywords that read something log the output. These keywords take the log level to use as an optional argument, and if no log level is specified they use the [#Configuration|configured] default value.
The valid log levels to use are
TRACE
,DEBUG
,INFO
(default), andWARN
. Levels belowINFO
are not shown in log files by default whereas warnings are shown more prominently.The [http://docs.python.org/library/telnetlib.html|telnetlib module] used by this library has a custom logging system for logging content it sends and receives. By default these messages are written using
TRACE
level, but the level is configurable with thetelnetlib_log_level
option either in the library initialization, to the Open Connection or by using the Set Telnetlib Log Level keyword to the active connection. Special levelNONE
con be used to disable the logging altogether.= Time string format =
Timeouts and other times used must be given as a time string using format like
15 seconds
or1min 10s
. If the timeout is given as just a number, for example,10
or1.5
, it is considered to be seconds. The time string format is described in more detail in an appendix of [http://robotframework.org/robotframework/#user-guide|Robot Framework User Guide].= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
Considering string
NONE
false is new in Robot Framework 3.0.3 and considering alsoOFF
and0
false is new in Robot Framework 3.1.Telnet library can be imported with optional configuration parameters.
Configuration parameters are used as default values when new connections are opened with Open Connection keyword. They can also be overridden after opening the connection using the Set … keywords. See these keywords as well as Configuration, Terminal emulation and Logging sections above for more information about these parameters and their possible values.
See Time string format and Boolean arguments sections for information about using arguments accepting times and Boolean values, respectively.
-
ROBOT_LIBRARY_SCOPE
= 'SUITE'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
open_connection
(host, alias=None, port=23, timeout=None, newline=None, prompt=None, prompt_is_regexp=False, encoding=None, encoding_errors=None, default_log_level=None, window_size=None, environ_user=None, terminal_emulation=None, terminal_type=None, telnetlib_log_level=None, connection_timeout=None)[source]¶ Opens a new Telnet connection to the given host and port.
The
timeout
,newline
,prompt
,prompt_is_regexp
,encoding
,default_log_level
,window_size
,environ_user
,terminal_emulation
,terminal_type
andtelnetlib_log_level
arguments get default values when the library is [#Importing|imported]. Setting them here overrides those values for the opened connection. See Configuration, Terminal emulation and Logging sections for more information about these parameters and their possible values.Possible already opened connections are cached and it is possible to switch back to them using Switch Connection keyword. It is possible to switch either using explicitly given
alias
or using index returned by this keyword. Indexing starts from 1 and is reset back to it by Close All Connections keyword.
-
switch_connection
(index_or_alias)[source]¶ Switches between active connections using an index or an alias.
Aliases can be given to Open Connection keyword which also always returns the connection index.
This keyword returns the index of previous active connection.
The example above expects that there were no other open connections when opening the first one, because it used index
1
when switching to the connection later. If you are not sure about that, you can store the index into a variable as shown below.
-
close_all_connections
()[source]¶ Closes all open connections and empties the connection cache.
If multiple connections are opened, this keyword should be used in a test or suite teardown to make sure that all connections are closed. It is not an error if some of the connections have already been closed by Close Connection.
After this keyword, new indexes returned by Open Connection keyword are reset to 1.
-
class
robot.libraries.Telnet.
TelnetConnection
(host=None, port=23, timeout=3.0, newline='CRLF', prompt=None, prompt_is_regexp=False, encoding='UTF-8', encoding_errors='ignore', default_log_level='INFO', window_size=None, environ_user=None, terminal_emulation=False, terminal_type=None, telnetlib_log_level='TRACE', connection_timeout=None)[source]¶ Bases:
telnetlib.Telnet
-
NEW_ENVIRON_IS
= b'\x00'¶
-
NEW_ENVIRON_VAR
= b'\x00'¶
-
NEW_ENVIRON_VALUE
= b'\x01'¶
-
INTERNAL_UPDATE_FREQUENCY
= 0.03¶
-
set_timeout
(timeout)[source]¶ Sets the timeout used for waiting output in the current connection.
Read operations that expect some output to appear (Read Until, Read Until Regexp, Read Until Prompt, Login) use this timeout and fail if the expected output does not appear before this timeout expires.
The
timeout
must be given in time string format. The old timeout is returned and can be used to restore the timeout later.See Configuration section for more information about global and connection specific configuration.
-
set_newline
(newline)[source]¶ Sets the newline used by Write keyword in the current connection.
The old newline is returned and can be used to restore the newline later. See Set Timeout for a similar example.
If terminal emulation is used, the newline can not be changed on an open connection.
See Configuration section for more information about global and connection specific configuration.
-
set_prompt
(prompt, prompt_is_regexp=False)[source]¶ Sets the prompt used by Read Until Prompt and Login in the current connection.
If
prompt_is_regexp
is given a true value (see Boolean arguments), the givenprompt
is considered to be a regular expression.The old prompt is returned and can be used to restore the prompt later.
See the documentation of [http://docs.python.org/library/re.html|Python re module] for more information about the supported regular expression syntax. Notice that possible backslashes need to be escaped in Robot Framework data.
See Configuration section for more information about global and connection specific configuration.
-
set_encoding
(encoding=None, errors=None)[source]¶ Sets the encoding to use for writing and reading in the current connection.
The given
encoding
specifies the encoding to use when written/read text is encoded/decoded, anderrors
specifies the error handler to use if encoding/decoding fails. Either of these can be omitted and in that case the old value is not affected. Use stringNONE
to disable encoding altogether.See Configuration section for more information about encoding and error handlers, as well as global and connection specific configuration in general.
The old values are returned and can be used to restore the encoding and the error handler later. See Set Prompt for a similar example.
If terminal emulation is used, the encoding can not be changed on an open connection.
-
set_telnetlib_log_level
(level)[source]¶ Sets the log level used for logging in the underlying
telnetlib
.Note that
telnetlib
can be very noisy thus using the levelNONE
can shutdown the messages generated by this library.
-
set_default_log_level
(level)[source]¶ Sets the default log level used for logging in the current connection.
The old default log level is returned and can be used to restore the log level later.
See Configuration section for more information about global and connection specific configuration.
-
close_connection
(loglevel=None)[source]¶ Closes the current Telnet connection.
Remaining output in the connection is read, logged, and returned. It is not an error to close an already closed connection.
Use Close All Connections if you want to make sure all opened connections are closed.
See Logging section for more information about log levels.
-
login
(username, password, login_prompt='login: ', password_prompt='Password: ', login_timeout='1 second', login_incorrect='Login incorrect')[source]¶ Logs in to the Telnet server with the given user information.
This keyword reads from the connection until the
login_prompt
is encountered and then types the givenusername
. Then it reads until thepassword_prompt
and types the givenpassword
. In both cases a newline is appended automatically and the connection specific timeout used when waiting for outputs.How logging status is verified depends on whether a prompt is set for this connection or not:
1) If the prompt is set, this keyword reads the output until the prompt is found using the normal timeout. If no prompt is found, login is considered failed and also this keyword fails. Note that in this case both
login_timeout
andlogin_incorrect
arguments are ignored.2) If the prompt is not set, this keywords sleeps until
login_timeout
and then reads all the output available on the connection. If the output containslogin_incorrect
text, login is considered failed and also this keyword fails.See Configuration section for more information about setting newline, timeout, and prompt.
-
write
(text, loglevel=None)[source]¶ Writes the given text plus a newline into the connection.
The newline character sequence to use can be [#Configuration|configured] both globally and per connection basis. The default value is
CRLF
.This keyword consumes the written text, until the added newline, from the output and logs and returns it. The given text itself must not contain newlines. Use Write Bare instead if either of these features causes a problem.
Note: This keyword does not return the possible output of the executed command. To get the output, one of the Read … keywords must be used. See Writing and reading section for more details.
See Logging section for more information about log levels.
-
write_bare
(text)[source]¶ Writes the given text, and nothing else, into the connection.
This keyword does not append a newline nor consume the written text. Use Write if these features are needed.
-
write_until_expected_output
(text, expected, timeout, retry_interval, loglevel=None)[source]¶ Writes the given
text
repeatedly, untilexpected
appears in the output.text
is written without appending a newline and it is consumed from the output before trying to findexpected
. Ifexpected
does not appear in the output withintimeout
, this keyword fails.retry_interval
defines the time to waitexpected
to appear before writing thetext
again. Consuming the writtentext
is subject to the normal [#Configuration|configured timeout].Both
timeout
andretry_interval
must be given in time string format. See Logging section for more information about log levels.The above example writes command
ps -ef | grep myprocess\r\n
untilmyprocess
appears in the output. The command is written every 0.5 seconds and the keyword fails ifmyprocess
does not appear in the output in 5 seconds.
-
write_control_character
(character)[source]¶ Writes the given control character into the connection.
The control character is prepended with an IAC (interpret as command) character.
The following control character names are supported: BRK, IP, AO, AYT, EC, EL, NOP. Additionally, you can use arbitrary numbers to send any control character.
-
read
(loglevel=None)[source]¶ Reads everything that is currently available in the output.
Read output is both returned and logged. See Logging section for more information about log levels.
-
read_until
(expected, loglevel=None)[source]¶ Reads output until
expected
text is encountered.Text up to and including the match is returned and logged. If no match is found, this keyword fails. How much to wait for the output depends on the [#Configuration|configured timeout].
See Logging section for more information about log levels. Use Read Until Regexp if more complex matching is needed.
-
read_until_regexp
(*expected)[source]¶ Reads output until any of the
expected
regular expressions match.This keyword accepts any number of regular expressions patterns or compiled Python regular expression objects as arguments. Text up to and including the first match to any of the regular expressions is returned and logged. If no match is found, this keyword fails. How much to wait for the output depends on the [#Configuration|configured timeout].
If the last given argument is a [#Logging|valid log level], it is used as
loglevel
similarly as with Read Until keyword.See the documentation of [http://docs.python.org/library/re.html|Python re module] for more information about the supported regular expression syntax. Notice that possible backslashes need to be escaped in Robot Framework data.
-
read_until_prompt
(loglevel=None, strip_prompt=False)[source]¶ Reads output until the prompt is encountered.
This keyword requires the prompt to be [#Configuration|configured] either in importing or with Open Connection or Set Prompt keyword.
By default, text up to and including the prompt is returned and logged. If no prompt is found, this keyword fails. How much to wait for the output depends on the [#Configuration|configured timeout].
If you want to exclude the prompt from the returned output, set
strip_prompt
to a true value (see Boolean arguments). If your prompt is a regular expression, make sure that the expression spans the whole prompt, because only the part of the output that matches the regular expression is stripped away.See Logging section for more information about log levels.
-
execute_command
(command, loglevel=None, strip_prompt=False)[source]¶ Executes the given
command
and reads, logs, and returns everything until the prompt.This keyword requires the prompt to be [#Configuration|configured] either in importing or with Open Connection or Set Prompt keyword.
This is a convenience keyword that uses Write and Read Until Prompt internally. Following two examples are thus functionally identical:
See Logging section for more information about log levels and Read Until Prompt for more information about the
strip_prompt
parameter.
-
msg
(msg, *args)[source]¶ Print a debug message, when the debug level is > 0.
If extra arguments are present, they are substituted in the message using the standard string formatting operator.
-
close
()¶ Close the connection.
-
expect
(list, timeout=None)¶ Read until one from a list of a regular expressions matches.
The first argument is a list of regular expressions, either compiled (re.Pattern instances) or uncompiled (strings). The optional second argument is a timeout, in seconds; default is no timeout.
Return a tuple of three items: the index in the list of the first regular expression that matches; the re.Match object returned; and the text read up till and including the match.
If EOF is read and no text was read, raise EOFError. Otherwise, when nothing matches, return (-1, None, text) where text is the text received so far (may be the empty string if a timeout happened).
If a regular expression ends with a greedy match (e.g. ‘.*’) or if more than one expression can match the same input, the results are undeterministic, and may depend on the I/O timing.
-
fileno
()¶ Return the fileno() of the socket object used internally.
-
fill_rawq
()¶ Fill raw queue from exactly one recv() system call.
Block if no data is immediately available. Set self.eof when connection is closed.
-
get_socket
()¶ Return the socket object used internally.
-
interact
()¶ Interaction function, emulates a very dumb telnet client.
-
listener
()¶ Helper for mt_interact() – this executes in the other thread.
-
mt_interact
()¶ Multithreaded version of interact().
-
open
(host, port=0, timeout=<object object>)¶ Connect to a host.
The optional second argument is the port number, which defaults to the standard telnet port (23).
Don’t try to reopen an already connected instance.
-
process_rawq
()¶ Transfer from raw queue to cooked queue.
Set self.eof when connection is closed. Don’t block unless in the midst of an IAC sequence.
-
rawq_getchar
()¶ Get next char from raw queue.
Block if no data is immediately available. Raise EOFError when connection is closed.
-
read_all
()¶ Read all data until EOF; block until connection closed.
-
read_eager
()¶ Read readily available data.
Raise EOFError if connection closed and no cooked data available. Return b’’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.
-
read_lazy
()¶ Process and return data that’s already in the queues (lazy).
Raise EOFError if connection closed and no data available. Return b’’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.
-
read_sb_data
()¶ Return any data available in the SB … SE queue.
Return b’’ if no SB … SE available. Should only be called after seeing a SB or SE command. When a new SB command is found, old unread SB data will be discarded. Don’t block.
-
read_some
()¶ Read at least one byte of cooked data unless EOF is hit.
Return b’’ if EOF is hit. Block if no data is immediately available.
-
read_very_eager
()¶ Read everything that’s possible without blocking in I/O (eager).
Raise EOFError if connection closed and no cooked data available. Return b’’ if no cooked data available otherwise. Don’t block unless in the midst of an IAC sequence.
-
read_very_lazy
()¶ Return any data available in the cooked queue (very lazy).
Raise EOFError if connection closed and no data available. Return b’’ if no cooked data available otherwise. Don’t block.
-
set_debuglevel
(debuglevel)¶ Set the debug level.
The higher it is, the more debug output you get (on sys.stdout).
-
set_option_negotiation_callback
(callback)¶ Provide a callback function called after each receipt of a telnet option.
-
sock_avail
()¶ Test whether data is available on the socket.
-
-
class
robot.libraries.Telnet.
TerminalEmulator
(window_size=None, newline='rn')[source]¶ Bases:
object
-
current_output
¶
-
-
exception
robot.libraries.Telnet.
NoMatchError
(expected, timeout, output=None)[source]¶ Bases:
AssertionError
-
ROBOT_SUPPRESS_NAME
= True¶
-
add_note
()¶ Exception.add_note(note) – add a note to the exception
-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
robot.libraries.XML module¶
-
class
robot.libraries.XML.
XML
(use_lxml=False)[source]¶ Bases:
object
Robot Framework library for verifying and modifying XML documents.
As the name implies, _XML_ is a library for verifying contents of XML files. In practice, it is a pretty thin wrapper on top of Python’s [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree XML API].
The library has the following main usages:
- Parsing an XML file, or a string containing XML, into an XML element structure and finding certain elements from it for for further analysis (e.g. Parse XML and Get Element keywords).
- Getting text or attributes of elements (e.g. Get Element Text and Get Element Attribute).
- Directly verifying text, attributes, or whole elements (e.g Element Text Should Be and Elements Should Be Equal).
- Modifying XML and saving it (e.g. Set Element Text, Add Element and Save XML).
== Table of contents ==
%TOC%
= Parsing XML =
XML can be parsed into an element structure using Parse XML keyword. The XML to be parsed can be specified using a path to an XML file or as a string or bytes that contain XML directly. The keyword returns the root element of the structure, which then contains other elements as its children and their children. Possible comments and processing instructions in the source XML are removed.
XML is not validated during parsing even if has a schema defined. How possible doctype elements are handled otherwise depends on the used XML module and on the platform. The standard ElementTree strips doctypes altogether but when using lxml they are preserved when XML is saved.
The element structure returned by Parse XML, as well as elements returned by keywords such as Get Element, can be used as the
source
argument with other keywords. In addition to an already parsed XML structure, other keywords also accept paths to XML files and strings containing XML similarly as Parse XML. Notice that keywords that modify XML do not write those changes back to disk even if the source would be given as a path to a file. Changes must always be saved explicitly using Save XML keyword.When the source is given as a path to a file, the forward slash character (
/
) can be used as the path separator regardless the operating system. On Windows also the backslash works, but in the data it needs to be escaped by doubling it (\\
). Using the built-in variable${/}
naturally works too.Note: Support for XML as bytes is new in Robot Framework 3.2.
= Using lxml =
By default, this library uses Python’s standard [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree] module for parsing XML, but it can be configured to use [http://lxml.de|lxml] module instead when importing the library. The resulting element structure has same API regardless which module is used for parsing.
The main benefits of using lxml is that it supports richer xpath syntax than the standard ElementTree and enables using Evaluate Xpath keyword. It also preserves the doctype and possible namespace prefixes saving XML.
= Example =
The following simple example demonstrates parsing XML and verifying its contents both using keywords in this library and in _BuiltIn_ and _Collections_ libraries. How to use xpath expressions to find elements and what attributes the returned elements contain are discussed, with more examples, in Finding elements with xpath and Element attributes sections.
In this example, as well as in many other examples in this documentation,
${XML}
refers to the following example XML document. In practice${XML}
could either be a path to an XML file or it could contain the XML itself.Notice that in the example three last lines are equivalent. Which one to use in practice depends on which other elements you need to get or verify. If you only need to do one verification, using the last line alone would suffice. If more verifications are needed, parsing the XML with Parse XML only once would be more efficient.
= Finding elements with xpath =
ElementTree, and thus also this library, supports finding elements using xpath expressions. ElementTree does not, however, support the full xpath standard. The supported xpath syntax is explained below and [https://docs.python.org/library/xml.etree.elementtree.html#xpath-support| ElementTree documentation] provides more details. In the examples
${XML}
refers to the same XML structure as in the earlier example.If lxml support is enabled when importing the library, the whole [http://www.w3.org/TR/xpath/|xpath 1.0 standard] is supported. That includes everything listed below but also lot of other useful constructs.
== Tag names ==
When just a single tag name is used, xpath matches all direct child elements that have that tag name.
== Paths ==
Paths are created by combining tag names with a forward slash (
/
). For example,parent/child
matches allchild
elements underparent
element. Notice that if there are multipleparent
elements that all havechild
elements,parent/child
xpath will match all thesechild
elements.== Wildcards ==
An asterisk (
*
) can be used in paths instead of a tag name to denote any element.== Current element ==
The current element is denoted with a dot (
.
). Normally the current element is implicit and does not need to be included in the xpath.== Parent element ==
The parent element of another element is denoted with two dots (
..
). Notice that it is not possible to refer to the parent of the current element.== Search all sub elements ==
Two forward slashes (
//
) mean that all sub elements, not only the direct children, are searched. If the search is started from the current element, an explicit dot is required.== Predicates ==
Predicates allow selecting elements using also other criteria than tag names, for example, attributes or position. They are specified after the normal tag name or path using syntax
path[predicate]
. The path can have wildcards and other special syntax explained earlier. What predicates the standard ElementTree supports is explained in the table below.Predicates can also be stacked like
path[predicate1][predicate2]
. A limitation is that possible position predicate must always be first.= Element attributes =
All keywords returning elements, such as Parse XML, and Get Element, return ElementTree’s [http://docs.python.org/library/xml.etree.elementtree.html#element-objects|Element objects]. These elements can be used as inputs for other keywords, but they also contain several useful attributes that can be accessed directly using the extended variable syntax.
The attributes that are both useful and convenient to use in the data are explained below. Also other attributes, including methods, can be accessed, but that is typically better to do in custom libraries than directly in the data.
The examples use the same
${XML}
structure as the earlier examples.== tag ==
The tag of the element.
== text ==
The text that the element contains or Python
None
if the element has no text. Notice that the text _does not_ contain texts of possible child elements nor text after or between children. Notice also that in XML whitespace is significant, so the text contains also possible indentation and newlines. To get also text of the possible children, optionally whitespace normalized, use Get Element Text keyword.== tail ==
The text after the element before the next opening or closing tag. Python
None
if the element has no tail. Similarly as withtext
, alsotail
contains possible indentation and newlines.== attrib ==
A Python dictionary containing attributes of the element.
= Handling XML namespaces =
ElementTree and lxml handle possible namespaces in XML documents by adding the namespace URI to tag names in so called Clark Notation. That is inconvenient especially with xpaths, and by default this library strips those namespaces away and moves them to
xmlns
attribute instead. That can be avoided by passingkeep_clark_notation
argument to Parse XML keyword. Alternatively Parse XML supports stripping namespace information altogether by usingstrip_namespaces
argument. The pros and cons of different approaches are discussed in more detail below.== How ElementTree handles namespaces ==
If an XML document has namespaces, ElementTree adds namespace information to tag names in [http://www.jclark.com/xml/xmlns.htm|Clark Notation] (e.g.
{http://ns.uri}tag
) and removes originalxmlns
attributes. This is done both with default namespaces and with namespaces with a prefix. How it works in practice is illustrated by the following example, where${NS}
variable contains this XML document:As you can see, including the namespace URI in tag names makes xpaths really long and complex.
If you save the XML, ElementTree moves namespace information back to
xmlns
attributes. Unfortunately it does not restore the original prefixes:The resulting output is semantically same as the original, but mangling prefixes like this may still not be desirable. Notice also that the actual output depends slightly on ElementTree version.
== Default namespace handling ==
Because the way ElementTree handles namespaces makes xpaths so complicated, this library, by default, strips namespaces from tag names and moves that information back to
xmlns
attributes. How this works in practice is shown by the example below, where${NS}
variable contains the same XML document as in the previous example.Now that tags do not contain namespace information, xpaths are simple again.
A minor limitation of this approach is that namespace prefixes are lost. As a result the saved output is not exactly same as the original one in this case either:
Also this output is semantically same as the original. If the original XML had only default namespaces, the output would also look identical.
== Namespaces when using lxml ==
This library handles namespaces same way both when using lxml and when not using it. There are, however, differences how lxml internally handles namespaces compared to the standard ElementTree. The main difference is that lxml stores information about namespace prefixes and they are thus preserved if XML is saved. Another visible difference is that lxml includes namespace information in child elements got with Get Element if the parent element has namespaces.
== Stripping namespaces altogether ==
Because namespaces often add unnecessary complexity, Parse XML supports stripping them altogether by using
strip_namespaces=True
. When this option is enabled, namespaces are not shown anywhere nor are they included if XML is saved.== Attribute namespaces ==
Attributes in XML documents are, by default, in the same namespaces as the element they belong to. It is possible to use different namespaces by using prefixes, but this is pretty rare.
If an attribute has a namespace prefix, ElementTree will replace it with Clark Notation the same way it handles elements. Because stripping namespaces from attributes could cause attribute conflicts, this library does not handle attribute namespaces at all. Thus the following example works the same way regardless how namespaces are handled.
= Boolean arguments =
Some keywords accept arguments that are handled as Boolean values true or false. If such an argument is given as a string, it is considered false if it is an empty string or equal to
FALSE
,NONE
,NO
,OFF
or0
, case-insensitively. Other strings are considered true regardless their value, and other argument types are tested using the same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].True examples:
False examples:
Considering
OFF
and0
false is new in Robot Framework 3.1.== Pattern matching ==
Some keywords, for example Elements Should Match, support so called [http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where:
Unlike with glob patterns normally, path separator characters
/
and\
and the newline character\n
are matches by the above wildcards.Support for brackets like
[abc]
and[!a-z]
is new in Robot Framework 3.1Import library with optionally lxml mode enabled.
This library uses Python’s standard [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree] module for parsing XML by default. If
use_lxml
argument is given a true value (see Boolean arguments), the [http://lxml.de|lxml] module is used instead. See the Using lxml section for benefits provided by lxml.Using lxml requires that the lxml module is installed on the system. If lxml mode is enabled but the module is not installed, this library emits a warning and reverts back to using the standard ElementTree.
-
ROBOT_LIBRARY_SCOPE
= 'GLOBAL'¶
-
ROBOT_LIBRARY_VERSION
= '6.1.1'¶
-
parse_xml
(source, keep_clark_notation=False, strip_namespaces=False)[source]¶ Parses the given XML file or string into an element structure.
The
source
can either be a path to an XML file or a string containing XML. In both cases the XML is parsed into ElementTree [http://docs.python.org/library/xml.etree.elementtree.html#element-objects|element structure] and the root element is returned. Possible comments and processing instructions in the source XML are removed.As discussed in Handling XML namespaces section, this keyword, by default, removes namespace information ElementTree has added to tag names and moves it into
xmlns
attributes. This typically eases handling XML documents with namespaces considerably. If you do not want that to happen, or want to avoid the small overhead of going through the element structure when your XML does not have namespaces, you can disable this feature by givingkeep_clark_notation
argument a true value (see Boolean arguments).If you want to strip namespace information altogether so that it is not included even if XML is saved, you can give a true value to
strip_namespaces
argument.Use Get Element keyword if you want to get a certain element and not the whole structure. See Parsing XML section for more details and examples.
-
get_element
(source, xpath='.')[source]¶ Returns an element in the
source
matching thexpath
.The
source
can be a path to an XML file, a string containing XML, or an already parsed XML element. Thexpath
specifies which element to find. See the introduction for more details about both the possible sources and the supported xpath syntax.The keyword fails if more, or less, than one element matches the
xpath
. Use Get Elements if you want all matching elements to be returned.Parse XML is recommended for parsing XML when the whole structure is needed. It must be used if there is a need to configure how XML namespaces are handled.
Many other keywords use this keyword internally, and keywords modifying XML are typically documented to both to modify the given source and to return it. Modifying the source does not apply if the source is given as a string. The XML structure parsed based on the string and then modified is nevertheless returned.
-
get_elements
(source, xpath)[source]¶ Returns a list of elements in the
source
matching thexpath
.The
source
can be a path to an XML file, a string containing XML, or an already parsed XML element. Thexpath
specifies which element to find. See the introduction for more details.Elements matching the
xpath
are returned as a list. If no elements match, an empty list is returned. Use Get Element if you want to get exactly one match.
-
get_child_elements
(source, xpath='.')[source]¶ Returns the child elements of the specified element as a list.
The element whose children to return is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.All the direct child elements of the specified element are returned. If the element has no children, an empty list is returned.
-
get_element_count
(source, xpath='.')[source]¶ Returns and logs how many elements the given
xpath
matches.Arguments
source
andxpath
have exactly the same semantics as with Get Elements keyword that this keyword uses internally.See also Element Should Exist and Element Should Not Exist.
-
element_should_exist
(source, xpath='.', message=None)[source]¶ Verifies that one or more element match the given
xpath
.Arguments
source
andxpath
have exactly the same semantics as with Get Elements keyword. Keyword passes if thexpath
matches one or more elements in thesource
. The default error message can be overridden with themessage
argument.See also Element Should Not Exist as well as Get Element Count that this keyword uses internally.
-
element_should_not_exist
(source, xpath='.', message=None)[source]¶ Verifies that no element match the given
xpath
.Arguments
source
andxpath
have exactly the same semantics as with Get Elements keyword. Keyword fails if thexpath
matches any element in thesource
. The default error message can be overridden with themessage
argument.See also Element Should Exist as well as Get Element Count that this keyword uses internally.
-
get_element_text
(source, xpath='.', normalize_whitespace=False)[source]¶ Returns all text of the element, possibly whitespace normalized.
The element whose text to return is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.This keyword returns all the text of the specified element, including all the text its children and grandchildren contain. If the element has no text, an empty string is returned. The returned text is thus not always the same as the text attribute of the element.
By default all whitespace, including newlines and indentation, inside the element is returned as-is. If
normalize_whitespace
is given a true value (see Boolean arguments), then leading and trailing whitespace is stripped, newlines and tabs converted to spaces, and multiple spaces collapsed into one. This is especially useful when dealing with HTML data.See also Get Elements Texts, Element Text Should Be and Element Text Should Match.
-
get_elements_texts
(source, xpath, normalize_whitespace=False)[source]¶ Returns text of all elements matching
xpath
as a list.The elements whose text to return is specified using
source
andxpath
. They have exactly the same semantics as with Get Elements keyword.The text of the matched elements is returned using the same logic as with Get Element Text. This includes optional whitespace normalization using the
normalize_whitespace
option.
-
element_text_should_be
(source, expected, xpath='.', normalize_whitespace=False, message=None)[source]¶ Verifies that the text of the specified element is
expected
.The element whose text is verified is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.The text to verify is got from the specified element using the same logic as with Get Element Text. This includes optional whitespace normalization using the
normalize_whitespace
option.The keyword passes if the text of the element is equal to the
expected
value, and otherwise it fails. The default error message can be overridden with themessage
argument. Use Element Text Should Match to verify the text against a pattern instead of an exact value.
-
element_text_should_match
(source, pattern, xpath='.', normalize_whitespace=False, message=None)[source]¶ Verifies that the text of the specified element matches
expected
.This keyword works exactly like Element Text Should Be except that the expected value can be given as a pattern that the text of the element must match.
Pattern matching is similar as matching files in a shell with
*
,?
and[chars]
acting as wildcards. See the Pattern matching section for more information.
-
get_element_attribute
(source, name, xpath='.', default=None)[source]¶ Returns the named attribute of the specified element.
The element whose attribute to return is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.The value of the attribute
name
of the specified element is returned. If the element does not have such element, thedefault
value is returned instead.See also Get Element Attributes, Element Attribute Should Be, Element Attribute Should Match and Element Should Not Have Attribute.
-
get_element_attributes
(source, xpath='.')[source]¶ Returns all attributes of the specified element.
The element whose attributes to return is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.Attributes are returned as a Python dictionary. It is a copy of the original attributes so modifying it has no effect on the XML structure.
Use Get Element Attribute to get the value of a single attribute.
-
element_attribute_should_be
(source, name, expected, xpath='.', message=None)[source]¶ Verifies that the specified attribute is
expected
.The element whose attribute is verified is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.The keyword passes if the attribute
name
of the element is equal to theexpected
value, and otherwise it fails. The default error message can be overridden with themessage
argument.To test that the element does not have a certain attribute, Python
None
(i.e. variable${NONE}
) can be used as the expected value. A cleaner alternative is using Element Should Not Have Attribute.See also Element Attribute Should Match and Get Element Attribute.
-
element_attribute_should_match
(source, name, pattern, xpath='.', message=None)[source]¶ Verifies that the specified attribute matches
expected
.This keyword works exactly like Element Attribute Should Be except that the expected value can be given as a pattern that the attribute of the element must match.
Pattern matching is similar as matching files in a shell with
*
,?
and[chars]
acting as wildcards. See the Pattern matching section for more information.
-
element_should_not_have_attribute
(source, name, xpath='.', message=None)[source]¶ Verifies that the specified element does not have attribute
name
.The element whose attribute is verified is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.The keyword fails if the specified element has attribute
name
. The default error message can be overridden with themessage
argument.See also Get Element Attribute, Get Element Attributes, Element Text Should Be and Element Text Should Match.
-
elements_should_be_equal
(source, expected, exclude_children=False, normalize_whitespace=False)[source]¶ Verifies that the given
source
element is equal toexpected
.Both
source
andexpected
can be given as a path to an XML file, as a string containing XML, or as an already parsed XML element structure. See introduction for more information about parsing XML in general.The keyword passes if the
source
element andexpected
element are equal. This includes testing the tag names, texts, and attributes of the elements. By default also child elements are verified the same way, but this can be disabled by settingexclude_children
to a true value (see Boolean arguments).All texts inside the given elements are verified, but possible text outside them is not. By default texts must match exactly, but setting
normalize_whitespace
to a true value makes text verification independent on newlines, tabs, and the amount of spaces. For more details about handling text see Get Element Text keyword and discussion about elements’ text and tail attributes in the introduction.The last example may look a bit strange because the
<p>
element only has textText with
. The reason is that rest of the text inside<p>
actually belongs to the child elements. This includes the.
at the end that is the tail text of the<i>
element.See also Elements Should Match.
-
elements_should_match
(source, expected, exclude_children=False, normalize_whitespace=False)[source]¶ Verifies that the given
source
element matchesexpected
.This keyword works exactly like Elements Should Be Equal except that texts and attribute values in the expected value can be given as patterns.
Pattern matching is similar as matching files in a shell with
*
,?
and[chars]
acting as wildcards. See the Pattern matching section for more information.See Elements Should Be Equal for more examples.
-
set_element_tag
(source, tag, xpath='.')[source]¶ Sets the tag of the specified element.
The element whose tag to set is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.Can only set the tag of a single element. Use Set Elements Tag to set the tag of multiple elements in one call.
-
set_elements_tag
(source, tag, xpath='.')[source]¶ Sets the tag of the specified elements.
Like Set Element Tag but sets the tag of all elements matching the given
xpath
.
-
set_element_text
(source, text=None, tail=None, xpath='.')[source]¶ Sets text and/or tail text of the specified element.
The element whose text to set is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.Element’s text and tail text are changed only if new
text
and/ortail
values are given. See Element attributes section for more information about text and tail in general.Can only set the text/tail of a single element. Use Set Elements Text to set the text/tail of multiple elements in one call.
-
set_elements_text
(source, text=None, tail=None, xpath='.')[source]¶ Sets text and/or tail text of the specified elements.
Like Set Element Text but sets the text or tail of all elements matching the given
xpath
.
-
set_element_attribute
(source, name, value, xpath='.')[source]¶ Sets attribute
name
of the specified element tovalue
.The element whose attribute to set is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.It is possible to both set new attributes and to overwrite existing. Use Remove Element Attribute or Remove Element Attributes for removing them.
Can only set an attribute of a single element. Use Set Elements Attribute to set an attribute of multiple elements in one call.
-
set_elements_attribute
(source, name, value, xpath='.')[source]¶ Sets attribute
name
of the specified elements tovalue
.Like Set Element Attribute but sets the attribute of all elements matching the given
xpath
.
-
remove_element_attribute
(source, name, xpath='.')[source]¶ Removes attribute
name
from the specified element.The element whose attribute to remove is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.It is not a failure to remove a non-existing attribute. Use Remove Element Attributes to remove all attributes and Set Element Attribute to set them.
Can only remove an attribute from a single element. Use Remove Elements Attribute to remove an attribute of multiple elements in one call.
-
remove_elements_attribute
(source, name, xpath='.')[source]¶ Removes attribute
name
from the specified elements.Like Remove Element Attribute but removes the attribute of all elements matching the given
xpath
.
-
remove_element_attributes
(source, xpath='.')[source]¶ Removes all attributes from the specified element.
The element whose attributes to remove is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.Use Remove Element Attribute to remove a single attribute and Set Element Attribute to set them.
Can only remove attributes from a single element. Use Remove Elements Attributes to remove all attributes of multiple elements in one call.
-
remove_elements_attributes
(source, xpath='.')[source]¶ Removes all attributes from the specified elements.
Like Remove Element Attributes but removes all attributes of all elements matching the given
xpath
.
-
add_element
(source, element, index=None, xpath='.')[source]¶ Adds a child element to the specified element.
The element to whom to add the new element is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.The
element
to add can be specified as a path to an XML file or as a string containing XML, or it can be an already parsed XML element. The element is copied before adding so modifying either the original or the added element has no effect on the other . The element is added as the last child by default, but a custom index can be used to alter the position. Indices start from zero (0 = first position, 1 = second position, etc.), and negative numbers refer to positions at the end (-1 = second last position, -2 = third last, etc.).Use Remove Element or Remove Elements to remove elements.
-
remove_element
(source, xpath='', remove_tail=False)[source]¶ Removes the element matching
xpath
from thesource
structure.The element to remove from the
source
is specified withxpath
using the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.The keyword fails if
xpath
does not match exactly one element. Use Remove Elements to remove all matched elements.Element’s tail text is not removed by default, but that can be changed by giving
remove_tail
a true value (see Boolean arguments). See Element attributes section for more information about tail in general.
-
remove_elements
(source, xpath='', remove_tail=False)[source]¶ Removes all elements matching
xpath
from thesource
structure.The elements to remove from the
source
are specified withxpath
using the same semantics as with Get Elements keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.It is not a failure if
xpath
matches no elements. Use Remove Element to remove exactly one element.Element’s tail text is not removed by default, but that can be changed by using
remove_tail
argument similarly as with Remove Element.
-
clear_element
(source, xpath='.', clear_tail=False)[source]¶ Clears the contents of the specified element.
The element to clear is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword. The resulting XML structure is returned, and if thesource
is an already parsed XML structure, it is also modified in place.Clearing the element means removing its text, attributes, and children. Element’s tail text is not removed by default, but that can be changed by giving
clear_tail
a true value (see Boolean arguments). See Element attributes section for more information about tail in general.Use Remove Element to remove the whole element.
-
copy_element
(source, xpath='.')[source]¶ Returns a copy of the specified element.
The element to copy is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.If the copy or the original element is modified afterwards, the changes have no effect on the other.
-
element_to_string
(source, xpath='.', encoding=None)[source]¶ Returns the string representation of the specified element.
The element to convert to a string is specified using
source
andxpath
. They have exactly the same semantics as with Get Element keyword.The string is returned as Unicode by default. If
encoding
argument is given any value, the string is returned as bytes in the specified encoding. The resulting string never contains the XML declaration.See also Log Element and Save XML.
-
log_element
(source, level='INFO', xpath='.')[source]¶ Logs the string representation of the specified element.
The element specified with
source
andxpath
is first converted into a string using Element To String keyword internally. The resulting string is then logged using the givenlevel
.The logged string is also returned.
-
save_xml
(source, path, encoding='UTF-8')[source]¶ Saves the given element to the specified file.
The element to save is specified with
source
using the same semantics as with Get Element keyword.The file where the element is saved is denoted with
path
and the encoding to use withencoding
. The resulting file always contains the XML declaration.The resulting XML file may not be exactly the same as the original: - Comments and processing instructions are always stripped. - Possible doctype and namespace prefixes are only preserved when
using lxml.- Other small differences are possible depending on the ElementTree or lxml version.
Use Element To String if you just need a string representation of the element.
-
evaluate_xpath
(source, expression, context='.')[source]¶ Evaluates the given xpath expression and returns results.
The element in which context the expression is executed is specified using
source
andcontext
arguments. They have exactly the same semantics assource
andxpath
arguments have with Get Element keyword.The xpath expression to evaluate is given as
expression
argument. The result of the evaluation is returned as-is.This keyword works only if lxml mode is taken into use when importing the library.
robot.libraries.dialogs_py module¶
-
class
robot.libraries.dialogs_py.
TkDialog
(message, value=None, **config)[source]¶ Bases:
tkinter.Toplevel
-
after
(ms, func=None, *args)¶ Call function once after given time.
MS specifies the time in milliseconds. FUNC gives the function which shall be called. Additional parameters are given as parameters to the function call. Return identifier to cancel scheduling with after_cancel.
-
after_cancel
(id)¶ Cancel scheduling of function identified with ID.
Identifier returned by after or after_idle must be given as first parameter.
-
after_idle
(func, *args)¶ Call FUNC once if the Tcl main loop has no event to process.
Return an identifier to cancel the scheduling with after_cancel.
-
anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
bell
(displayof=0)¶ Ring a display’s bell.
-
bind
(sequence=None, func=None, add=None)¶ Bind to this widget at event SEQUENCE a call to function FUNC.
SEQUENCE is a string of concatenated event patterns. An event pattern is of the form <MODIFIER-MODIFIER-TYPE-DETAIL> where MODIFIER is one of Control, Mod2, M2, Shift, Mod3, M3, Lock, Mod4, M4, Button1, B1, Mod5, M5 Button2, B2, Meta, M, Button3, B3, Alt, Button4, B4, Double, Button5, B5 Triple, Mod1, M1. TYPE is one of Activate, Enter, Map, ButtonPress, Button, Expose, Motion, ButtonRelease FocusIn, MouseWheel, Circulate, FocusOut, Property, Colormap, Gravity Reparent, Configure, KeyPress, Key, Unmap, Deactivate, KeyRelease Visibility, Destroy, Leave and DETAIL is the button number for ButtonPress, ButtonRelease and DETAIL is the Keysym for KeyPress and KeyRelease. Examples are <Control-Button-1> for pressing Control and mouse button 1 or <Alt-A> for pressing A and the Alt key (KeyPress can be omitted). An event pattern can also be a virtual event of the form <<AString>> where AString can be arbitrary. This event can be generated by event_generate. If events are concatenated they must appear shortly after each other.
FUNC will be called if the event sequence occurs with an instance of Event as argument. If the return value of FUNC is “break” no further bound function is invoked.
An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function.
Bind will return an identifier to allow deletion of the bound function with unbind without memory leak.
If FUNC or SEQUENCE is omitted the bound function or list of bound events are returned.
-
bind_all
(sequence=None, func=None, add=None)¶ Bind to all widgets at an event SEQUENCE a call to function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
-
bind_class
(className, sequence=None, func=None, add=None)¶ Bind to widgets with bindtag CLASSNAME at event SEQUENCE a call of function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
Set or get the list of bindtags for this widget.
With no argument return the list of all bindtags associated with this widget. With a list of strings as argument the bindtags are set to this list. The bindtags determine in which order events are processed (see bind).
-
cget
(key)¶ Return the resource value for a KEY given as string.
-
client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
clipboard_append
(string, **kw)¶ Append STRING to the Tk clipboard.
A widget specified at the optional displayof keyword argument specifies the target display. The clipboard can be retrieved with selection_get.
-
clipboard_clear
(**kw)¶ Clear the data in the Tk clipboard.
A widget specified for the optional displayof keyword argument specifies the target display.
-
clipboard_get
(**kw)¶ Retrieve data from the clipboard on window’s display.
The window keyword defaults to the root window of the Tkinter application.
The type keyword specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING, except on X11, where the default is to try UTF8_STRING and fall back to STRING.
This command is equivalent to:
selection_get(CLIPBOARD)
-
colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
config
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
configure
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
deletecommand
(name)¶ Internal function.
Delete the Tcl command provided in NAME.
-
destroy
()¶ Destroy this and all descendants widgets.
-
event_add
(virtual, *sequences)¶ Bind a virtual event VIRTUAL (of the form <<Name>>) to an event SEQUENCE such that the virtual event is triggered whenever SEQUENCE occurs.
-
event_delete
(virtual, *sequences)¶ Unbind a virtual event VIRTUAL from SEQUENCE.
-
event_generate
(sequence, **kw)¶ Generate an event SEQUENCE. Additional keyword arguments specify parameter of the event (e.g. x, y, rootx, rooty).
-
event_info
(virtual=None)¶ Return a list of all virtual events or the information about the SEQUENCE bound to the virtual event VIRTUAL.
-
focus
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focus_displayof
()¶ Return the widget which has currently the focus on the display where this widget is located.
Return None if the application does not have the focus.
-
focus_force
()¶ Direct input focus to this widget even if the application does not have the focus. Use with caution!
-
focus_get
()¶ Return the widget which has currently the focus in the application.
Use focus_displayof to allow working with several displays. Return None if application does not have the focus.
-
focus_lastfor
()¶ Return the widget which would have the focus if top level for this widget gets the focus from the window manager.
-
focus_set
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
frame
()¶ Return identifier for decorative frame of this widget if present.
-
geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
getboolean
(s)¶ Return a boolean value for Tcl boolean values true and false given as parameter.
-
getdouble
(s)¶
-
getint
(s)¶
-
getvar
(name='PY_VAR')¶ Return value of Tcl variable NAME.
-
grab_current
()¶ Return widget which has currently the grab in this application or None.
-
grab_release
()¶ Release grab for this widget if currently set.
-
grab_set
()¶ Set grab for this widget.
A grab directs all events to this and descendant widgets in the application.
-
grab_set_global
()¶ Set global grab for this widget.
A global grab directs all events to this and descendant widgets on the display. Use with caution - other applications do not get events anymore.
-
grab_status
()¶ Return None, “local” or “global” if this widget has no, a local or a global grab.
-
grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
grid_anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
grid_bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
grid_columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
grid_location
(x, y)¶ Return a tuple of column and row which identify the cell at which the pixel at position X and Y inside the master widget is located.
-
grid_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given, the current setting will be returned.
-
grid_rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
grid_size
()¶ Return a tuple of the number of column and rows in the grid.
-
grid_slaves
(row=None, column=None)¶ Return a list of all slaves of this widget in its packing order.
-
group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
iconify
()¶ Display widget as icon.
-
iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
image_names
()¶ Return a list of all existing image names.
-
image_types
()¶ Return a list of all available image types (e.g. photo bitmap).
-
info_patchlevel
()¶ Returns the exact version of the Tcl library.
-
keys
()¶ Return a list of all resource names of this widget.
-
lift
(aboveThis=None)¶ Raise this widget in the stacking order.
-
lower
(belowThis=None)¶ Lower this widget in the stacking order.
-
mainloop
(n=0)¶ Call the mainloop of Tk.
-
manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
nametowidget
(name)¶ Return the Tkinter instance of a widget identified by its Tcl name NAME.
-
option_add
(pattern, value, priority=None)¶ Set a VALUE (second parameter) for an option PATTERN (first parameter).
An optional third parameter gives the numeric priority (defaults to 80).
-
option_clear
()¶ Clear the option database.
It will be reloaded if option_add is called.
-
option_get
(name, className)¶ Return the value for an option NAME for this widget with CLASSNAME.
Values with higher priority override lower values.
-
option_readfile
(fileName, priority=None)¶ Read file FILENAME into the option database.
An optional second parameter gives the numeric priority.
-
overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
pack_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
pack_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
place_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
quit
()¶ Quit the Tcl interpreter. All widgets will be destroyed.
-
register
(func, subst=None, needcleanup=1)¶ Return a newly created Tcl function. If this function is called, the Python function FUNC will be executed. An optional function SUBST can be given which will be executed before FUNC.
-
resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
selection_clear
(**kw)¶ Clear the current X selection.
-
selection_get
(**kw)¶ Return the contents of the current X selection.
A keyword parameter selection specifies the name of the selection and defaults to PRIMARY. A keyword parameter displayof specifies a widget on the display to use. A keyword parameter type specifies the form of data to be fetched, defaulting to STRING except on X11, where UTF8_STRING is tried before STRING.
-
selection_handle
(command, **kw)¶ Specify a function COMMAND to call if the X selection owned by this widget is queried by another application.
This function must return the contents of the selection. The function will be called with the arguments OFFSET and LENGTH which allows the chunking of very long selections. The following keyword parameters can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
selection_own
(**kw)¶ Become owner of X selection.
A keyword parameter selection specifies the name of the selection (default PRIMARY).
-
selection_own_get
(**kw)¶ Return owner of X selection.
The following keyword parameter can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
send
(interp, cmd, *args)¶ Send Tcl command CMD to different interpreter INTERP to be executed.
-
setvar
(name='PY_VAR', value='1')¶ Set Tcl variable NAME to VALUE.
-
size
()¶ Return a tuple of the number of column and rows in the grid.
-
sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
title
(string=None)¶ Set the title of this widget.
-
tk_bisque
()¶ Change the color scheme to light brown as used in Tk 3.6 and before.
-
tk_focusFollowsMouse
()¶ The widget under mouse will get automatically focus. Can not be disabled easily.
-
tk_focusNext
()¶ Return the next widget in the focus order which follows widget which has currently the focus.
The focus order first goes to the next child, then to the children of the child recursively and then to the next sibling which is higher in the stacking order. A widget is omitted if it has the takefocus resource set to 0.
-
tk_focusPrev
()¶ Return previous widget in the focus order. See tk_focusNext for details.
-
tk_setPalette
(*args, **kw)¶ Set a new color scheme for all widget elements.
A single color as argument will cause that all colors of Tk widget elements are derived from this. Alternatively several keyword parameters and its associated colors can be given. The following keywords are valid: activeBackground, foreground, selectColor, activeForeground, highlightBackground, selectBackground, background, highlightColor, selectForeground, disabledForeground, insertBackground, troughColor.
-
tk_strictMotif
(boolean=None)¶ Set Tcl internal variable, whether the look and feel should adhere to Motif.
A parameter of 1 means adhere to Motif (e.g. no color change if mouse passes over slider). Returns the set value.
-
tkraise
(aboveThis=None)¶ Raise this widget in the stacking order.
-
transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
unbind
(sequence, funcid=None)¶ Unbind for this widget for event SEQUENCE the function identified with FUNCID.
-
unbind_all
(sequence)¶ Unbind for all widgets for event SEQUENCE all functions.
-
unbind_class
(className, sequence)¶ Unbind for all widgets with bindtag CLASSNAME for event SEQUENCE all functions.
-
update
()¶ Enter event loop until all pending events have been processed by Tcl.
-
update_idletasks
()¶ Enter event loop until all idle callbacks have been called. This will update the display of windows but not process events caused by the user.
-
wait_variable
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
wait_visibility
(window=None)¶ Wait until the visibility of a WIDGET changes (e.g. it appears).
If no parameter is given self is used.
-
wait_window
(window=None)¶ Wait until a WIDGET is destroyed.
If no parameter is given self is used.
-
waitvar
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
winfo_atom
(name, displayof=0)¶ Return integer which represents atom NAME.
-
winfo_atomname
(id, displayof=0)¶ Return name of atom with identifier ID.
-
winfo_cells
()¶ Return number of cells in the colormap for this widget.
-
winfo_children
()¶ Return a list of all widgets which are children of this widget.
-
winfo_class
()¶ Return window class name of this widget.
-
winfo_colormapfull
()¶ Return True if at the last color request the colormap was full.
-
winfo_containing
(rootX, rootY, displayof=0)¶ Return the widget which is at the root coordinates ROOTX, ROOTY.
-
winfo_depth
()¶ Return the number of bits per pixel.
-
winfo_exists
()¶ Return true if this widget exists.
-
winfo_fpixels
(number)¶ Return the number of pixels for the given distance NUMBER (e.g. “3c”) as float.
-
winfo_geometry
()¶ Return geometry string for this widget in the form “widthxheight+X+Y”.
-
winfo_height
()¶ Return height of this widget.
-
winfo_id
()¶ Return identifier ID for this widget.
-
winfo_interps
(displayof=0)¶ Return the name of all Tcl interpreters for this display.
-
winfo_ismapped
()¶ Return true if this widget is mapped.
-
winfo_manager
()¶ Return the window manager name for this widget.
-
winfo_name
()¶ Return the name of this widget.
-
winfo_parent
()¶ Return the name of the parent of this widget.
-
winfo_pathname
(id, displayof=0)¶ Return the pathname of the widget given by ID.
-
winfo_pixels
(number)¶ Rounded integer value of winfo_fpixels.
-
winfo_pointerx
()¶ Return the x coordinate of the pointer on the root window.
-
winfo_pointerxy
()¶ Return a tuple of x and y coordinates of the pointer on the root window.
-
winfo_pointery
()¶ Return the y coordinate of the pointer on the root window.
-
winfo_reqheight
()¶ Return requested height of this widget.
-
winfo_reqwidth
()¶ Return requested width of this widget.
-
winfo_rgb
(color)¶ Return a tuple of integer RGB values in range(65536) for color in this widget.
-
winfo_rootx
()¶ Return x coordinate of upper left corner of this widget on the root window.
-
winfo_rooty
()¶ Return y coordinate of upper left corner of this widget on the root window.
-
winfo_screen
()¶ Return the screen name of this widget.
-
winfo_screencells
()¶ Return the number of the cells in the colormap of the screen of this widget.
-
winfo_screendepth
()¶ Return the number of bits per pixel of the root window of the screen of this widget.
-
winfo_screenheight
()¶ Return the number of pixels of the height of the screen of this widget in pixel.
-
winfo_screenmmheight
()¶ Return the number of pixels of the height of the screen of this widget in mm.
-
winfo_screenmmwidth
()¶ Return the number of pixels of the width of the screen of this widget in mm.
-
winfo_screenvisual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the default colormodel of this screen.
-
winfo_screenwidth
()¶ Return the number of pixels of the width of the screen of this widget in pixel.
-
winfo_server
()¶ Return information of the X-Server of the screen of this widget in the form “XmajorRminor vendor vendorVersion”.
-
winfo_toplevel
()¶ Return the toplevel widget of this widget.
-
winfo_viewable
()¶ Return true if the widget and all its higher ancestors are mapped.
-
winfo_visual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the colormodel of this widget.
-
winfo_visualid
()¶ Return the X identifier for the visual for this widget.
-
winfo_visualsavailable
(includeids=False)¶ Return a list of all visuals available for the screen of this widget.
Each item in the list consists of a visual name (see winfo_visual), a depth and if includeids is true is given also the X identifier.
-
winfo_vrootheight
()¶ Return the height of the virtual root window associated with this widget in pixels. If there is no virtual root window return the height of the screen.
-
winfo_vrootwidth
()¶ Return the width of the virtual root window associated with this widget in pixel. If there is no virtual root window return the width of the screen.
-
winfo_vrootx
()¶ Return the x offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_vrooty
()¶ Return the y offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_width
()¶ Return the width of this widget.
-
winfo_x
()¶ Return the x coordinate of the upper left corner of this widget in the parent.
-
winfo_y
()¶ Return the y coordinate of the upper left corner of this widget in the parent.
-
withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
wm_aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
wm_attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
wm_client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
wm_colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
wm_command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
wm_deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
wm_focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
wm_forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
wm_frame
()¶ Return identifier for decorative frame of this widget if present.
-
wm_geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
wm_grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
wm_group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
wm_iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
wm_iconify
()¶ Display widget as icon.
-
wm_iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
wm_iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
wm_iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
wm_iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
wm_iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
wm_manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
wm_maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
wm_positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
wm_resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
wm_sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
wm_title
(string=None)¶ Set the title of this widget.
-
wm_transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
wm_withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
-
class
robot.libraries.dialogs_py.
MessageDialog
(message, value=None, **config)[source]¶ Bases:
robot.libraries.dialogs_py.TkDialog
-
after
(ms, func=None, *args)¶ Call function once after given time.
MS specifies the time in milliseconds. FUNC gives the function which shall be called. Additional parameters are given as parameters to the function call. Return identifier to cancel scheduling with after_cancel.
-
after_cancel
(id)¶ Cancel scheduling of function identified with ID.
Identifier returned by after or after_idle must be given as first parameter.
-
after_idle
(func, *args)¶ Call FUNC once if the Tcl main loop has no event to process.
Return an identifier to cancel the scheduling with after_cancel.
-
anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
bell
(displayof=0)¶ Ring a display’s bell.
-
bind
(sequence=None, func=None, add=None)¶ Bind to this widget at event SEQUENCE a call to function FUNC.
SEQUENCE is a string of concatenated event patterns. An event pattern is of the form <MODIFIER-MODIFIER-TYPE-DETAIL> where MODIFIER is one of Control, Mod2, M2, Shift, Mod3, M3, Lock, Mod4, M4, Button1, B1, Mod5, M5 Button2, B2, Meta, M, Button3, B3, Alt, Button4, B4, Double, Button5, B5 Triple, Mod1, M1. TYPE is one of Activate, Enter, Map, ButtonPress, Button, Expose, Motion, ButtonRelease FocusIn, MouseWheel, Circulate, FocusOut, Property, Colormap, Gravity Reparent, Configure, KeyPress, Key, Unmap, Deactivate, KeyRelease Visibility, Destroy, Leave and DETAIL is the button number for ButtonPress, ButtonRelease and DETAIL is the Keysym for KeyPress and KeyRelease. Examples are <Control-Button-1> for pressing Control and mouse button 1 or <Alt-A> for pressing A and the Alt key (KeyPress can be omitted). An event pattern can also be a virtual event of the form <<AString>> where AString can be arbitrary. This event can be generated by event_generate. If events are concatenated they must appear shortly after each other.
FUNC will be called if the event sequence occurs with an instance of Event as argument. If the return value of FUNC is “break” no further bound function is invoked.
An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function.
Bind will return an identifier to allow deletion of the bound function with unbind without memory leak.
If FUNC or SEQUENCE is omitted the bound function or list of bound events are returned.
-
bind_all
(sequence=None, func=None, add=None)¶ Bind to all widgets at an event SEQUENCE a call to function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
-
bind_class
(className, sequence=None, func=None, add=None)¶ Bind to widgets with bindtag CLASSNAME at event SEQUENCE a call of function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
Set or get the list of bindtags for this widget.
With no argument return the list of all bindtags associated with this widget. With a list of strings as argument the bindtags are set to this list. The bindtags determine in which order events are processed (see bind).
-
cget
(key)¶ Return the resource value for a KEY given as string.
-
client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
clipboard_append
(string, **kw)¶ Append STRING to the Tk clipboard.
A widget specified at the optional displayof keyword argument specifies the target display. The clipboard can be retrieved with selection_get.
-
clipboard_clear
(**kw)¶ Clear the data in the Tk clipboard.
A widget specified for the optional displayof keyword argument specifies the target display.
-
clipboard_get
(**kw)¶ Retrieve data from the clipboard on window’s display.
The window keyword defaults to the root window of the Tkinter application.
The type keyword specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING, except on X11, where the default is to try UTF8_STRING and fall back to STRING.
This command is equivalent to:
selection_get(CLIPBOARD)
-
colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
config
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
configure
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
deletecommand
(name)¶ Internal function.
Delete the Tcl command provided in NAME.
-
destroy
()¶ Destroy this and all descendants widgets.
-
event_add
(virtual, *sequences)¶ Bind a virtual event VIRTUAL (of the form <<Name>>) to an event SEQUENCE such that the virtual event is triggered whenever SEQUENCE occurs.
-
event_delete
(virtual, *sequences)¶ Unbind a virtual event VIRTUAL from SEQUENCE.
-
event_generate
(sequence, **kw)¶ Generate an event SEQUENCE. Additional keyword arguments specify parameter of the event (e.g. x, y, rootx, rooty).
-
event_info
(virtual=None)¶ Return a list of all virtual events or the information about the SEQUENCE bound to the virtual event VIRTUAL.
-
focus
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focus_displayof
()¶ Return the widget which has currently the focus on the display where this widget is located.
Return None if the application does not have the focus.
-
focus_force
()¶ Direct input focus to this widget even if the application does not have the focus. Use with caution!
-
focus_get
()¶ Return the widget which has currently the focus in the application.
Use focus_displayof to allow working with several displays. Return None if application does not have the focus.
-
focus_lastfor
()¶ Return the widget which would have the focus if top level for this widget gets the focus from the window manager.
-
focus_set
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
frame
()¶ Return identifier for decorative frame of this widget if present.
-
geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
getboolean
(s)¶ Return a boolean value for Tcl boolean values true and false given as parameter.
-
getdouble
(s)¶
-
getint
(s)¶
-
getvar
(name='PY_VAR')¶ Return value of Tcl variable NAME.
-
grab_current
()¶ Return widget which has currently the grab in this application or None.
-
grab_release
()¶ Release grab for this widget if currently set.
-
grab_set
()¶ Set grab for this widget.
A grab directs all events to this and descendant widgets in the application.
-
grab_set_global
()¶ Set global grab for this widget.
A global grab directs all events to this and descendant widgets on the display. Use with caution - other applications do not get events anymore.
-
grab_status
()¶ Return None, “local” or “global” if this widget has no, a local or a global grab.
-
grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
grid_anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
grid_bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
grid_columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
grid_location
(x, y)¶ Return a tuple of column and row which identify the cell at which the pixel at position X and Y inside the master widget is located.
-
grid_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given, the current setting will be returned.
-
grid_rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
grid_size
()¶ Return a tuple of the number of column and rows in the grid.
-
grid_slaves
(row=None, column=None)¶ Return a list of all slaves of this widget in its packing order.
-
group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
iconify
()¶ Display widget as icon.
-
iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
image_names
()¶ Return a list of all existing image names.
-
image_types
()¶ Return a list of all available image types (e.g. photo bitmap).
-
info_patchlevel
()¶ Returns the exact version of the Tcl library.
-
keys
()¶ Return a list of all resource names of this widget.
-
lift
(aboveThis=None)¶ Raise this widget in the stacking order.
-
lower
(belowThis=None)¶ Lower this widget in the stacking order.
-
mainloop
(n=0)¶ Call the mainloop of Tk.
-
manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
nametowidget
(name)¶ Return the Tkinter instance of a widget identified by its Tcl name NAME.
-
option_add
(pattern, value, priority=None)¶ Set a VALUE (second parameter) for an option PATTERN (first parameter).
An optional third parameter gives the numeric priority (defaults to 80).
-
option_clear
()¶ Clear the option database.
It will be reloaded if option_add is called.
-
option_get
(name, className)¶ Return the value for an option NAME for this widget with CLASSNAME.
Values with higher priority override lower values.
-
option_readfile
(fileName, priority=None)¶ Read file FILENAME into the option database.
An optional second parameter gives the numeric priority.
-
overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
pack_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
pack_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
place_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
quit
()¶ Quit the Tcl interpreter. All widgets will be destroyed.
-
register
(func, subst=None, needcleanup=1)¶ Return a newly created Tcl function. If this function is called, the Python function FUNC will be executed. An optional function SUBST can be given which will be executed before FUNC.
-
resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
selection_clear
(**kw)¶ Clear the current X selection.
-
selection_get
(**kw)¶ Return the contents of the current X selection.
A keyword parameter selection specifies the name of the selection and defaults to PRIMARY. A keyword parameter displayof specifies a widget on the display to use. A keyword parameter type specifies the form of data to be fetched, defaulting to STRING except on X11, where UTF8_STRING is tried before STRING.
-
selection_handle
(command, **kw)¶ Specify a function COMMAND to call if the X selection owned by this widget is queried by another application.
This function must return the contents of the selection. The function will be called with the arguments OFFSET and LENGTH which allows the chunking of very long selections. The following keyword parameters can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
selection_own
(**kw)¶ Become owner of X selection.
A keyword parameter selection specifies the name of the selection (default PRIMARY).
-
selection_own_get
(**kw)¶ Return owner of X selection.
The following keyword parameter can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
send
(interp, cmd, *args)¶ Send Tcl command CMD to different interpreter INTERP to be executed.
-
setvar
(name='PY_VAR', value='1')¶ Set Tcl variable NAME to VALUE.
-
show
() → Any¶
-
size
()¶ Return a tuple of the number of column and rows in the grid.
-
sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
title
(string=None)¶ Set the title of this widget.
-
tk_bisque
()¶ Change the color scheme to light brown as used in Tk 3.6 and before.
-
tk_focusFollowsMouse
()¶ The widget under mouse will get automatically focus. Can not be disabled easily.
-
tk_focusNext
()¶ Return the next widget in the focus order which follows widget which has currently the focus.
The focus order first goes to the next child, then to the children of the child recursively and then to the next sibling which is higher in the stacking order. A widget is omitted if it has the takefocus resource set to 0.
-
tk_focusPrev
()¶ Return previous widget in the focus order. See tk_focusNext for details.
-
tk_setPalette
(*args, **kw)¶ Set a new color scheme for all widget elements.
A single color as argument will cause that all colors of Tk widget elements are derived from this. Alternatively several keyword parameters and its associated colors can be given. The following keywords are valid: activeBackground, foreground, selectColor, activeForeground, highlightBackground, selectBackground, background, highlightColor, selectForeground, disabledForeground, insertBackground, troughColor.
-
tk_strictMotif
(boolean=None)¶ Set Tcl internal variable, whether the look and feel should adhere to Motif.
A parameter of 1 means adhere to Motif (e.g. no color change if mouse passes over slider). Returns the set value.
-
tkraise
(aboveThis=None)¶ Raise this widget in the stacking order.
-
transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
unbind
(sequence, funcid=None)¶ Unbind for this widget for event SEQUENCE the function identified with FUNCID.
-
unbind_all
(sequence)¶ Unbind for all widgets for event SEQUENCE all functions.
-
unbind_class
(className, sequence)¶ Unbind for all widgets with bindtag CLASSNAME for event SEQUENCE all functions.
-
update
()¶ Enter event loop until all pending events have been processed by Tcl.
-
update_idletasks
()¶ Enter event loop until all idle callbacks have been called. This will update the display of windows but not process events caused by the user.
-
wait_variable
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
wait_visibility
(window=None)¶ Wait until the visibility of a WIDGET changes (e.g. it appears).
If no parameter is given self is used.
-
wait_window
(window=None)¶ Wait until a WIDGET is destroyed.
If no parameter is given self is used.
-
waitvar
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
winfo_atom
(name, displayof=0)¶ Return integer which represents atom NAME.
-
winfo_atomname
(id, displayof=0)¶ Return name of atom with identifier ID.
-
winfo_cells
()¶ Return number of cells in the colormap for this widget.
-
winfo_children
()¶ Return a list of all widgets which are children of this widget.
-
winfo_class
()¶ Return window class name of this widget.
-
winfo_colormapfull
()¶ Return True if at the last color request the colormap was full.
-
winfo_containing
(rootX, rootY, displayof=0)¶ Return the widget which is at the root coordinates ROOTX, ROOTY.
-
winfo_depth
()¶ Return the number of bits per pixel.
-
winfo_exists
()¶ Return true if this widget exists.
-
winfo_fpixels
(number)¶ Return the number of pixels for the given distance NUMBER (e.g. “3c”) as float.
-
winfo_geometry
()¶ Return geometry string for this widget in the form “widthxheight+X+Y”.
-
winfo_height
()¶ Return height of this widget.
-
winfo_id
()¶ Return identifier ID for this widget.
-
winfo_interps
(displayof=0)¶ Return the name of all Tcl interpreters for this display.
-
winfo_ismapped
()¶ Return true if this widget is mapped.
-
winfo_manager
()¶ Return the window manager name for this widget.
-
winfo_name
()¶ Return the name of this widget.
-
winfo_parent
()¶ Return the name of the parent of this widget.
-
winfo_pathname
(id, displayof=0)¶ Return the pathname of the widget given by ID.
-
winfo_pixels
(number)¶ Rounded integer value of winfo_fpixels.
-
winfo_pointerx
()¶ Return the x coordinate of the pointer on the root window.
-
winfo_pointerxy
()¶ Return a tuple of x and y coordinates of the pointer on the root window.
-
winfo_pointery
()¶ Return the y coordinate of the pointer on the root window.
-
winfo_reqheight
()¶ Return requested height of this widget.
-
winfo_reqwidth
()¶ Return requested width of this widget.
-
winfo_rgb
(color)¶ Return a tuple of integer RGB values in range(65536) for color in this widget.
-
winfo_rootx
()¶ Return x coordinate of upper left corner of this widget on the root window.
-
winfo_rooty
()¶ Return y coordinate of upper left corner of this widget on the root window.
-
winfo_screen
()¶ Return the screen name of this widget.
-
winfo_screencells
()¶ Return the number of the cells in the colormap of the screen of this widget.
-
winfo_screendepth
()¶ Return the number of bits per pixel of the root window of the screen of this widget.
-
winfo_screenheight
()¶ Return the number of pixels of the height of the screen of this widget in pixel.
-
winfo_screenmmheight
()¶ Return the number of pixels of the height of the screen of this widget in mm.
-
winfo_screenmmwidth
()¶ Return the number of pixels of the width of the screen of this widget in mm.
-
winfo_screenvisual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the default colormodel of this screen.
-
winfo_screenwidth
()¶ Return the number of pixels of the width of the screen of this widget in pixel.
-
winfo_server
()¶ Return information of the X-Server of the screen of this widget in the form “XmajorRminor vendor vendorVersion”.
-
winfo_toplevel
()¶ Return the toplevel widget of this widget.
-
winfo_viewable
()¶ Return true if the widget and all its higher ancestors are mapped.
-
winfo_visual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the colormodel of this widget.
-
winfo_visualid
()¶ Return the X identifier for the visual for this widget.
-
winfo_visualsavailable
(includeids=False)¶ Return a list of all visuals available for the screen of this widget.
Each item in the list consists of a visual name (see winfo_visual), a depth and if includeids is true is given also the X identifier.
-
winfo_vrootheight
()¶ Return the height of the virtual root window associated with this widget in pixels. If there is no virtual root window return the height of the screen.
-
winfo_vrootwidth
()¶ Return the width of the virtual root window associated with this widget in pixel. If there is no virtual root window return the width of the screen.
-
winfo_vrootx
()¶ Return the x offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_vrooty
()¶ Return the y offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_width
()¶ Return the width of this widget.
-
winfo_x
()¶ Return the x coordinate of the upper left corner of this widget in the parent.
-
winfo_y
()¶ Return the y coordinate of the upper left corner of this widget in the parent.
-
withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
wm_aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
wm_attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
wm_client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
wm_colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
wm_command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
wm_deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
wm_focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
wm_forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
wm_frame
()¶ Return identifier for decorative frame of this widget if present.
-
wm_geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
wm_grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
wm_group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
wm_iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
wm_iconify
()¶ Display widget as icon.
-
wm_iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
wm_iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
wm_iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
wm_iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
wm_iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
wm_manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
wm_maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
wm_positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
wm_resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
wm_sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
wm_title
(string=None)¶ Set the title of this widget.
-
wm_transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
wm_withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
-
class
robot.libraries.dialogs_py.
InputDialog
(message, default='', hidden=False)[source]¶ Bases:
robot.libraries.dialogs_py.TkDialog
-
after
(ms, func=None, *args)¶ Call function once after given time.
MS specifies the time in milliseconds. FUNC gives the function which shall be called. Additional parameters are given as parameters to the function call. Return identifier to cancel scheduling with after_cancel.
-
after_cancel
(id)¶ Cancel scheduling of function identified with ID.
Identifier returned by after or after_idle must be given as first parameter.
-
after_idle
(func, *args)¶ Call FUNC once if the Tcl main loop has no event to process.
Return an identifier to cancel the scheduling with after_cancel.
-
anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
bell
(displayof=0)¶ Ring a display’s bell.
-
bind
(sequence=None, func=None, add=None)¶ Bind to this widget at event SEQUENCE a call to function FUNC.
SEQUENCE is a string of concatenated event patterns. An event pattern is of the form <MODIFIER-MODIFIER-TYPE-DETAIL> where MODIFIER is one of Control, Mod2, M2, Shift, Mod3, M3, Lock, Mod4, M4, Button1, B1, Mod5, M5 Button2, B2, Meta, M, Button3, B3, Alt, Button4, B4, Double, Button5, B5 Triple, Mod1, M1. TYPE is one of Activate, Enter, Map, ButtonPress, Button, Expose, Motion, ButtonRelease FocusIn, MouseWheel, Circulate, FocusOut, Property, Colormap, Gravity Reparent, Configure, KeyPress, Key, Unmap, Deactivate, KeyRelease Visibility, Destroy, Leave and DETAIL is the button number for ButtonPress, ButtonRelease and DETAIL is the Keysym for KeyPress and KeyRelease. Examples are <Control-Button-1> for pressing Control and mouse button 1 or <Alt-A> for pressing A and the Alt key (KeyPress can be omitted). An event pattern can also be a virtual event of the form <<AString>> where AString can be arbitrary. This event can be generated by event_generate. If events are concatenated they must appear shortly after each other.
FUNC will be called if the event sequence occurs with an instance of Event as argument. If the return value of FUNC is “break” no further bound function is invoked.
An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function.
Bind will return an identifier to allow deletion of the bound function with unbind without memory leak.
If FUNC or SEQUENCE is omitted the bound function or list of bound events are returned.
-
bind_all
(sequence=None, func=None, add=None)¶ Bind to all widgets at an event SEQUENCE a call to function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
-
bind_class
(className, sequence=None, func=None, add=None)¶ Bind to widgets with bindtag CLASSNAME at event SEQUENCE a call of function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
Set or get the list of bindtags for this widget.
With no argument return the list of all bindtags associated with this widget. With a list of strings as argument the bindtags are set to this list. The bindtags determine in which order events are processed (see bind).
-
cget
(key)¶ Return the resource value for a KEY given as string.
-
client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
clipboard_append
(string, **kw)¶ Append STRING to the Tk clipboard.
A widget specified at the optional displayof keyword argument specifies the target display. The clipboard can be retrieved with selection_get.
-
clipboard_clear
(**kw)¶ Clear the data in the Tk clipboard.
A widget specified for the optional displayof keyword argument specifies the target display.
-
clipboard_get
(**kw)¶ Retrieve data from the clipboard on window’s display.
The window keyword defaults to the root window of the Tkinter application.
The type keyword specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING, except on X11, where the default is to try UTF8_STRING and fall back to STRING.
This command is equivalent to:
selection_get(CLIPBOARD)
-
colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
config
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
configure
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
deletecommand
(name)¶ Internal function.
Delete the Tcl command provided in NAME.
-
destroy
()¶ Destroy this and all descendants widgets.
-
event_add
(virtual, *sequences)¶ Bind a virtual event VIRTUAL (of the form <<Name>>) to an event SEQUENCE such that the virtual event is triggered whenever SEQUENCE occurs.
-
event_delete
(virtual, *sequences)¶ Unbind a virtual event VIRTUAL from SEQUENCE.
-
event_generate
(sequence, **kw)¶ Generate an event SEQUENCE. Additional keyword arguments specify parameter of the event (e.g. x, y, rootx, rooty).
-
event_info
(virtual=None)¶ Return a list of all virtual events or the information about the SEQUENCE bound to the virtual event VIRTUAL.
-
focus
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focus_displayof
()¶ Return the widget which has currently the focus on the display where this widget is located.
Return None if the application does not have the focus.
-
focus_force
()¶ Direct input focus to this widget even if the application does not have the focus. Use with caution!
-
focus_get
()¶ Return the widget which has currently the focus in the application.
Use focus_displayof to allow working with several displays. Return None if application does not have the focus.
-
focus_lastfor
()¶ Return the widget which would have the focus if top level for this widget gets the focus from the window manager.
-
focus_set
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
frame
()¶ Return identifier for decorative frame of this widget if present.
-
geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
getboolean
(s)¶ Return a boolean value for Tcl boolean values true and false given as parameter.
-
getdouble
(s)¶
-
getint
(s)¶
-
getvar
(name='PY_VAR')¶ Return value of Tcl variable NAME.
-
grab_current
()¶ Return widget which has currently the grab in this application or None.
-
grab_release
()¶ Release grab for this widget if currently set.
-
grab_set
()¶ Set grab for this widget.
A grab directs all events to this and descendant widgets in the application.
-
grab_set_global
()¶ Set global grab for this widget.
A global grab directs all events to this and descendant widgets on the display. Use with caution - other applications do not get events anymore.
-
grab_status
()¶ Return None, “local” or “global” if this widget has no, a local or a global grab.
-
grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
grid_anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
grid_bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
grid_columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
grid_location
(x, y)¶ Return a tuple of column and row which identify the cell at which the pixel at position X and Y inside the master widget is located.
-
grid_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given, the current setting will be returned.
-
grid_rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
grid_size
()¶ Return a tuple of the number of column and rows in the grid.
-
grid_slaves
(row=None, column=None)¶ Return a list of all slaves of this widget in its packing order.
-
group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
iconify
()¶ Display widget as icon.
-
iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
image_names
()¶ Return a list of all existing image names.
-
image_types
()¶ Return a list of all available image types (e.g. photo bitmap).
-
info_patchlevel
()¶ Returns the exact version of the Tcl library.
-
keys
()¶ Return a list of all resource names of this widget.
-
lift
(aboveThis=None)¶ Raise this widget in the stacking order.
-
lower
(belowThis=None)¶ Lower this widget in the stacking order.
-
mainloop
(n=0)¶ Call the mainloop of Tk.
-
manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
nametowidget
(name)¶ Return the Tkinter instance of a widget identified by its Tcl name NAME.
-
option_add
(pattern, value, priority=None)¶ Set a VALUE (second parameter) for an option PATTERN (first parameter).
An optional third parameter gives the numeric priority (defaults to 80).
-
option_clear
()¶ Clear the option database.
It will be reloaded if option_add is called.
-
option_get
(name, className)¶ Return the value for an option NAME for this widget with CLASSNAME.
Values with higher priority override lower values.
-
option_readfile
(fileName, priority=None)¶ Read file FILENAME into the option database.
An optional second parameter gives the numeric priority.
-
overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
pack_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
pack_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
place_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
quit
()¶ Quit the Tcl interpreter. All widgets will be destroyed.
-
register
(func, subst=None, needcleanup=1)¶ Return a newly created Tcl function. If this function is called, the Python function FUNC will be executed. An optional function SUBST can be given which will be executed before FUNC.
-
resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
selection_clear
(**kw)¶ Clear the current X selection.
-
selection_get
(**kw)¶ Return the contents of the current X selection.
A keyword parameter selection specifies the name of the selection and defaults to PRIMARY. A keyword parameter displayof specifies a widget on the display to use. A keyword parameter type specifies the form of data to be fetched, defaulting to STRING except on X11, where UTF8_STRING is tried before STRING.
-
selection_handle
(command, **kw)¶ Specify a function COMMAND to call if the X selection owned by this widget is queried by another application.
This function must return the contents of the selection. The function will be called with the arguments OFFSET and LENGTH which allows the chunking of very long selections. The following keyword parameters can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
selection_own
(**kw)¶ Become owner of X selection.
A keyword parameter selection specifies the name of the selection (default PRIMARY).
-
selection_own_get
(**kw)¶ Return owner of X selection.
The following keyword parameter can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
send
(interp, cmd, *args)¶ Send Tcl command CMD to different interpreter INTERP to be executed.
-
setvar
(name='PY_VAR', value='1')¶ Set Tcl variable NAME to VALUE.
-
show
() → Any¶
-
size
()¶ Return a tuple of the number of column and rows in the grid.
-
sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
title
(string=None)¶ Set the title of this widget.
-
tk_bisque
()¶ Change the color scheme to light brown as used in Tk 3.6 and before.
-
tk_focusFollowsMouse
()¶ The widget under mouse will get automatically focus. Can not be disabled easily.
-
tk_focusNext
()¶ Return the next widget in the focus order which follows widget which has currently the focus.
The focus order first goes to the next child, then to the children of the child recursively and then to the next sibling which is higher in the stacking order. A widget is omitted if it has the takefocus resource set to 0.
-
tk_focusPrev
()¶ Return previous widget in the focus order. See tk_focusNext for details.
-
tk_setPalette
(*args, **kw)¶ Set a new color scheme for all widget elements.
A single color as argument will cause that all colors of Tk widget elements are derived from this. Alternatively several keyword parameters and its associated colors can be given. The following keywords are valid: activeBackground, foreground, selectColor, activeForeground, highlightBackground, selectBackground, background, highlightColor, selectForeground, disabledForeground, insertBackground, troughColor.
-
tk_strictMotif
(boolean=None)¶ Set Tcl internal variable, whether the look and feel should adhere to Motif.
A parameter of 1 means adhere to Motif (e.g. no color change if mouse passes over slider). Returns the set value.
-
tkraise
(aboveThis=None)¶ Raise this widget in the stacking order.
-
transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
unbind
(sequence, funcid=None)¶ Unbind for this widget for event SEQUENCE the function identified with FUNCID.
-
unbind_all
(sequence)¶ Unbind for all widgets for event SEQUENCE all functions.
-
unbind_class
(className, sequence)¶ Unbind for all widgets with bindtag CLASSNAME for event SEQUENCE all functions.
-
update
()¶ Enter event loop until all pending events have been processed by Tcl.
-
update_idletasks
()¶ Enter event loop until all idle callbacks have been called. This will update the display of windows but not process events caused by the user.
-
wait_variable
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
wait_visibility
(window=None)¶ Wait until the visibility of a WIDGET changes (e.g. it appears).
If no parameter is given self is used.
-
wait_window
(window=None)¶ Wait until a WIDGET is destroyed.
If no parameter is given self is used.
-
waitvar
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
winfo_atom
(name, displayof=0)¶ Return integer which represents atom NAME.
-
winfo_atomname
(id, displayof=0)¶ Return name of atom with identifier ID.
-
winfo_cells
()¶ Return number of cells in the colormap for this widget.
-
winfo_children
()¶ Return a list of all widgets which are children of this widget.
-
winfo_class
()¶ Return window class name of this widget.
-
winfo_colormapfull
()¶ Return True if at the last color request the colormap was full.
-
winfo_containing
(rootX, rootY, displayof=0)¶ Return the widget which is at the root coordinates ROOTX, ROOTY.
-
winfo_depth
()¶ Return the number of bits per pixel.
-
winfo_exists
()¶ Return true if this widget exists.
-
winfo_fpixels
(number)¶ Return the number of pixels for the given distance NUMBER (e.g. “3c”) as float.
-
winfo_geometry
()¶ Return geometry string for this widget in the form “widthxheight+X+Y”.
-
winfo_height
()¶ Return height of this widget.
-
winfo_id
()¶ Return identifier ID for this widget.
-
winfo_interps
(displayof=0)¶ Return the name of all Tcl interpreters for this display.
-
winfo_ismapped
()¶ Return true if this widget is mapped.
-
winfo_manager
()¶ Return the window manager name for this widget.
-
winfo_name
()¶ Return the name of this widget.
-
winfo_parent
()¶ Return the name of the parent of this widget.
-
winfo_pathname
(id, displayof=0)¶ Return the pathname of the widget given by ID.
-
winfo_pixels
(number)¶ Rounded integer value of winfo_fpixels.
-
winfo_pointerx
()¶ Return the x coordinate of the pointer on the root window.
-
winfo_pointerxy
()¶ Return a tuple of x and y coordinates of the pointer on the root window.
-
winfo_pointery
()¶ Return the y coordinate of the pointer on the root window.
-
winfo_reqheight
()¶ Return requested height of this widget.
-
winfo_reqwidth
()¶ Return requested width of this widget.
-
winfo_rgb
(color)¶ Return a tuple of integer RGB values in range(65536) for color in this widget.
-
winfo_rootx
()¶ Return x coordinate of upper left corner of this widget on the root window.
-
winfo_rooty
()¶ Return y coordinate of upper left corner of this widget on the root window.
-
winfo_screen
()¶ Return the screen name of this widget.
-
winfo_screencells
()¶ Return the number of the cells in the colormap of the screen of this widget.
-
winfo_screendepth
()¶ Return the number of bits per pixel of the root window of the screen of this widget.
-
winfo_screenheight
()¶ Return the number of pixels of the height of the screen of this widget in pixel.
-
winfo_screenmmheight
()¶ Return the number of pixels of the height of the screen of this widget in mm.
-
winfo_screenmmwidth
()¶ Return the number of pixels of the width of the screen of this widget in mm.
-
winfo_screenvisual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the default colormodel of this screen.
-
winfo_screenwidth
()¶ Return the number of pixels of the width of the screen of this widget in pixel.
-
winfo_server
()¶ Return information of the X-Server of the screen of this widget in the form “XmajorRminor vendor vendorVersion”.
-
winfo_toplevel
()¶ Return the toplevel widget of this widget.
-
winfo_viewable
()¶ Return true if the widget and all its higher ancestors are mapped.
-
winfo_visual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the colormodel of this widget.
-
winfo_visualid
()¶ Return the X identifier for the visual for this widget.
-
winfo_visualsavailable
(includeids=False)¶ Return a list of all visuals available for the screen of this widget.
Each item in the list consists of a visual name (see winfo_visual), a depth and if includeids is true is given also the X identifier.
-
winfo_vrootheight
()¶ Return the height of the virtual root window associated with this widget in pixels. If there is no virtual root window return the height of the screen.
-
winfo_vrootwidth
()¶ Return the width of the virtual root window associated with this widget in pixel. If there is no virtual root window return the width of the screen.
-
winfo_vrootx
()¶ Return the x offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_vrooty
()¶ Return the y offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_width
()¶ Return the width of this widget.
-
winfo_x
()¶ Return the x coordinate of the upper left corner of this widget in the parent.
-
winfo_y
()¶ Return the y coordinate of the upper left corner of this widget in the parent.
-
withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
wm_aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
wm_attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
wm_client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
wm_colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
wm_command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
wm_deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
wm_focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
wm_forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
wm_frame
()¶ Return identifier for decorative frame of this widget if present.
-
wm_geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
wm_grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
wm_group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
wm_iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
wm_iconify
()¶ Display widget as icon.
-
wm_iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
wm_iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
wm_iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
wm_iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
wm_iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
wm_manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
wm_maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
wm_positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
wm_resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
wm_sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
wm_title
(string=None)¶ Set the title of this widget.
-
wm_transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
wm_withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
-
class
robot.libraries.dialogs_py.
SelectionDialog
(message, value=None, **config)[source]¶ Bases:
robot.libraries.dialogs_py.TkDialog
-
after
(ms, func=None, *args)¶ Call function once after given time.
MS specifies the time in milliseconds. FUNC gives the function which shall be called. Additional parameters are given as parameters to the function call. Return identifier to cancel scheduling with after_cancel.
-
after_cancel
(id)¶ Cancel scheduling of function identified with ID.
Identifier returned by after or after_idle must be given as first parameter.
-
after_idle
(func, *args)¶ Call FUNC once if the Tcl main loop has no event to process.
Return an identifier to cancel the scheduling with after_cancel.
-
anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
bell
(displayof=0)¶ Ring a display’s bell.
-
bind
(sequence=None, func=None, add=None)¶ Bind to this widget at event SEQUENCE a call to function FUNC.
SEQUENCE is a string of concatenated event patterns. An event pattern is of the form <MODIFIER-MODIFIER-TYPE-DETAIL> where MODIFIER is one of Control, Mod2, M2, Shift, Mod3, M3, Lock, Mod4, M4, Button1, B1, Mod5, M5 Button2, B2, Meta, M, Button3, B3, Alt, Button4, B4, Double, Button5, B5 Triple, Mod1, M1. TYPE is one of Activate, Enter, Map, ButtonPress, Button, Expose, Motion, ButtonRelease FocusIn, MouseWheel, Circulate, FocusOut, Property, Colormap, Gravity Reparent, Configure, KeyPress, Key, Unmap, Deactivate, KeyRelease Visibility, Destroy, Leave and DETAIL is the button number for ButtonPress, ButtonRelease and DETAIL is the Keysym for KeyPress and KeyRelease. Examples are <Control-Button-1> for pressing Control and mouse button 1 or <Alt-A> for pressing A and the Alt key (KeyPress can be omitted). An event pattern can also be a virtual event of the form <<AString>> where AString can be arbitrary. This event can be generated by event_generate. If events are concatenated they must appear shortly after each other.
FUNC will be called if the event sequence occurs with an instance of Event as argument. If the return value of FUNC is “break” no further bound function is invoked.
An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function.
Bind will return an identifier to allow deletion of the bound function with unbind without memory leak.
If FUNC or SEQUENCE is omitted the bound function or list of bound events are returned.
-
bind_all
(sequence=None, func=None, add=None)¶ Bind to all widgets at an event SEQUENCE a call to function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
-
bind_class
(className, sequence=None, func=None, add=None)¶ Bind to widgets with bindtag CLASSNAME at event SEQUENCE a call of function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
Set or get the list of bindtags for this widget.
With no argument return the list of all bindtags associated with this widget. With a list of strings as argument the bindtags are set to this list. The bindtags determine in which order events are processed (see bind).
-
cget
(key)¶ Return the resource value for a KEY given as string.
-
client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
clipboard_append
(string, **kw)¶ Append STRING to the Tk clipboard.
A widget specified at the optional displayof keyword argument specifies the target display. The clipboard can be retrieved with selection_get.
-
clipboard_clear
(**kw)¶ Clear the data in the Tk clipboard.
A widget specified for the optional displayof keyword argument specifies the target display.
-
clipboard_get
(**kw)¶ Retrieve data from the clipboard on window’s display.
The window keyword defaults to the root window of the Tkinter application.
The type keyword specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING, except on X11, where the default is to try UTF8_STRING and fall back to STRING.
This command is equivalent to:
selection_get(CLIPBOARD)
-
colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
config
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
configure
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
deletecommand
(name)¶ Internal function.
Delete the Tcl command provided in NAME.
-
destroy
()¶ Destroy this and all descendants widgets.
-
event_add
(virtual, *sequences)¶ Bind a virtual event VIRTUAL (of the form <<Name>>) to an event SEQUENCE such that the virtual event is triggered whenever SEQUENCE occurs.
-
event_delete
(virtual, *sequences)¶ Unbind a virtual event VIRTUAL from SEQUENCE.
-
event_generate
(sequence, **kw)¶ Generate an event SEQUENCE. Additional keyword arguments specify parameter of the event (e.g. x, y, rootx, rooty).
-
event_info
(virtual=None)¶ Return a list of all virtual events or the information about the SEQUENCE bound to the virtual event VIRTUAL.
-
focus
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focus_displayof
()¶ Return the widget which has currently the focus on the display where this widget is located.
Return None if the application does not have the focus.
-
focus_force
()¶ Direct input focus to this widget even if the application does not have the focus. Use with caution!
-
focus_get
()¶ Return the widget which has currently the focus in the application.
Use focus_displayof to allow working with several displays. Return None if application does not have the focus.
-
focus_lastfor
()¶ Return the widget which would have the focus if top level for this widget gets the focus from the window manager.
-
focus_set
()¶ Direct input focus to this widget.
If the application currently does not have the focus this widget will get the focus if the application gets the focus through the window manager.
-
focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
frame
()¶ Return identifier for decorative frame of this widget if present.
-
geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
getboolean
(s)¶ Return a boolean value for Tcl boolean values true and false given as parameter.
-
getdouble
(s)¶
-
getint
(s)¶
-
getvar
(name='PY_VAR')¶ Return value of Tcl variable NAME.
-
grab_current
()¶ Return widget which has currently the grab in this application or None.
-
grab_release
()¶ Release grab for this widget if currently set.
-
grab_set
()¶ Set grab for this widget.
A grab directs all events to this and descendant widgets in the application.
-
grab_set_global
()¶ Set global grab for this widget.
A global grab directs all events to this and descendant widgets on the display. Use with caution - other applications do not get events anymore.
-
grab_status
()¶ Return None, “local” or “global” if this widget has no, a local or a global grab.
-
grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
grid_anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
grid_bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
grid_columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
grid_location
(x, y)¶ Return a tuple of column and row which identify the cell at which the pixel at position X and Y inside the master widget is located.
-
grid_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given, the current setting will be returned.
-
grid_rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
grid_size
()¶ Return a tuple of the number of column and rows in the grid.
-
grid_slaves
(row=None, column=None)¶ Return a list of all slaves of this widget in its packing order.
-
group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
iconify
()¶ Display widget as icon.
-
iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
image_names
()¶ Return a list of all existing image names.
-
image_types
()¶ Return a list of all available image types (e.g. photo bitmap).
-
info_patchlevel
()¶ Returns the exact version of the Tcl library.
-
keys
()¶ Return a list of all resource names of this widget.
-
lift
(aboveThis=None)¶ Raise this widget in the stacking order.
-
lower
(belowThis=None)¶ Lower this widget in the stacking order.
-
mainloop
(n=0)¶ Call the mainloop of Tk.
-
manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
nametowidget
(name)¶ Return the Tkinter instance of a widget identified by its Tcl name NAME.
-
option_add
(pattern, value, priority=None)¶ Set a VALUE (second parameter) for an option PATTERN (first parameter).
An optional third parameter gives the numeric priority (defaults to 80).
-
option_clear
()¶ Clear the option database.
It will be reloaded if option_add is called.
-
option_get
(name, className)¶ Return the value for an option NAME for this widget with CLASSNAME.
Values with higher priority override lower values.
-
option_readfile
(fileName, priority=None)¶ Read file FILENAME into the option database.
An optional second parameter gives the numeric priority.
-
overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
pack_propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
pack_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
place_slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
propagate
(flag=['_noarg_'])¶ Set or get the status for propagation of geometry information.
A boolean argument specifies whether the geometry information of the slaves will determine the size of this widget. If no argument is given the current setting will be returned.
-
protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
quit
()¶ Quit the Tcl interpreter. All widgets will be destroyed.
-
register
(func, subst=None, needcleanup=1)¶ Return a newly created Tcl function. If this function is called, the Python function FUNC will be executed. An optional function SUBST can be given which will be executed before FUNC.
-
resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
rowconfigure
(index, cnf={}, **kw)¶ Configure row INDEX of a grid.
Valid resources are minsize (minimum size of the row), weight (how much does additional space propagate to this row) and pad (how much space to let additionally).
-
selection_clear
(**kw)¶ Clear the current X selection.
-
selection_get
(**kw)¶ Return the contents of the current X selection.
A keyword parameter selection specifies the name of the selection and defaults to PRIMARY. A keyword parameter displayof specifies a widget on the display to use. A keyword parameter type specifies the form of data to be fetched, defaulting to STRING except on X11, where UTF8_STRING is tried before STRING.
-
selection_handle
(command, **kw)¶ Specify a function COMMAND to call if the X selection owned by this widget is queried by another application.
This function must return the contents of the selection. The function will be called with the arguments OFFSET and LENGTH which allows the chunking of very long selections. The following keyword parameters can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
selection_own
(**kw)¶ Become owner of X selection.
A keyword parameter selection specifies the name of the selection (default PRIMARY).
-
selection_own_get
(**kw)¶ Return owner of X selection.
The following keyword parameter can be provided: selection - name of the selection (default PRIMARY), type - type of the selection (e.g. STRING, FILE_NAME).
-
send
(interp, cmd, *args)¶ Send Tcl command CMD to different interpreter INTERP to be executed.
-
setvar
(name='PY_VAR', value='1')¶ Set Tcl variable NAME to VALUE.
-
show
() → Any¶
-
size
()¶ Return a tuple of the number of column and rows in the grid.
-
sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
slaves
()¶ Return a list of all slaves of this widget in its packing order.
-
state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
title
(string=None)¶ Set the title of this widget.
-
tk_bisque
()¶ Change the color scheme to light brown as used in Tk 3.6 and before.
-
tk_focusFollowsMouse
()¶ The widget under mouse will get automatically focus. Can not be disabled easily.
-
tk_focusNext
()¶ Return the next widget in the focus order which follows widget which has currently the focus.
The focus order first goes to the next child, then to the children of the child recursively and then to the next sibling which is higher in the stacking order. A widget is omitted if it has the takefocus resource set to 0.
-
tk_focusPrev
()¶ Return previous widget in the focus order. See tk_focusNext for details.
-
tk_setPalette
(*args, **kw)¶ Set a new color scheme for all widget elements.
A single color as argument will cause that all colors of Tk widget elements are derived from this. Alternatively several keyword parameters and its associated colors can be given. The following keywords are valid: activeBackground, foreground, selectColor, activeForeground, highlightBackground, selectBackground, background, highlightColor, selectForeground, disabledForeground, insertBackground, troughColor.
-
tk_strictMotif
(boolean=None)¶ Set Tcl internal variable, whether the look and feel should adhere to Motif.
A parameter of 1 means adhere to Motif (e.g. no color change if mouse passes over slider). Returns the set value.
-
tkraise
(aboveThis=None)¶ Raise this widget in the stacking order.
-
transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
unbind
(sequence, funcid=None)¶ Unbind for this widget for event SEQUENCE the function identified with FUNCID.
-
unbind_all
(sequence)¶ Unbind for all widgets for event SEQUENCE all functions.
-
unbind_class
(className, sequence)¶ Unbind for all widgets with bindtag CLASSNAME for event SEQUENCE all functions.
-
update
()¶ Enter event loop until all pending events have been processed by Tcl.
-
update_idletasks
()¶ Enter event loop until all idle callbacks have been called. This will update the display of windows but not process events caused by the user.
-
wait_variable
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
wait_visibility
(window=None)¶ Wait until the visibility of a WIDGET changes (e.g. it appears).
If no parameter is given self is used.
-
wait_window
(window=None)¶ Wait until a WIDGET is destroyed.
If no parameter is given self is used.
-
waitvar
(name='PY_VAR')¶ Wait until the variable is modified.
A parameter of type IntVar, StringVar, DoubleVar or BooleanVar must be given.
-
winfo_atom
(name, displayof=0)¶ Return integer which represents atom NAME.
-
winfo_atomname
(id, displayof=0)¶ Return name of atom with identifier ID.
-
winfo_cells
()¶ Return number of cells in the colormap for this widget.
-
winfo_children
()¶ Return a list of all widgets which are children of this widget.
-
winfo_class
()¶ Return window class name of this widget.
-
winfo_colormapfull
()¶ Return True if at the last color request the colormap was full.
-
winfo_containing
(rootX, rootY, displayof=0)¶ Return the widget which is at the root coordinates ROOTX, ROOTY.
-
winfo_depth
()¶ Return the number of bits per pixel.
-
winfo_exists
()¶ Return true if this widget exists.
-
winfo_fpixels
(number)¶ Return the number of pixels for the given distance NUMBER (e.g. “3c”) as float.
-
winfo_geometry
()¶ Return geometry string for this widget in the form “widthxheight+X+Y”.
-
winfo_height
()¶ Return height of this widget.
-
winfo_id
()¶ Return identifier ID for this widget.
-
winfo_interps
(displayof=0)¶ Return the name of all Tcl interpreters for this display.
-
winfo_ismapped
()¶ Return true if this widget is mapped.
-
winfo_manager
()¶ Return the window manager name for this widget.
-
winfo_name
()¶ Return the name of this widget.
-
winfo_parent
()¶ Return the name of the parent of this widget.
-
winfo_pathname
(id, displayof=0)¶ Return the pathname of the widget given by ID.
-
winfo_pixels
(number)¶ Rounded integer value of winfo_fpixels.
-
winfo_pointerx
()¶ Return the x coordinate of the pointer on the root window.
-
winfo_pointerxy
()¶ Return a tuple of x and y coordinates of the pointer on the root window.
-
winfo_pointery
()¶ Return the y coordinate of the pointer on the root window.
-
winfo_reqheight
()¶ Return requested height of this widget.
-
winfo_reqwidth
()¶ Return requested width of this widget.
-
winfo_rgb
(color)¶ Return a tuple of integer RGB values in range(65536) for color in this widget.
-
winfo_rootx
()¶ Return x coordinate of upper left corner of this widget on the root window.
-
winfo_rooty
()¶ Return y coordinate of upper left corner of this widget on the root window.
-
winfo_screen
()¶ Return the screen name of this widget.
-
winfo_screencells
()¶ Return the number of the cells in the colormap of the screen of this widget.
-
winfo_screendepth
()¶ Return the number of bits per pixel of the root window of the screen of this widget.
-
winfo_screenheight
()¶ Return the number of pixels of the height of the screen of this widget in pixel.
-
winfo_screenmmheight
()¶ Return the number of pixels of the height of the screen of this widget in mm.
-
winfo_screenmmwidth
()¶ Return the number of pixels of the width of the screen of this widget in mm.
-
winfo_screenvisual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the default colormodel of this screen.
-
winfo_screenwidth
()¶ Return the number of pixels of the width of the screen of this widget in pixel.
-
winfo_server
()¶ Return information of the X-Server of the screen of this widget in the form “XmajorRminor vendor vendorVersion”.
-
winfo_toplevel
()¶ Return the toplevel widget of this widget.
-
winfo_viewable
()¶ Return true if the widget and all its higher ancestors are mapped.
-
winfo_visual
()¶ Return one of the strings directcolor, grayscale, pseudocolor, staticcolor, staticgray, or truecolor for the colormodel of this widget.
-
winfo_visualid
()¶ Return the X identifier for the visual for this widget.
-
winfo_visualsavailable
(includeids=False)¶ Return a list of all visuals available for the screen of this widget.
Each item in the list consists of a visual name (see winfo_visual), a depth and if includeids is true is given also the X identifier.
-
winfo_vrootheight
()¶ Return the height of the virtual root window associated with this widget in pixels. If there is no virtual root window return the height of the screen.
-
winfo_vrootwidth
()¶ Return the width of the virtual root window associated with this widget in pixel. If there is no virtual root window return the width of the screen.
-
winfo_vrootx
()¶ Return the x offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_vrooty
()¶ Return the y offset of the virtual root relative to the root window of the screen of this widget.
-
winfo_width
()¶ Return the width of this widget.
-
winfo_x
()¶ Return the x coordinate of the upper left corner of this widget in the parent.
-
winfo_y
()¶ Return the y coordinate of the upper left corner of this widget in the parent.
-
withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
wm_aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
wm_attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
wm_client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
wm_colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
wm_command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
wm_deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
wm_focusmodel
(model=None)¶ Set focus model to MODEL. “active” means that this widget will claim the focus itself, “passive” means that the window manager shall give the focus. Return current focus model if MODEL is None.
-
wm_forget
(window)¶ The window will be unmapped from the screen and will no longer be managed by wm. toplevel windows will be treated like frame windows once they are no longer managed by wm, however, the menu option configuration will be remembered and the menus will return once the widget is managed again.
-
wm_frame
()¶ Return identifier for decorative frame of this widget if present.
-
wm_geometry
(newGeometry=None)¶ Set geometry to NEWGEOMETRY of the form =widthxheight+x+y. Return current value if None is given.
-
wm_grid
(baseWidth=None, baseHeight=None, widthInc=None, heightInc=None)¶ Instruct the window manager that this widget shall only be resized on grid boundaries. WIDTHINC and HEIGHTINC are the width and height of a grid unit in pixels. BASEWIDTH and BASEHEIGHT are the number of grid units requested in Tk_GeometryRequest.
-
wm_group
(pathName=None)¶ Set the group leader widgets for related widgets to PATHNAME. Return the group leader of this widget if None is given.
-
wm_iconbitmap
(bitmap=None, default=None)¶ Set bitmap for the iconified widget to BITMAP. Return the bitmap if None is given.
Under Windows, the DEFAULT parameter can be used to set the icon for the widget and any descendants that don’t have an icon set explicitly. DEFAULT can be the relative path to a .ico file (example: root.iconbitmap(default=’myicon.ico’) ). See Tk documentation for more information.
-
wm_iconify
()¶ Display widget as icon.
-
wm_iconmask
(bitmap=None)¶ Set mask for the icon bitmap of this widget. Return the mask if None is given.
-
wm_iconname
(newName=None)¶ Set the name of the icon for this widget. Return the name if None is given.
-
wm_iconphoto
(default=False, *args)¶ Sets the titlebar icon for this window based on the named photo images passed through args. If default is True, this is applied to all future created toplevels as well.
The data in the images is taken as a snapshot at the time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes to be provided. The window manager may scale provided icons to an appropriate size.
On Windows, the images are packed into a Windows icon structure. This will override an icon specified to wm_iconbitmap, and vice versa.
On X, the images are arranged into the _NET_WM_ICON X property, which most modern window managers support. An icon specified by wm_iconbitmap may exist simultaneously.
On Macintosh, this currently does nothing.
-
wm_iconposition
(x=None, y=None)¶ Set the position of the icon of this widget to X and Y. Return a tuple of the current values of X and X if None is given.
-
wm_iconwindow
(pathName=None)¶ Set widget PATHNAME to be displayed instead of icon. Return the current value if None is given.
-
wm_manage
(widget)¶ The widget specified will become a stand alone top-level window. The window will be decorated with the window managers title bar, etc.
-
wm_maxsize
(width=None, height=None)¶ Set max WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_minsize
(width=None, height=None)¶ Set min WIDTH and HEIGHT for this widget. If the window is gridded the values are given in grid units. Return the current values if None is given.
-
wm_overrideredirect
(boolean=None)¶ Instruct the window manager to ignore this widget if BOOLEAN is given with 1. Return the current value if None is given.
-
wm_positionfrom
(who=None)¶ Instruct the window manager that the position of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_protocol
(name=None, func=None)¶ Bind function FUNC to command NAME for this widget. Return the function bound to NAME if None is given. NAME could be e.g. “WM_SAVE_YOURSELF” or “WM_DELETE_WINDOW”.
-
wm_resizable
(width=None, height=None)¶ Instruct the window manager whether this width can be resized in WIDTH or HEIGHT. Both values are boolean values.
-
wm_sizefrom
(who=None)¶ Instruct the window manager that the size of this widget shall be defined by the user if WHO is “user”, and by its own policy if WHO is “program”.
-
wm_state
(newstate=None)¶ Query or set the state of this widget as one of normal, icon, iconic (see wm_iconwindow), withdrawn, or zoomed (Windows only).
-
wm_title
(string=None)¶ Set the title of this widget.
-
wm_transient
(master=None)¶ Instruct the window manager that this widget is transient with regard to widget MASTER.
-
wm_withdraw
()¶ Withdraw this widget from the screen such that it is unmapped and forgotten by the window manager. Re-draw it with wm_deiconify.
-
-
class
robot.libraries.dialogs_py.
MultipleSelectionDialog
(message, value=None, **config)[source]¶ Bases:
robot.libraries.dialogs_py.TkDialog
-
after
(ms, func=None, *args)¶ Call function once after given time.
MS specifies the time in milliseconds. FUNC gives the function which shall be called. Additional parameters are given as parameters to the function call. Return identifier to cancel scheduling with after_cancel.
-
after_cancel
(id)¶ Cancel scheduling of function identified with ID.
Identifier returned by after or after_idle must be given as first parameter.
-
after_idle
(func, *args)¶ Call FUNC once if the Tcl main loop has no event to process.
Return an identifier to cancel the scheduling with after_cancel.
-
anchor
(anchor=None)¶ The anchor value controls how to place the grid within the master when no row/column has any weight.
The default anchor is nw.
-
aspect
(minNumer=None, minDenom=None, maxNumer=None, maxDenom=None)¶ Instruct the window manager to set the aspect ratio (width/height) of this widget to be between MINNUMER/MINDENOM and MAXNUMER/MAXDENOM. Return a tuple of the actual values if no argument is given.
-
attributes
(*args)¶ This subcommand returns or sets platform specific attributes
The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows:
On Windows, -disabled gets or sets whether the window is in a disabled state. -toolwindow gets or sets the style of the window to toolwindow (as defined in the MSDN). -topmost gets or sets whether this is a topmost window (displays above all other windows).
On Macintosh, XXXXX
On Unix, there are currently no special attribute values.
-
bbox
(column=None, row=None, col2=None, row2=None)¶ Return a tuple of integer coordinates for the bounding box of this widget controlled by the geometry manager grid.
If COLUMN, ROW is given the bounding box applies from the cell with row and column 0 to the specified cell. If COL2 and ROW2 are given the bounding box starts at that cell.
The returned integers specify the offset of the upper left corner in the master widget and the width and height.
-
bell
(displayof=0)¶ Ring a display’s bell.
-
bind
(sequence=None, func=None, add=None)¶ Bind to this widget at event SEQUENCE a call to function FUNC.
SEQUENCE is a string of concatenated event patterns. An event pattern is of the form <MODIFIER-MODIFIER-TYPE-DETAIL> where MODIFIER is one of Control, Mod2, M2, Shift, Mod3, M3, Lock, Mod4, M4, Button1, B1, Mod5, M5 Button2, B2, Meta, M, Button3, B3, Alt, Button4, B4, Double, Button5, B5 Triple, Mod1, M1. TYPE is one of Activate, Enter, Map, ButtonPress, Button, Expose, Motion, ButtonRelease FocusIn, MouseWheel, Circulate, FocusOut, Property, Colormap, Gravity Reparent, Configure, KeyPress, Key, Unmap, Deactivate, KeyRelease Visibility, Destroy, Leave and DETAIL is the button number for ButtonPress, ButtonRelease and DETAIL is the Keysym for KeyPress and KeyRelease. Examples are <Control-Button-1> for pressing Control and mouse button 1 or <Alt-A> for pressing A and the Alt key (KeyPress can be omitted). An event pattern can also be a virtual event of the form <<AString>> where AString can be arbitrary. This event can be generated by event_generate. If events are concatenated they must appear shortly after each other.
FUNC will be called if the event sequence occurs with an instance of Event as argument. If the return value of FUNC is “break” no further bound function is invoked.
An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function.
Bind will return an identifier to allow deletion of the bound function with unbind without memory leak.
If FUNC or SEQUENCE is omitted the bound function or list of bound events are returned.
-
bind_all
(sequence=None, func=None, add=None)¶ Bind to all widgets at an event SEQUENCE a call to function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
-
bind_class
(className, sequence=None, func=None, add=None)¶ Bind to widgets with bindtag CLASSNAME at event SEQUENCE a call of function FUNC. An additional boolean parameter ADD specifies whether FUNC will be called additionally to the other bound function or whether it will replace the previous function. See bind for the return value.
Set or get the list of bindtags for this widget.
With no argument return the list of all bindtags associated with this widget. With a list of strings as argument the bindtags are set to this list. The bindtags determine in which order events are processed (see bind).
-
cget
(key)¶ Return the resource value for a KEY given as string.
-
client
(name=None)¶ Store NAME in WM_CLIENT_MACHINE property of this widget. Return current value.
-
clipboard_append
(string, **kw)¶ Append STRING to the Tk clipboard.
A widget specified at the optional displayof keyword argument specifies the target display. The clipboard can be retrieved with selection_get.
-
clipboard_clear
(**kw)¶ Clear the data in the Tk clipboard.
A widget specified for the optional displayof keyword argument specifies the target display.
-
clipboard_get
(**kw)¶ Retrieve data from the clipboard on window’s display.
The window keyword defaults to the root window of the Tkinter application.
The type keyword specifies the form in which the data is to be returned and should be an atom name such as STRING or FILE_NAME. Type defaults to STRING, except on X11, where the default is to try UTF8_STRING and fall back to STRING.
This command is equivalent to:
selection_get(CLIPBOARD)
-
colormapwindows
(*wlist)¶ Store list of window names (WLIST) into WM_COLORMAPWINDOWS property of this widget. This list contains windows whose colormaps differ from their parents. Return current list of widgets if WLIST is empty.
-
columnconfigure
(index, cnf={}, **kw)¶ Configure column INDEX of a grid.
Valid resources are minsize (minimum size of the column), weight (how much does additional space propagate to this column) and pad (how much space to let additionally).
-
command
(value=None)¶ Store VALUE in WM_COMMAND property. It is the command which shall be used to invoke the application. Return current command if VALUE is None.
-
config
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
configure
(cnf=None, **kw)¶ Configure resources of a widget.
The values for resources are specified as keyword arguments. To get an overview about the allowed keyword arguments call the method keys.
-
deiconify
()¶ Deiconify this widget. If it was never mapped it will not be mapped. On Windows it will raise this widget and give it the focus.
-
deletecommand
(name)¶ Internal function.
Delete the Tcl command provided in NAME.
-