robotframework-plugins 2026.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (199) hide show
  1. robotframework_plugins/__init__.py +14 -0
  2. robotframework_plugins/_assets/catalog.json +143 -0
  3. robotframework_plugins/_assets/plugins/rf-agentskills/.claude-plugin/plugin.json +25 -0
  4. robotframework_plugins/_assets/plugins/rf-agentskills/CHANGELOG.md +198 -0
  5. robotframework_plugins/_assets/plugins/rf-agentskills/README.md +27 -0
  6. robotframework_plugins/_assets/plugins/rf-agentskills/catalog.yaml +25 -0
  7. robotframework_plugins/_assets/plugins/rf-api/.claude-plugin/plugin.json +25 -0
  8. robotframework_plugins/_assets/plugins/rf-api/CHANGELOG.md +9 -0
  9. robotframework_plugins/_assets/plugins/rf-api/README.md +27 -0
  10. robotframework_plugins/_assets/plugins/rf-api/catalog.yaml +27 -0
  11. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/SKILL.md +113 -0
  12. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/authentication-patterns.robot +39 -0
  13. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/basic-crud.robot +46 -0
  14. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/file-upload.robot +28 -0
  15. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/assets/examples/session-handling.robot +48 -0
  16. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/async-jobs.md +42 -0
  17. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/authentication.md +58 -0
  18. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/install.md +10 -0
  19. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/loose-assertions.md +20 -0
  20. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/request-options.md +90 -0
  21. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/response-validation.md +64 -0
  22. robotframework_plugins/_assets/plugins/rf-api/skills/rf-requests/references/troubleshooting.md +64 -0
  23. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/SKILL.md +120 -0
  24. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/basic-rest.robot +51 -0
  25. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schema-validation.robot +38 -0
  26. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/assets/examples/schemas/user.json +10 -0
  27. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/authentication.md +61 -0
  28. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/install.md +11 -0
  29. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/json-handling.md +89 -0
  30. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/loose-assertions.md +18 -0
  31. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/migrate-from-requests.md +15 -0
  32. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/schema-validation.md +85 -0
  33. robotframework_plugins/_assets/plugins/rf-api/skills/rf-restinstance/references/troubleshooting.md +68 -0
  34. robotframework_plugins/_assets/plugins/rf-core/.claude-plugin/plugin.json +19 -0
  35. robotframework_plugins/_assets/plugins/rf-core/CHANGELOG.md +13 -0
  36. robotframework_plugins/_assets/plugins/rf-core/README.md +38 -0
  37. robotframework_plugins/_assets/plugins/rf-core/agents/rf-debug-expert.md +120 -0
  38. robotframework_plugins/_assets/plugins/rf-core/agents/rf-migration-guide.md +73 -0
  39. robotframework_plugins/_assets/plugins/rf-core/agents/rf-test-architect.md +98 -0
  40. robotframework_plugins/_assets/plugins/rf-core/catalog.yaml +19 -0
  41. robotframework_plugins/_assets/plugins/rf-core/hooks/README.md +445 -0
  42. robotframework_plugins/_assets/plugins/rf-core/hooks/hooks.json +70 -0
  43. robotframework_plugins/_assets/plugins/rf-core/scripts/_hook_input.mjs +101 -0
  44. robotframework_plugins/_assets/plugins/rf-core/scripts/_pending_errors.mjs +65 -0
  45. robotframework_plugins/_assets/plugins/rf-core/scripts/_python_env.mjs +181 -0
  46. robotframework_plugins/_assets/plugins/rf-core/scripts/check_rf_environment.mjs +181 -0
  47. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_inject_rf_context.mjs +74 -0
  48. robotframework_plugins/_assets/plugins/rf-core/scripts/maybe_remind_robot_tests.mjs +128 -0
  49. robotframework_plugins/_assets/plugins/rf-core/scripts/report_pending_errors.mjs +72 -0
  50. robotframework_plugins/_assets/plugins/rf-core/scripts/rf_error_hints.mjs +126 -0
  51. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot.mjs +517 -0
  52. robotframework_plugins/_assets/plugins/rf-core/scripts/validate_robot_project.mjs +103 -0
  53. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/SKILL.md +313 -0
  54. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/api.resource +30 -0
  55. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/calc.resource +23 -0
  56. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/embedded.resource +20 -0
  57. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/keywords.resource +26 -0
  58. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/resources/login.resource +10 -0
  59. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/01__keyword_driven.robot +15 -0
  60. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/02__data_driven.robot +10 -0
  61. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/03__templates.robot +17 -0
  62. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/04__bdd.robot +10 -0
  63. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/05__embedded.robot +13 -0
  64. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/__init__.robot +6 -0
  65. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/__init__.robot +7 -0
  66. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/api/users.robot +18 -0
  67. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/tests/env.robot +15 -0
  68. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/common.py +11 -0
  69. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/dev.yaml +3 -0
  70. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/assets/examples/variables/staging.yaml +3 -0
  71. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/arguments.md +139 -0
  72. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/control-structures.md +175 -0
  73. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/embedded-arguments.md +135 -0
  74. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/migration.md +90 -0
  75. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/resources-and-variable-files.md +127 -0
  76. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/styles.md +92 -0
  77. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/suites-and-init.md +96 -0
  78. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/tags-and-selection.md +104 -0
  79. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/templates.md +124 -0
  80. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/references/variables-and-scopes.md +129 -0
  81. robotframework_plugins/_assets/plugins/rf-core/skills/rf-language/scripts/rf_conventions.py +883 -0
  82. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/SKILL.md +216 -0
  83. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ExampleLibrary.py +61 -0
  84. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/ResultListener.py +60 -0
  85. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.py +48 -0
  86. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/converters.robot +20 -0
  87. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/example_library.robot +31 -0
  88. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/assets/examples/listener.robot +12 -0
  89. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/api-variants.md +291 -0
  90. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/communication.md +248 -0
  91. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/conversion.md +347 -0
  92. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/listeners.md +150 -0
  93. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/references/packaging-and-docs.md +155 -0
  94. robotframework_plugins/_assets/plugins/rf-core/skills/rf-python-library/scripts/check_library.py +842 -0
  95. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/SKILL.md +159 -0
  96. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/github-actions-robot.yml +32 -0
  97. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/gitignore.txt +22 -0
  98. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.poetry.toml +28 -0
  99. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/pyproject.uv.toml +20 -0
  100. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/requirements.txt +9 -0
  101. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/robot.toml +16 -0
  102. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/assets/examples/smoke.robot +22 -0
  103. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/ci.md +61 -0
  104. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/cli-tools.md +33 -0
  105. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/libraries.md +47 -0
  106. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/poetry.md +77 -0
  107. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/project-layout.md +86 -0
  108. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/troubleshooting.md +73 -0
  109. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/uv.md +108 -0
  110. robotframework_plugins/_assets/plugins/rf-core/skills/rf-setup/references/venv-pip.md +71 -0
  111. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-debug-expert.toml +119 -0
  112. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-migration-guide.toml +72 -0
  113. robotframework_plugins/_assets/plugins/rf-core/variants/codex/agents/rf-test-architect.toml +97 -0
  114. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-debug-expert.md +123 -0
  115. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-migration-guide.md +76 -0
  116. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/agents/rf-test-architect.md +101 -0
  117. robotframework_plugins/_assets/plugins/rf-core/variants/opencode/plugins/rf-core.js +93 -0
  118. robotframework_plugins/_assets/plugins/rf-desktop/.claude-plugin/plugin.json +24 -0
  119. robotframework_plugins/_assets/plugins/rf-desktop/CHANGELOG.md +10 -0
  120. robotframework_plugins/_assets/plugins/rf-desktop/README.md +26 -0
  121. robotframework_plugins/_assets/plugins/rf-desktop/catalog.yaml +23 -0
  122. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/SKILL.md +268 -0
  123. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/calculator.robot +45 -0
  124. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/assets/examples/mock-deterministic.robot +33 -0
  125. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/cli-and-inspector.md +82 -0
  126. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/install.md +14 -0
  127. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/keywords-reference.md +102 -0
  128. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/locators-and-queries.md +95 -0
  129. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/platform-setup.md +65 -0
  130. robotframework_plugins/_assets/plugins/rf-desktop/skills/rf-platynui/references/status-and-migration.md +41 -0
  131. robotframework_plugins/_assets/plugins/rf-mobile/.claude-plugin/plugin.json +24 -0
  132. robotframework_plugins/_assets/plugins/rf-mobile/CHANGELOG.md +9 -0
  133. robotframework_plugins/_assets/plugins/rf-mobile/README.md +26 -0
  134. robotframework_plugins/_assets/plugins/rf-mobile/catalog.yaml +23 -0
  135. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/SKILL.md +134 -0
  136. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/android-basic.robot +60 -0
  137. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/gestures-example.robot +59 -0
  138. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/hybrid-app.robot +54 -0
  139. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/assets/examples/ios-basic.robot +48 -0
  140. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/capabilities.md +117 -0
  141. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/gestures-touch.md +84 -0
  142. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/install.md +21 -0
  143. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/locators-mobile.md +74 -0
  144. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/platform-specific.md +105 -0
  145. robotframework_plugins/_assets/plugins/rf-mobile/skills/rf-appium/references/troubleshooting.md +70 -0
  146. robotframework_plugins/_assets/plugins/rf-web/.claude-plugin/plugin.json +25 -0
  147. robotframework_plugins/_assets/plugins/rf-web/CHANGELOG.md +9 -0
  148. robotframework_plugins/_assets/plugins/rf-web/README.md +27 -0
  149. robotframework_plugins/_assets/plugins/rf-web/catalog.yaml +27 -0
  150. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/SKILL.md +134 -0
  151. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/authentication-flow.robot +34 -0
  152. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/basic-web-test.robot +29 -0
  153. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/form-handling.robot +49 -0
  154. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/assets/examples/iframe-shadow-dom.robot +31 -0
  155. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/assertion-engine.md +79 -0
  156. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/authentication-storage.md +86 -0
  157. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/browser-context-page.md +110 -0
  158. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/downloads-uploads.md +51 -0
  159. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/iframes-shadow-dom.md +67 -0
  160. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/install.md +67 -0
  161. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/locators.md +83 -0
  162. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/migrate-from-selenium.md +22 -0
  163. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/selector-drift.md +29 -0
  164. robotframework_plugins/_assets/plugins/rf-web/skills/rf-browser/references/troubleshooting.md +100 -0
  165. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/SKILL.md +123 -0
  166. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/basic-web-test.robot +64 -0
  167. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/multi-window.robot +55 -0
  168. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/assets/examples/wait-patterns.robot +53 -0
  169. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/browser-setup.md +103 -0
  170. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/frames-windows.md +84 -0
  171. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/install.md +12 -0
  172. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/javascript-execution.md +65 -0
  173. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/locators.md +86 -0
  174. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/troubleshooting.md +122 -0
  175. robotframework_plugins/_assets/plugins/rf-web/skills/rf-selenium/references/waiting-strategies.md +84 -0
  176. robotframework_plugins/_assets.py +120 -0
  177. robotframework_plugins/_catalog.py +123 -0
  178. robotframework_plugins/_snapshot.py +320 -0
  179. robotframework_plugins/adapters/__init__.py +53 -0
  180. robotframework_plugins/adapters/_base.py +400 -0
  181. robotframework_plugins/adapters/claude_code.py +312 -0
  182. robotframework_plugins/adapters/claude_desktop.py +129 -0
  183. robotframework_plugins/adapters/codex.py +276 -0
  184. robotframework_plugins/adapters/copilot.py +87 -0
  185. robotframework_plugins/adapters/cursor.py +295 -0
  186. robotframework_plugins/adapters/goose.py +240 -0
  187. robotframework_plugins/adapters/opencode.py +170 -0
  188. robotframework_plugins/bundle.py +85 -0
  189. robotframework_plugins/cli.py +1311 -0
  190. robotframework_plugins/detect.py +121 -0
  191. robotframework_plugins/manifest.py +338 -0
  192. robotframework_plugins/py.typed +0 -0
  193. robotframework_plugins/skillzip.py +39 -0
  194. robotframework_plugins/transforms.py +725 -0
  195. robotframework_plugins-2026.11.0.dist-info/METADATA +198 -0
  196. robotframework_plugins-2026.11.0.dist-info/RECORD +199 -0
  197. robotframework_plugins-2026.11.0.dist-info/WHEEL +4 -0
  198. robotframework_plugins-2026.11.0.dist-info/entry_points.txt +2 -0
  199. robotframework_plugins-2026.11.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,347 @@
1
+ # Argument conversion from type hints
2
+
3
+ Robot Framework passes every argument from `.robot` data as a string unless it
4
+ is a variable holding another object. A type hint on the Python argument makes
5
+ RF convert the string before the keyword runs and documents the type in libdoc.
6
+ Examples need RF 7.0+ unless a block says otherwise.
7
+
8
+ - [Built-in types](#built-in-types)
9
+ - [Enum and Literal](#enum-and-literal)
10
+ - [Containers and TypedDict](#containers-and-typeddict)
11
+ - [None, unions and their order](#none-unions-and-their-order)
12
+ - [Implicit typing and bool](#implicit-typing-and-bool)
13
+ - [Secret and object (RF 7.4)](#secret-and-object-rf-74)
14
+ - [Custom converters](#custom-converters)
15
+ - [Types without annotations: `types=`](#types-without-annotations-types)
16
+
17
+ ## Built-in types
18
+
19
+ | Hint | Accepts (strings) | Notes |
20
+ |---|---|---|
21
+ | `int` | `42`, `-1`, `0x2A`, `1 000` | spaces and underscores allowed |
22
+ | `float` / `Decimal` | `3.14`, `1e3` | use `Decimal` for money |
23
+ | `bool` | `True`/`yes`/`on`/`1`, `False`/`no`/`off`/`0`/`none`/empty | other strings pass through unchanged |
24
+ | `str` | anything | no conversion |
25
+ | `bytes` | `abc` (Latin-1) | |
26
+ | `datetime` / `date` | `2026-09-28 12:00:00`, epoch seconds | |
27
+ | `timedelta` | `1 minute 30 s`, `90`, `1:30` | RF time format |
28
+ | `Path` | `results/out.json` | |
29
+ | `None` | `None` (case-insensitive) | usually inside a union |
30
+
31
+ ```python
32
+ # file: Types.py
33
+ """Built-in conversions."""
34
+
35
+ from datetime import timedelta
36
+ from decimal import Decimal
37
+ from pathlib import Path
38
+
39
+ from robot.api.deco import keyword, library
40
+
41
+
42
+ @library(scope="GLOBAL")
43
+ class Types:
44
+ """Show converted values."""
45
+
46
+ @keyword
47
+ def describe(self, count: int, price: Decimal, wait: timedelta, target: Path, enabled: bool) -> str:
48
+ """Return the converted values as one string."""
49
+ return f"{count + 1}|{price * 2}|{wait.total_seconds()}|{target.name}|{enabled}"
50
+ ```
51
+
52
+ ```robotframework
53
+ # file: types.robot
54
+ *** Settings ***
55
+ Library Types
56
+
57
+
58
+ *** Test Cases ***
59
+ Strings Become Typed Values
60
+ ${text}= Describe 41 1.25 1 minute 30 s results/out.json yes
61
+ Should Be Equal ${text} 42|2.50|90.0|out.json|True
62
+
63
+ Bad Integer Fails Before The Keyword Runs
64
+ Run Keyword And Expect Error *cannot be converted to integer*
65
+ ... Describe many 1 1s x no
66
+ ```
67
+
68
+ ## Enum and Literal
69
+
70
+ Both restrict an argument to fixed values and match case-insensitively
71
+ (`on` → `ON`). `Literal` (RF 7.0) keeps the plain value; an `Enum` gives the
72
+ member and documents the allowed values once for several keywords. A wrong
73
+ value fails and names the allowed values (`Literal`: "… cannot be converted
74
+ to 'ON' or 'OFF'"; `Enum`: "… Available: 'FAST' and 'SLOW'").
75
+
76
+ ```python
77
+ # file: Modes.py
78
+ """Enum and Literal arguments."""
79
+
80
+ from enum import Enum
81
+ from typing import Literal
82
+
83
+ from robot.api.deco import keyword, library
84
+
85
+
86
+ class Speed(Enum):
87
+ SLOW = 1
88
+ FAST = 2
89
+
90
+
91
+ @library(scope="GLOBAL")
92
+ class Modes:
93
+ """Fixed-value arguments."""
94
+
95
+ @keyword
96
+ def set_power(self, state: Literal["ON", "OFF"]) -> str:
97
+ """Return the normalised power state."""
98
+ return state
99
+
100
+ @keyword
101
+ def set_speed(self, speed: Speed) -> int:
102
+ """Return the numeric value of the speed."""
103
+ return speed.value
104
+ ```
105
+
106
+ ```robotframework
107
+ # file: modes.robot
108
+ *** Settings ***
109
+ Library Modes
110
+
111
+
112
+ *** Test Cases ***
113
+ Values Match Case-Insensitively
114
+ ${state}= Set Power on
115
+ Should Be Equal ${state} ON
116
+ ${speed}= Set Speed fast
117
+ Should Be Equal ${speed} ${2}
118
+
119
+ Unknown Value Lists The Allowed Ones
120
+ Run Keyword And Expect Error *'ON' or 'OFF'* Set Power maybe
121
+ Run Keyword And Expect Error *Available: 'FAST' and 'SLOW'* Set Speed medium
122
+ ```
123
+
124
+ ## Containers and TypedDict
125
+
126
+ `list[int]`, `dict[str, int]`, `tuple[int, ...]` and `set[str]` convert
127
+ Python-literal strings (`[1, 2]`) and also convert the items of a list or
128
+ dictionary variable. `TypedDict` checks the keys and converts each value;
129
+ missing required keys fail.
130
+
131
+ ```python
132
+ # file: Orders.py
133
+ """Parametrised containers and TypedDict."""
134
+
135
+ from typing import TypedDict
136
+
137
+ from robot.api.deco import keyword, library
138
+
139
+
140
+ class Item(TypedDict):
141
+ name: str
142
+ qty: int
143
+
144
+
145
+ @library(scope="GLOBAL")
146
+ class Orders:
147
+ """Container arguments."""
148
+
149
+ @keyword
150
+ def total_quantity(self, quantities: list[int]) -> int:
151
+ """Sum the quantities."""
152
+ return sum(quantities)
153
+
154
+ @keyword
155
+ def item_label(self, item: Item) -> str:
156
+ """Return ``<qty> x <name>``."""
157
+ return f"{item['qty']} x {item['name']}"
158
+ ```
159
+
160
+ ```robotframework
161
+ # file: orders.robot
162
+ *** Settings ***
163
+ Library Orders
164
+
165
+
166
+ *** Test Cases ***
167
+ Literal String And List Variable Are Converted
168
+ ${total}= Total Quantity [1, 2, 3]
169
+ Should Be Equal ${total} ${6}
170
+ VAR @{strings} 4 5
171
+ ${total}= Total Quantity ${strings}
172
+ Should Be Equal ${total} ${9}
173
+
174
+ TypedDict Converts Values
175
+ ${label}= Item Label {'name': 'apple', 'qty': '3'}
176
+ Should Be Equal ${label} 3 x apple
177
+ ```
178
+
179
+ ## None, unions and their order
180
+
181
+ `int | None = None` accepts `None` or an integer. RF tries the union members
182
+ from left to right and stops at the first that works; if the argument already
183
+ has one of the member types, it is passed unchanged. So a union with `str`
184
+ never converts a string: every argument from `.robot` data already is one.
185
+ The checker reports this as `union_with_str`.
186
+
187
+ ```python
188
+ # file: Unions.py
189
+ # Wrong: union_with_str
190
+ """A union with str never converts strings."""
191
+
192
+ from robot.api.deco import keyword, library
193
+
194
+
195
+ @library(scope="GLOBAL")
196
+ class Unions:
197
+ """Union order."""
198
+
199
+ @keyword
200
+ def add_one(self, value: int | str) -> str:
201
+ """Returns the type name: ``10`` stays a string."""
202
+ return type(value).__name__
203
+ ```
204
+
205
+ Put the converting types only (`int | float`), order them from the most to the
206
+ least specific, and keep `str | None` for "text or nothing" (the checker does
207
+ not flag it).
208
+
209
+ ## Implicit typing and bool
210
+
211
+ Without a hint, a default value implies the type, but leniently: `def kw(n=3)`
212
+ converts `5` to `5` and passes `abc` through as the string `abc`. `bool`
213
+ conversion also passes unknown strings through (`maybe` stays `maybe`). Neither
214
+ is detected by the checker. Use real hints, and `Literal`/`Enum` when only a
215
+ few values are valid.
216
+
217
+ ## Secret and object (RF 7.4)
218
+
219
+ `Secret` (`from robot.api.types import Secret`) marks an argument that only
220
+ accepts `Secret` objects, so the value does not appear in logs. A plain string
221
+ fails ("… must have type 'Secret', got string"). The data creates one from an
222
+ environment variable in the Variables section; read `.value` in the keyword.
223
+
224
+ ```python
225
+ # file: Vault.py
226
+ # RF 7.4+
227
+ """Secret arguments."""
228
+
229
+ from robot.api.deco import keyword, library
230
+ from robot.api.types import Secret
231
+
232
+
233
+ @library(scope="GLOBAL")
234
+ class Vault:
235
+ """Uses a secret without logging it."""
236
+
237
+ @keyword
238
+ def password_length(self, password: Secret) -> int:
239
+ """Return the length of the secret value."""
240
+ return len(password.value)
241
+ ```
242
+
243
+ ```robotframework
244
+ # file: vault.robot
245
+ # RF 7.4+
246
+ *** Settings ***
247
+ Library Vault
248
+
249
+
250
+ *** Variables ***
251
+ ${PASSWORD: Secret} %{APP_PASSWORD=s3cret}
252
+
253
+
254
+ *** Test Cases ***
255
+ Secret From Environment
256
+ ${length}= Password Length ${PASSWORD}
257
+ Should Be True ${length} > 0
258
+
259
+ Plain String Is Rejected
260
+ Run Keyword And Expect Error *must have type 'Secret'* Password Length s3cret
261
+ ```
262
+
263
+ `object` as a hint (RF 7.4) states "any value, no conversion" explicitly.
264
+
265
+ ## Custom converters
266
+
267
+ For a domain type, register a converter function on the library. RF calls it
268
+ only when the argument is not already of that type; it must raise `ValueError`
269
+ on bad input, and RF turns that into a failure naming the argument. Register it
270
+ with `@library(converters={Type: function})` or, in a module library,
271
+ `ROBOT_LIBRARY_CONVERTERS = {Type: function}`.
272
+
273
+ ```python
274
+ # file: Shop.py
275
+ """Custom converter registered with @library(converters=...)."""
276
+
277
+ from dataclasses import dataclass
278
+
279
+ from robot.api.deco import keyword, library
280
+
281
+
282
+ @dataclass(frozen=True)
283
+ class Sku:
284
+ """A stock-keeping unit such as ``AB-1234``."""
285
+
286
+ prefix: str
287
+ number: int
288
+
289
+
290
+ def parse_sku(value: str) -> Sku:
291
+ """Convert ``AB-1234``; raise ValueError on anything else."""
292
+ prefix, _, number = value.partition("-")
293
+ if len(prefix) != 2 or not prefix.isalpha() or not number.isdigit():
294
+ raise ValueError(f"expected an SKU like 'AB-1234', got '{value}'")
295
+ return Sku(prefix.upper(), int(number))
296
+
297
+
298
+ @library(scope="GLOBAL", converters={Sku: parse_sku})
299
+ class Shop:
300
+ """Keywords that take SKUs."""
301
+
302
+ @keyword
303
+ def sku_number(self, sku: Sku) -> int:
304
+ """Return the numeric part of ``sku``."""
305
+ return sku.number
306
+ ```
307
+
308
+ ```robotframework
309
+ # file: shop.robot
310
+ *** Settings ***
311
+ Library Shop
312
+
313
+
314
+ *** Test Cases ***
315
+ String Becomes Sku
316
+ ${number}= Sku Number ab-1234
317
+ Should Be Equal ${number} ${1234}
318
+
319
+ Converter Error Names The Argument
320
+ Run Keyword And Expect Error *'sku'*expected an SKU like 'AB-1234'* Sku Number 1234
321
+ ```
322
+
323
+ `assets/examples/converters.py` shows the module-library form
324
+ (`ROBOT_LIBRARY_CONVERTERS`) with a `Money` type.
325
+
326
+ ## Types without annotations: `types=`
327
+
328
+ `@keyword(types={"count": int})` (or a list in argument order) sets types when
329
+ annotations are not possible, for example on generated functions. Annotations
330
+ are preferred.
331
+
332
+ ```python
333
+ # file: Legacy.py
334
+ """Types given through the keyword decorator."""
335
+
336
+ from robot.api.deco import keyword, library
337
+
338
+
339
+ @library(scope="GLOBAL")
340
+ class Legacy:
341
+ """Old-style keyword."""
342
+
343
+ @keyword(types={"count": int})
344
+ def repeat_word(self, word, count):
345
+ """Repeat ``word`` ``count`` times."""
346
+ return word * count
347
+ ```
@@ -0,0 +1,150 @@
1
+ # Listeners
2
+
3
+ A listener is a Python class or module whose methods Robot Framework calls
4
+ while a run progresses. Listener API version 3 (the default from RF 7.0)
5
+ passes the running data and result model objects, so a listener can read and
6
+ change them. Examples need RF 7.0+ unless a block says otherwise.
7
+
8
+ - [Listener API v3 methods](#listener-api-v3-methods)
9
+ - [Registering a listener](#registering-a-listener)
10
+ - [A library that is also a listener](#a-library-that-is-also-a-listener)
11
+ - [Priority](#priority)
12
+ - [Changing results](#changing-results)
13
+ - [Rules of thumb](#rules-of-thumb)
14
+
15
+ ## Listener API v3 methods
16
+
17
+ | Method | Called |
18
+ |---|---|
19
+ | `start_suite(data, result)` / `end_suite(data, result)` | around each suite; `start_suite` may modify `data` (add or filter tests) |
20
+ | `start_test(data, result)` / `end_test(data, result)` | around each test; `end_test` may change `result.status` and `result.message` |
21
+ | `start_keyword(data, result)` / `end_keyword(data, result)` | around every keyword and control structure (RF 7.0+; also `start_library_keyword`, `start_user_keyword`, `start_for`, …) |
22
+ | `log_message(message)` / `message(message)` | a log message / a system message |
23
+ | `library_import`, `resource_import`, `variables_import` | after an import |
24
+ | `output_file(path)`, `log_file`, `report_file`, `xunit_file`, `debug_file` | when an output file is written |
25
+ | `close()` | once at the end (for a library listener: when the library goes out of scope) |
26
+
27
+ Every method is optional; implement only the ones you need. Version 2
28
+ listeners (name and attribute-dict arguments) still work with
29
+ `ROBOT_LISTENER_API_VERSION = 2`, but new code uses version 3.
30
+
31
+ ## Registering a listener
32
+
33
+ On the command line, by module or class name on the python-path (or a file
34
+ path). Arguments follow after colons and reach `__init__` as strings:
35
+
36
+ ```bash
37
+ uv run robot --pythonpath libraries --listener ResultListener tests/
38
+ uv run robot --pythonpath libraries --listener ResultListener:summary.json tests/
39
+ ```
40
+
41
+ In `robot.toml` the same goes into `listeners = ["ResultListener:summary.json"]`.
42
+ `assets/examples/ResultListener.py` is a complete listener that writes a JSON
43
+ summary into the output directory at `close`.
44
+
45
+ ## A library that is also a listener
46
+
47
+ `@library(listener="SELF")` (or `ROBOT_LIBRARY_LISTENER = self` in `__init__`)
48
+ makes the library instance a listener for the suites that import it. With
49
+ `@library`, listener methods such as `end_test` do not become keywords, and
50
+ the checker does not flag them. Without `@library` they are keywords (checker:
51
+ `listener_method_exposed`).
52
+
53
+ ```python
54
+ # file: Timing.py
55
+ """Library listener: records test durations of the importing suite."""
56
+
57
+ from robot.api.deco import keyword, library
58
+
59
+
60
+ @library(scope="SUITE", listener="SELF")
61
+ class Timing:
62
+ """Collects the duration of each finished test."""
63
+
64
+ def __init__(self) -> None:
65
+ self._durations: dict[str, float] = {}
66
+
67
+ def end_test(self, data, result) -> None:
68
+ self._durations[result.name] = result.elapsed_time.total_seconds()
69
+
70
+ @keyword
71
+ def finished_test_count(self) -> int:
72
+ """Number of tests of this suite that have finished so far."""
73
+ return len(self._durations)
74
+ ```
75
+
76
+ ```robotframework
77
+ # file: timing.robot
78
+ *** Settings ***
79
+ Library Timing
80
+
81
+
82
+ *** Test Cases ***
83
+ First
84
+ No Operation
85
+
86
+ Second Sees The First As Finished
87
+ ${count}= Finished Test Count
88
+ Should Be Equal ${count} ${1}
89
+ ```
90
+
91
+ ## Priority
92
+
93
+ With several listeners, `ROBOT_LISTENER_PRIORITY = <number>` (RF 7.1+) orders
94
+ them: higher numbers are called first for every event. Without it, listeners
95
+ run in the order they were registered.
96
+
97
+ ## Changing results
98
+
99
+ In `end_test`, set `result.status` to `"PASS"`, `"FAIL"` or `"SKIP"` and
100
+ adjust `result.message`; the change reaches `output.xml`, the log, the report
101
+ and the exit code (skipped tests do not fail the run). Keep such rules narrow
102
+ and explicit, for example driven by a tag, and say in the message why the
103
+ status changed.
104
+
105
+ ```python
106
+ # file: KnownIssues.py
107
+ # check: skip (a listener, not a library)
108
+ """Listener: failing tests tagged known-issue are reported as SKIP."""
109
+
110
+
111
+ class KnownIssues:
112
+ """Turns failures of tests tagged ``known-issue`` into skips."""
113
+
114
+ ROBOT_LISTENER_API_VERSION = 3
115
+
116
+ def __init__(self, tag: str = "known-issue") -> None:
117
+ self._tag = tag
118
+
119
+ def end_test(self, data, result) -> None:
120
+ if result.failed and self._tag in result.tags:
121
+ result.message = f"Skipped by KnownIssues ({self._tag}): {result.message}"
122
+ result.status = "SKIP"
123
+ ```
124
+
125
+ ```robotframework
126
+ # file: known_issues.robot
127
+ # run: --listener KnownIssues
128
+ *** Test Cases ***
129
+ Tracked Bug
130
+ [Tags] known-issue
131
+ Fail Ticket 123 is not fixed yet
132
+
133
+ Healthy Feature
134
+ Should Be Equal ${{ 2 * 2 }} ${4}
135
+ ```
136
+
137
+ With the listener the run exits 0 (1 passed, 1 skipped); without it, 1.
138
+ `KnownIssues` is a listener, not a library: its listener methods would be
139
+ keywords if it were imported with `Library`.
140
+
141
+ ## Rules of thumb
142
+
143
+ - Keep listener methods fast; they run for every test or keyword.
144
+ - Do not raise from a listener: RF reports the error and continues, but the
145
+ change you wanted is lost.
146
+ - Use `robot.api.logger` from listener methods only in the main thread.
147
+ - `start_keyword` / `end_keyword` fire for every keyword, including BuiltIn
148
+ ones; filter on `data.name` or `data.owner` early.
149
+ - A listener that posts to chat or a webhook reads the URL and token from
150
+ environment variables, never from the repository.
@@ -0,0 +1,155 @@
1
+ # Documentation, packaging and tests
2
+
3
+ How libdoc reads a library, how to document and version it, how to ship it as
4
+ a package, and how to test it. Examples need RF 7.0+ unless a block says
5
+ otherwise.
6
+
7
+ - [libdoc output](#libdoc-output)
8
+ - [Writing docstrings](#writing-docstrings)
9
+ - [Doc formats](#doc-formats)
10
+ - [Versioning](#versioning)
11
+ - [Package layout](#package-layout)
12
+ - [Dependencies](#dependencies)
13
+ - [Testing a library](#testing-a-library)
14
+
15
+ ## libdoc output
16
+
17
+ libdoc imports the library (running its import and `__init__` code, like the
18
+ checker) and writes its documentation:
19
+
20
+ ```bash
21
+ uv run libdoc libraries/Inventory.py docs/Inventory.html
22
+ uv run libdoc libraries/Inventory.py docs/Inventory.json
23
+ uv run libdoc --pythonpath libraries Inventory list
24
+ uv run libdoc --pythonpath libraries Inventory show "Add Item"
25
+ ```
26
+
27
+ The output format follows the file extension (`.html`, `.xml`, `.json`,
28
+ `.libspec`); `list` and `show` print to the console. With robotcode installed,
29
+ `robotcode doc keywords libraries/Inventory.py` and `robotcode doc keyword
30
+ libraries/Inventory.py "Add Item"` print the same data as Markdown, using the
31
+ project's `robot.toml`. Commit generated HTML only when the project publishes
32
+ it; editors and language servers read the library directly.
33
+
34
+ ## Writing docstrings
35
+
36
+ - The class (or module) docstring is the library introduction; the
37
+ `__init__` docstring documents the import arguments.
38
+ - A keyword's first docstring line is its short doc in listings; keep it one
39
+ sentence that starts with a verb.
40
+ - Google-style `Args:` sections are fine; libdoc shows the types from the
41
+ hints, so do not repeat them in prose.
42
+ - In the default `ROBOT` format, `` `Other Keyword` `` links to a keyword,
43
+ ``` ``code`` ``` is inline code, `*bold*` and `_italic_` work, and a table
44
+ row such as `| Add Item | apple | 3 |` shows an example call.
45
+ - A library without a docstring gets the placeholder "Documentation for
46
+ library ``Name``." (checker: `library_doc_missing`); a keyword without one
47
+ has an empty doc (checker: `missing_doc`).
48
+
49
+ ## Doc formats
50
+
51
+ | Format | Set with | Notes |
52
+ |---|---|---|
53
+ | `ROBOT` (default) | nothing | RF's own light markup |
54
+ | `HTML` | `ROBOT_LIBRARY_DOC_FORMAT = "HTML"` or `@library(doc_format="HTML")` | raw HTML |
55
+ | `TEXT` | `"TEXT"` | no formatting |
56
+ | `REST` | `"REST"` | needs the `docutils` package |
57
+ | `MARKDOWN` | `"MARKDOWN"` | RF 7.5+; needs the `markdown` package (RF 7.4 rejects it as an invalid format) |
58
+
59
+ Keep one format per library.
60
+
61
+ ## Versioning
62
+
63
+ `@library(version="1.2.0")` or `ROBOT_LIBRARY_VERSION = "1.2.0"` shows the
64
+ version in libdoc, in the log's import message and in the checker output. For
65
+ a packaged library, read it from the package metadata so there is one source:
66
+
67
+ ```python
68
+ # file: Versioned.py
69
+ """Library version from one place."""
70
+
71
+ from robot.api.deco import keyword, library
72
+
73
+ __version__ = "1.2.0"
74
+
75
+
76
+ @library(scope="GLOBAL", version=__version__)
77
+ class Versioned:
78
+ """A library that reports its version."""
79
+
80
+ @keyword
81
+ def library_version(self) -> str:
82
+ """Return the library version."""
83
+ return __version__
84
+ ```
85
+
86
+ ## Package layout
87
+
88
+ A project library is one file in `libraries/`. A library shared between
89
+ projects becomes a package:
90
+
91
+ ```
92
+ mylibrary/
93
+ ├── pyproject.toml # name, version, dependencies = ["robotframework>=7"]
94
+ ├── src/mylibrary/
95
+ │ ├── __init__.py # the library class, named like the package: class mylibrary
96
+ │ │ # or, RF 7.2+, one @library class with any name
97
+ │ ├── keywords/… # components (plain classes, or PythonLibCore components)
98
+ │ └── resources/common.resource
99
+ └── tests/
100
+ ├── unit/ # pytest
101
+ └── acceptance/ # .robot suites that import the library by name
102
+ ```
103
+
104
+ - Import it as `Library mylibrary` once installed; `Library mylibrary.Client`
105
+ selects a class inside it.
106
+ - Ship `.resource` files as package data (setuptools `package-data`, or
107
+ hatch's default include) and import them through the python-path:
108
+ `Resource mylibrary/resources/common.resource`.
109
+ - Keep the package importable without side effects: libdoc, the checker,
110
+ editors and `--dryrun` all import it.
111
+
112
+ ## Dependencies
113
+
114
+ Declare runtime dependencies in the package's `pyproject.toml`, and add them
115
+ to a project with its tool (`uv add <package>`; Poetry or pip in a venv
116
+ otherwise; see rf-setup). An import error at load time shows up as the
117
+ checker's `import_failed` finding with the `ModuleNotFoundError` text.
118
+
119
+ ## Testing a library
120
+
121
+ 1. The checker: `uv run python scripts/check_library.py libraries/*.py` (the
122
+ script path is relative to the rf-python-library skill directory, the
123
+ library paths to the project root) finds RF-specific defects without
124
+ running tests.
125
+ 2. pytest for logic that does not need RF: instantiate the class and call the
126
+ methods. Raising `AssertionError` is testable with `pytest.raises`.
127
+ 3. Acceptance suites in `.robot` files exercise the library the way users
128
+ call it, including conversion errors (`Run Keyword And Expect Error`).
129
+ 4. In CI, run the suites with `--pythonpath libraries` (or the `robot.toml`
130
+ python-path) and the checker on every library.
131
+
132
+ ```python
133
+ # file: test_inventory_logic.py
134
+ # check: skip (a pytest module, not a library)
135
+ """pytest for library logic without Robot Framework running."""
136
+
137
+ import pytest
138
+
139
+ from ExampleLibrary import ExampleLibrary
140
+
141
+
142
+ def test_add_item_counts() -> None:
143
+ lib = ExampleLibrary()
144
+ assert lib.add_item("apple", 2) == 2
145
+ assert lib.add_item("apple", 3) == 5
146
+
147
+
148
+ def test_count_mismatch_fails() -> None:
149
+ lib = ExampleLibrary()
150
+ with pytest.raises(AssertionError, match="expected 1"):
151
+ lib.item_count_should_be("apple", 1)
152
+ ```
153
+
154
+ The pytest example uses `assets/examples/ExampleLibrary.py`; run it with that
155
+ directory on `PYTHONPATH`.