okw-contract-utils
Shared utilities for the OKW ecosystem. This package defines cross-library contracts such as matchers (EXACT/WCM/REGX), value expansion ($MEM{KEY}), global OKW tokens, and the YES/NO existence model.
Features
- Match modes: EXACT (equality), WCM (wildcard via fnmatch:
*= any chars,?= one char), REGX (regex viare.search) - Value expansion:
$MEM{KEY}placeholder expansion viaexpand_mem(text, store) - Global tokens:
$IGNORE,$EMPTY,$DELETE - YES/NO existence model:
parse_yes_no(),assert_exists() - Timeout helper:
wait_until(predicate, timeout_s, interval_s) - Exceptions:
OkwAssertionError,OkwTimeoutError,OkwConfigError
Non-goals
- No Robot Framework keywords
- No SSH/Selenium/GUI dependencies
- No environment/provider logic
Match Modes
All match modes normalize newlines (\r\n to \n) before comparing.
| Mode | Function | Description |
|---|---|---|
| EXACT | a == e |
Exact string equality |
| WCM | fnmatch(a, e) |
Wildcard pattern match (* = any chars, ? = one char) |
| REGX | re.search(e, a) |
Regular expression search (multiline) |
Usage:
from okw_contract_utils import assert_match, MatchMode
assert_match("Hello World", "Hello World", MatchMode.EXACT)
assert_match("Hello World", "Hello*", MatchMode.WCM)
assert_match("Hello World", r"Hello\s+\w+", MatchMode.REGX)
Global Token Model
OKW defines a small set of global tokens. Tokens are case-insensitive and evaluated after trimming surrounding whitespace.
Tokens are defined here (contract) and may be implemented selectively by concrete keyword libraries. Not every library must implement every token.
Tokens
-
$IGNORE(control token)- Meaning: the keyword becomes a no-op (PASS).
- Use case: disable single steps inside reusable sequences without control structures.
-
$EMPTY(value-intent token)- Meaning: expected/target value is empty.
- Use case: explicitly verify that a value is empty (e.g. stdout/stderr is empty), even if the
underlying system does not represent emptiness strictly as
"".
-
$DELETE(action-intent token)- Meaning: perform an explicit delete/clear action.
- Typically used in GUI libraries (e.g. clear text fields).
- Libraries that cannot implement delete semantics simply do not support
$DELETE.
Robot Framework variables
Robot variables like ${IGNORE} are expanded by Robot before the keyword is executed.
If ${IGNORE} is not defined, Robot fails before the library can handle it.
Recommended suite variables:
*** Variables ***
${IGNORE} $IGNORE
${EMPTY} $EMPTY
${DELETE} $DELETE
Evaluation order (contract)
For keyword parameters of type Value/Expected/Command:
- Robot Framework variable expansion (e.g. ${IGNORE} -> $IGNORE)
- OKW value expansion (e.g. $MEM{KEY})
- Token parsing ($IGNORE, $EMPTY, $DELETE)
- Keyword semantics / adapter execution
YES/NO Existence Model
For keywords that verify whether a resource exists (files, directories, UI elements, etc.), OKW defines a standard YES/NO model.
Accepted values
| Input | Parsed as |
|---|---|
YES, TRUE, 1 |
YES (must exist) |
NO, FALSE, 0 |
NO (must not exist) |
All values are case-insensitive and trimmed. Invalid values raise ValueError.
Usage
from okw_contract_utils.tokens import parse_yes_no, assert_exists, OkwYesNo
# Parse user input
yn = parse_yes_no("YES") # -> OkwYesNo.YES
yn = parse_yes_no("false") # -> OkwYesNo.NO
yn = parse_yes_no("1") # -> OkwYesNo.YES
# Assert existence
assert_exists(True, OkwYesNo.YES) # PASS
assert_exists(False, OkwYesNo.NO) # PASS
assert_exists(False, OkwYesNo.YES) # raises OkwAssertionError
Robot Framework integration
Keywords typically expose the expected parameter with a default of YES:
Verify Remote File Exists session1 /tmp/data.txt # default: YES
Verify Remote File Exists session1 /tmp/data.txt YES
Verify Remote File Exists session1 /tmp/old.txt NO # must NOT exist
Value Expansion
expand_mem(text, store) replaces $MEM{KEY} placeholders with values from a dictionary.
Missing keys cause an immediate error (no silent fallback).
from okw_contract_utils import expand_mem
store = {"USER": "admin", "HOST": "10.0.0.1"}
result = expand_mem("ssh $MEM{USER}@$MEM{HOST}", store)
# -> "ssh admin@10.0.0.1"
Metadata
Release files for okw-contract-utils 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| okw_contract_utils-0.2.1.tar.gz | 20.6 kB | Without provenance | Details for okw_contract_utils-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| okw_contract_utils-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for okw_contract_utils-0.2.1-py3-none-any.whl |
Total release size: 39.5 kB
Release files / okw_contract_utils-0.2.1.tar.gz
| Download URL | okw_contract_utils-0.2.1.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6803570d6dd36c13c44de19ff92ec41e6e89a254decbb76f23551bc72585ceed
|
|
BLAKE2b-256 checksum How to use checksums |
da34e1dbb3f5759eb7a982e0a356205fb3463f85d82a84c96ac542a77e12ac7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / okw_contract_utils-0.2.1-py3-none-any.whl
| Download URL | okw_contract_utils-0.2.1-py3-none-any.whl |
|---|---|
| Size | 18.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aca63d9bb5efa20115e283572f829e5125ffafec58c82260faa17f5e32724036
|
|
BLAKE2b-256 checksum How to use checksums |
0b7c7928e4f2abf07d759e18d18e7d3f5ea040035413c6605997ccece0d06aa6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for okw-contract-utils 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.