Typed Schemas

[Greedquest]

I know the primary reason for this library was to improve the error messages when validating config files, not to reinvent the way that these files are validated. Nevertheless, I think a really neat addition to this codebase would be if API functions like validate, load_from_file returned a mypy type-hinted version of the value based on the schema. Since we are already validating at runtime, it makes sense to statically validate the config afterwards.

Put simply, if I have some simple schema:

SCHEMA= cfgv.Map(
    "Person",
    "name",
    cfgv.Required("name", cfgv.check_string), 
    cfgv.OptionalNoDefault("age", cfgv.check_int),  
    cfgv.NoAdditionalKeys(["name", "age"]),
) 

Then I would like the signature of validate to be like:

from typing import NamedTuple

class Person(NamedTuple):
    name: str
    age: int | None

def validate(value: Any, schema: ...) -> Person:
	# do the validation
    cast(Person, value)
    return value

... for example. This means that once a value has passed through the cfgv.validate function, it is now statically typed in code and mypy can take it from there. Obviously, I could just cast the result of validate to whatever type I like, however this duplicates the schema definition - once when I write cfgv.Required("name", cfgv.check_string) and then again when I write name: str.

Is this even possible?

[asottile]

one could write a mypy plugin, though some of the validations are unrepresentable in the type system so it wouldn't be perfect

feel free to send a pull request!

[Greedquest]

I was hoping to avoid plugins because I don't know much about them (other than they can get around tricky python structures where standard mypy fails, like pandas datatables I think). Maybe an anthony explains idea!

However my initial idea of dynamically creating NamedTuples looks doomed to fail since GvR has said dynamic fields will never happen: python/mypy#848 (comment). I have got it to the point where there is Required[T] that matches the internal check_fn, however I don't know how to put those generic types into the structure of a Map or a full Schema.

e.g.

T = TypeVar("T")

class TypedCheckFunc(Generic[T]):  # needs a functools.wraps for the docstring, this is just proof of concept
    def __init__(self, wrapped: Callable[..., None]) -> None:
        self._wrapped = wrapped

    def __call__(self, *args: Any, **kwargs: Any) -> None:  # better with ParamSpec, but they're not implemented in mypy just yet
        return self._wrapped(*args, **kwargs)

check_bytes = TypedCheckFunc[bytes](check_type(bytes))  # bytes twice - bit janky

@dataclass #replaces the named tuple version you have
class Required(Generic[T]):
    key: str
    check_fn: TypedCheckFunc[T]
    check = _check_required
    apply_default = _dct_noop
    remove_default = _dct_noop

Required("foo", check_bytes)  # mypy sees Required[bytes] - Good :)

Map("Person", None, Required("foo", check_bytes), Required("bar", check_int)) # I WANT Map[foo=bytes, bar=int] or something hetrogenous, not just typing.Mapping[str, Union[bytes, int]]

[asottile]

it's not possible given the type system, that is why a plugin would be required

[Greedquest]

Hello @asottile hope you are well. I've recently made some progress on this in creating a mypy plugin (at least mypy now crashes when I run it so my code must be doing something!). Jokes aside, instead of starting from a blank canvas without any type information and handling everything type related within the plugin, I think it makes more sense to add some type hints to cfgv first and then fill in the remaining gaps with the plugin. Here's my approach so far:

Consider the simple schema of a Map container and some Required and Optional validators. I'm making those validators Generic[T], where the type reflects the type argument of the check function. For example: req: Required[int] = Required("key", check_type(int)). This can be done automatically using the existing type system.

class Required(Generic[T]):
    def __init__(self, key: str, check_fn: Callable[[T], None]) -> None: ...

Next, in the construction of Map, the caller supplies a list of validators of type [T1], [T2], etc. In the plugin, on every call to cfgv.Map(), it inspects these arguments, reads their generic types, and uses this information to construct a new type. This generates a Map[T] where T is defined according to the validators. It becomes a TypedDictionary containing the relevant keys and data types from the validators.

Finally, more standard Python type hints can be used for the API to bubble up the schema type info. For example:

def apply_defaults(data: dict[str, Any], schema: Map[T]) -> T: ...

The alternative to my approach would be for the plugin to inspect the arguments to Map, finds their constructors, inspect the arguments of those constructors to find the check function, and then use a big switch case to handle different cases like check_int, check_str, or check_type(type) to infer the datatype. I haven't found a more elegant approach yet, but maybe there's one out there.

Now, here's my question: Would it be better to add the necessary type hints directly to cfgv.py, or as a stubs file cfgv.pyi in a potential pull request? Normally, I'd say put the types in directly, but cfgv has some elegant class construction that would become noisier with added types. Also, cfgv seems fairly feature complete, so there's less risk of things getting out of sync between the .pyi and the .py files. Lastly, by using a separate stubs file, there's less risk of introducing a bug that isn't caught by the unit tests. That's what I've been doing locally to avoid modifying cfgv.py and accidentally breaking it without realizing.

What do you think is the best approach you'd like to see in a PR?