(Backward) incompatible signature in `jsonschema.protocols.Validator` per static type checking

[candleindark]

The signature of jsonschema.protocols.Validator is backward incompatible with earlier versions and definitions such as jsonschema.Draft202012Validator in static type checking. Specifically, an registry argument is now needed, as far as static checking is concerned, in instantiating an object of a class that is casted as a jsonschema.protocols.Validator.

# as_validator.py

from typing import cast, Type

from jsonschema import Draft202012Validator
from jsonschema.protocols import Validator


validator_cls = cast(Type[Validator], Draft202012Validator)

schema = {"maxItems" : 2}
validator_cls(schema).validate([2, 3, 4])

Running mypy on tmp.py produces the following error.

(dandi-schema) ➜  dandi-schema git:(devendorize) ✗ mypy as_validator.py 
as_validator.py:12: error: Missing positional argument "registry" in call to "Validator"  [call-arg]
    validator_cls(schema).validate([2, 3, 4])
    ^~~~~~~~~~~~~~~~~~~~~
Found 1 error in 1 file (checked 1 source file)

# as_draft_202012_validator.py

from jsonschema import Draft202012Validator

schema = {"maxItems" : 2}
Draft202012Validator(schema).validate([2, 3, 4])

On the other hand, running mypy on as_draft_202012_validator.py doesn't produce any error.

(dandi-schema) ➜  dandi-schema git:(devendorize) ✗ mypy as_draft_202012_validator.py
Success: no issues found in 1 source file

This incompatibility exists, at least, in three places source code, documentation, and the types-jsonschema package.

• Source code which mentioned earlier
• Documentation at 4.18.0 and beyond
• types-jsonschema at the current version of 4.24.0.20250708

Context:
Python used: 3.9.16

[Julian]

I haven't untangled all involved here, but just as a quick response:

• this is probably just a missing default in protocols.Validator, exacerbated by not having tests for the type annotation code, so PR certainly welcome to add a test and then fix the default
• types-jsonschema isn't maintained by me so you possibly will need to file an additional bug there even if/when we fix it here, though I suspect usually they're pretty good at keeping up to date, I think @sirosen is involved upstream in typeshed until the day that we have decent annotation support here (which honestly isn't a high priority but small fixes which don't modify runtime code are the way to keep getting us closer, and occasionally I do shove an additional bit in myself when it doesn't cause 50 nonsense typing errors to do so)
• there's no "backwards compatibility" really when it comes to type annotations, backwards compatibility is at the behavior and API layers -- so if there ever was a bug in the annotations I'd certainly want it fixed, but I don't think of such things in compatibility terms personally, if anything the type annotations should represent what the promised API is but the typing ecosystem isn't mature enough to do this well yet (again, which isn't to say we're not going to get there anyhow) But yeah you shouldn't make any compatibility assumptions about the annotations themselves, just the defined public API

[sirosen]

This is my quarterly reminder that I need to come back to working on type checking and typing tests here. 😂

I can put up a PR to add a default for registry to the protocol here and then backport it to typeshed.
I'll try to circle back after my workday.

---

This is all related to the change that I put up for typeshed, which provides types-jsonschema: python/typeshed#14327
I didn't notice that what I was porting over would be incorrect in requiring registry; my bad! If I had realized it as an issue at the time, I probably would have opened a PR or issue here before the typeshed PR.

Having the type stubs out of sync with the protocol as declared in jsonschema is undesirable. You can get type checking failures, and then you check your usage against jsonschema itself and your usage matches the declared protocol. That kind of discrepancy is confusing as a developer -- it's why I opened that typeshed PR.

So my policy is: I will happily port any changes to the protocol here into types-jsonschema.

---

there's no "backwards compatibility" really when it comes to type annotations, backwards compatibility is at the behavior and API layers -- so if there ever was a bug in the annotations I'd certainly want it fixed, but I don't think of such things in compatibility terms personally

I agree. I think that as Python typing continues to evolve we may eventually start to think about "type compatibility", but we're not there yet.

Typing is mature enough to be useful, but given the discrepancies between mypy and pyright alone, you have multiple definitions out there for compatibility. I don't think it's reasonable for a library to try to reason rigorously about the compatibility of its types changing at present.
(Simple example: str | Iterable[str] is a subtype of Iterable[str] in several checkers, but not in pytype.)