Enhance documentation of register_run_keyword.
This includes mentioning special timeout handling. That fixes
@@ -3591,40 +3591,28 @@ class RobotNotRunningError(AttributeError):
def register_run_keyword(library, keyword, args_to_process=None,
deprecation_warning=True):
- """Registers 'run keyword' so that its arguments can be handled correctly.
+ """Tell Robot Framework that this keyword runs other keywords internally.
- *NOTE:* This API will change in RF 3.1. For more information see
+ *NOTE:* This API will change in the future. For more information see
https://github.com/robotframework/robotframework/issues/2190. Use with
`deprecation_warning=False` to avoid related deprecation warnings.
1) Why is this method needed
- Keywords running other keywords internally (normally using `Run Keyword`
- or some variants of it in BuiltIn) must have the arguments meant to the
- internally executed keyword handled specially to prevent processing them
- twice. This is done ONLY for keywords registered using this method.
-
- If the register keyword has same name as any keyword from Robot Framework
- standard libraries, it can be used without getting warnings. Normally
- there is a warning in such cases unless the keyword is used in long
- format (e.g. MyLib.Keyword).
-
- Keywords executed by registered run keywords can be tested in dry-run mode
- if they have 'name' argument which takes the name of the executed keyword.
+ Keywords running other keywords internally using `Run Keyword` or its variants
+ like `Run Keyword If` need some special handling by the framework. This includes
+ not processing arguments (e.g. variables in them) twice, special handling of
+ timeouts, and so on.
2) How to use this method
- `library` is the name of the library where the registered keyword is
- implemented.
+ `library` is the name of the library where the registered keyword is implemented.
- `keyword` can be either a function or method implementing the
- keyword, or name of the implemented keyword as a string.
+ `keyword` is the name of the keyword. With Python 2 it is possible to pass also
+ the function or method implementing the keyword.
- `args_to_process` is needed when `keyword` is given as a string, and it
- defines how many of the arguments to the registered keyword must be
- processed normally. When `keyword` is a method or function, this
- information is got directly from it so that varargs (those specified with
- syntax '*args') are not processed but others are.
+ `args_to_process`` defines how many of the arguments to the registered keyword must
+ be processed normally.
3) Examples
@@ -3634,8 +3622,6 @@ def register_run_keyword(library, keyword, args_to_process=None,
# do something
return BuiltIn().run_keyword(name, *args)
- # Either one of these works
- register_run_keyword(__name__, my_run_keyword)
register_run_keyword(__name__, 'My Run Keyword', 1)
-------------
@@ -3647,8 +3633,6 @@ def register_run_keyword(library, keyword, args_to_process=None,
# do something
return BuiltIn().run_keyword_if(expression, name, *args)
- # Either one of these works
- register_run_keyword('MyLibrary', MyLibrary.my_run_keyword_if)
register_run_keyword('MyLibrary', 'my_run_keyword_if', 2)
"""
RUN_KW_REGISTER.register_run_keyword(library, keyword, args_to_process,
