Type hints for Element.walk are incorrect

[castedo]

panflute/panflute/base.py

Line 225 in f99f82d

def walk(self, action: Callable[[Element, Element], Any], doc: Element | None=None, stop_if=None) -> Element | None:

The action function:

• parameter takes [Element, Doc] as arguments not [Element, Element]
• returns an Element, typing Any isn't very useful

The doc parameter take a Doc not an Element.

The documentation/helpstring for this function says an empty list can be returned. This type hint says it can not. What is correct. Can an empty list be returned or not?

Also the Element.doc method type hint returns Any | Element. But it should be Doc shouldn't it?

[Leilei332]

Doc isn't defined in base.py, and it can't be imported since it is a circular import. So Doc's parent class Element has to be used.

It's my fault that I didn't made it clear that the PR for type hints is a work in progress (though I did mark the PR as a draft). I think we had better revert the type hint at the moment. I welcome you to point out the issues in this pull request through GitHub's PR review feature in my pull request.

[castedo]

@sergiocorreia and/or @Leilei332 How do you want to proceed with type hints in the main branch of panflute?

I am getting close to finishing https://github.com/castedo/panflute-stubs. I plan on adding type hints for panflute.table_elements within two weeks (and maybe will stop there). The only other submodule left with non-low-level methods in the documentation is panflute.tools.

The main question is whether you prefer to have these type hints integrated into the main branch for the next panflute release or whether you prefer there exists a separate panflute-stubs package on PyPI and some pointers in Panflute documentation pointing to the stub library.

Users of panflute 2.3.1 will prefer a pip installable separate stubs package (because 2.3.1 doesn't have type hints). Users of future releases of panflute will prefer type hints be included with future panflute releases. But keeping type hints, main code, and documentation in-sync and tested in the main branch is more work. But we could just plan on having separate packages and users that want type checking have to pip install a stubs package.