clarifiy / rename readonly-rule

[funkyfuture]

i think the readonly-rule isn't named intuitively. it could mean a lot and my guess is it was named for a certain use-case (propably validating before writing something). but it doesn't explain itself immediately and unambiguously. i had to read the code to fully get its purpose which turned out more trivial and explanatory to me than the docs.

i propose to rename it to is_exluded. excluded may be semantically enough, but it would be just one keystroke away from excludes. another proposal is blacklisted or to stick with an already used term: allowed.

the transition should be implemented like from key- to valueschema.

a usage-example should be added to the documentation.

or is this an artifact from the time before allow_unknown was available?

[funkyfuture]

oh, allowed was a stupid idea.

on a second thought, it isn't. like allow_unknown it could be defined either by a bool or more specific with a list of allowed values (as it is now).

[funkyfuture]

i pledge to resolve this before an 1.0 release.

[nicolaiarocci]

I am not clear on what your suggestion is right now. In any case, as you mention, readonly should be deprecated, not removed entirely.

And yes the use case was receiving a payload for validation, before sending it to a permanent store. Sometime you have fields which should be there for reads, but should not be writable. From the perspective of a system like that, readonly actually makes some sense 😄 but I recon it might be confusing in different scenarios.

[funkyfuture]

i have no clear suggestion. ;-) here are two:

a) clarifying the documentation. (also noting that it makes only sense if unknown fields are allowed.)

b) turn a {'field': {'readonly': True}} into {'field': {'allowed': False}}. this means that the allowed-rule with a boolean can be used to override the tolerant behaviour when allow_unknown is set for a specific field. since the field must not exist, it can't collide with a sequence of allowed values defined with allowed. it may be confusing anyway.

[nicolaiarocci]

upgrading the docs should be fine I think.