improve type safety when using NodeMatcher

[danieleades]

Improve type safety by refactoring the NodeMatcher.

Mypy is unable to infer the return type of the Node.find_all method when NodeMatcher is used. By moving the helper method into the NodeMatcher class and adding some generics it's possible for type checkers to correctly infer the return type of the iterator.

I've noticed that a matcher rarely gets reused, so an alternative approach would be to get rid of the helper class entirely and turn it into a plain function.

[jayaddison]

Are any of the affected callsites recursive methods?

What I'm thinking: an additional frame/entry on the stack (for the intermediate method call) is usually likely to have negligible effect for a call-and-return, but within a deeply recursive method it could have a significant effect on memory usage.

[picnixz]

Seems fine to me but can you confirm that self.document is of correct type actually ? (what is the revealed type?) because I remember that mypy was not happy sometimes because of the fact that self.document was not typed at all (and did not exist on SphinxTransform).

[danieleades]

Seems fine to me but can you confirm that self.document is of correct type actually ? (what is the revealed type?) because I remember that mypy was not happy sometimes because of the fact that self.document was not typed at all (and did not exist on SphinxTransform).

i'm making some changes to the type stubs upstream in typeshed that should help with this

[picnixz]

Thank you!

[jayaddison]

Are any of the affected callsites recursive methods?

From a relatively quick check of the code: no, none of the affected methods are recursive.