feat(DRAFT): DType.__eq__ as a TypeIs[...]

[dangotbanned]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• refactor(typing): Avoid more ignore[attr-defined] on Datetime #2049 (comment)
• refactor(typing): Avoid more ignore[attr-defined] on Datetime #2049 (comment)

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

If you have comments or can explain your changes, please do so below

Important

Seems that we can't represent this well in the current typing spec AFAICT.
See (dbadb09) message

https://typing.readthedocs.io/en/latest/spec/narrowing.html

Type checkers should assume that type narrowing should be applied to the expression that is passed as the first positional argument to a user-defined type guard.
If the type guard function accepts more than one argument, no type narrowing is applied to those additional argument expressions.

If a type guard function is implemented as an instance method or class method, the first positional argument maps to the second parameter (after “self” or “cls”).

So __eq__ currently describes the opposite of the spec:

import narwhals as nw

dtype = nw.Boolean()
second_parameter = nw.Int64

dtype == second_parameter
dtype.__eq__(second_parameter)

# Equivalent to
isinstance_or_issubclass(second_parameter, type(dtype))
isinstance_or_issubclass(nw.Int64, nw.Boolean)
issubclass(nw.Int64, nw.Boolean)

[dangotbanned]

FIXME

Need some help getting this work again
https://results.pre-commit.ci/run/github/760058710/1739990897.pkejAgUjQ3CdKYXvgIDqPw

I don't understand what the two checks are doing https://narwhals-dev.github.io/narwhals/api-reference/dtypes/#narwhals.dtypes

Or why this seems to include Literal?

narwhals/utils/check_api_reference.py

Lines 42 to 49 in 228e478

	BASE_DTYPES = {
	"NumericType",
	"DType",
	"TemporalType",
	"Literal",
	"OrderedDict",
	"Mapping",
	}

[dangotbanned]

@MarcoGorelli I've added a little write-up for what I believe is the blocking issue.

Maybe this is a naive question, why was __eq__ chosen for this instead of __(instance|subclass)check__?
https://docs.python.org/3/reference/datamodel.html#customizing-instance-and-subclass-checks