osrlib.core.validation
The refusal a validator returns when the rules don't allow an input.
The module has one member,
Rejection. You usually read rejections rather than
build them. Every kernel validator returns a list of them, empty when the input is
legal. When a session refuses a command, the
CommandResult it returns lists them too. Read
their codes to find out what went wrong, and turn them into the message you show the
player.
Each rules area has a validator and a function that applies the change:
validate_adjustment with
apply_adjustment,
validate_purchase with
purchase, and so on. Call the validator, show the
rejections if there are any, and call the apply function only on an empty list. Passing
the apply function a change that its validator refuses is a mistake in your code, not a
player's illegal move, so the apply function raises ValueError instead of returning a
rejection. The exceptions
osrlib raises for other kinds of failure are in osrlib.errors.
Validators run before anything changes. When a validator refuses an input, osrlib draws no random numbers, advances no game time, and changes nothing. You can offer a move, show why the validator refused it, and let the player pick again with the game in the same state.
Typical usage:
from osrlib.core.abilities import AbilityAdjustment, AbilityScore, validate_adjustment
scores = {
AbilityScore.STR: 12,
AbilityScore.INT: 13,
AbilityScore.WIS: 9,
AbilityScore.DEX: 11,
AbilityScore.CON: 14,
AbilityScore.CHA: 10,
}
# Lowering WIS below 9 is against the rules, so the validator refuses it.
adjustment = AbilityAdjustment(lowered={AbilityScore.WIS: 2}, raised={AbilityScore.STR: 1})
rejections = validate_adjustment(scores, adjustment, prime_requisites=(AbilityScore.STR,))
assert [rejection.code for rejection in rejections] == ["creation.adjustment.below_floor"]
assert rejections[0].params == {"ability": "wis", "score": 9, "amount": 2}
Rejection
Bases: BaseModel
One reason a validator refused an input, as a code plus the facts behind it.
A validator returns these. Match on code to decide what to tell the player, and read
params for the numbers and names to put in the sentence. osrlib writes no English
into a rejection, so write your own wording for the codes you expect, and show the
code itself for the rest.
The rejection code reference
lists every code osrlib returns, with what it means.
Build one yourself only when you write your own validator, for a house rule or a custom item, and want it to report a refusal the same way osrlib does.
The model is frozen, so you can keep a rejection around and compare rejections for equality.
Examples:
from osrlib.core.validation import Rejection
rejection = Rejection(code="items.equip.armour_forbidden", params={"class": "magic_user"})
assert rejection.code.split(".")[0] == "items"
assert rejection.params["class"] == "magic_user"
code
instance-attribute
code: str
Which refusal this is, as a dotted message code like items.equip.armour_forbidden.
Match on this value to choose what to show the player. A code is two or more
snake_case segments joined by dots, and the first segment is the subsystem that
refused. Building a rejection with any other format raises a pydantic
ValidationError.
params
class-attribute
instance-attribute
The facts behind the refusal, like the ability that was too low or the class that may not wear the armour.
Values are integers, strings, or tuples of either. Which keys appear depends on the
code, so read the keys of the codes you handle and skip any you don't recognize. A
string is an id or a value name, except where an adventure's author wrote the text,
like a gate's refusal line in the refusal key.