type annotation for docutils is incomplete #1269
Labels
help wanted
An actionable problem of low to medium complexity where a PR would be very welcome
stubs: incomplete
Annotations or sub-modules missing from an existing package or module
Comments
|
Is there anything I can do? If needed, I'll try to create stubs. |
|
Thanks for reporting this! Yes, sounds like we just need to write more stubs. PRs would be appreciated. |
|
I'm reading CONTRIBUTING.md now. Did you already get permission from docutils project? |
|
I'm not sure actually—it looks like the docutils stubs were added back in 2015 (337abed), when typeshed's norms weren't as clearly established. Perhaps @matthiaskramm remembers; I couldn't find anything on a quick search of the docutils mailing lists. |
|
337abed merged pytype's and mypy's stubs. The docutils stubs go back to 2014, when mypy still had its own |
|
Until more complete stubs can be generated, would it be reasonable to delete the |
srittau
added
the
stubs: incomplete
|
not sure if this is the right place for this, but i'm having trouble getting mypy to perform typechecking of the i'm working through the sphinx extension 'todo' tutorial here - https://www.sphinx-doc.org/en/master/development/tutorials/todo.html but mypy is none too happy about the docutils types- ...
# Create a reference
newnode = nodes.reference("", "")
innernode = nodes.emphasis(_("here"), _("here"))
newnode["refdocname"] = todo_info["docname"] # error: Unsupported target for indexed assignment ("reference")
...now, looking at the docutils source code, this should be ok.
why is mypy failing to recognise the base class? i see only this stub - https://github.com/python/typeshed/blob/4d734e38dde295e93c27efd6ead3bb5c05d03fe5/stubs/docutils/docutils/nodes.pyi, but it doesn't appear to include the base classes. (I don't know anything about these stub files by the way) |
|
The docutils stubs were added in #5192, and lots of things are missing from them, including the whole |
i need help with that can you point me to any references on how to write stub files? best practices? |
|
seems like it should be possible (in principle) to generate stub files from the source code. is there a tool for that? |
|
Stub file syntax is a subset of Python syntax, so there isn't much to learn. Best practices etc are explained in |
|
Will try and find some time over the next couple of days to investigate |
|
For reference, #5192 did not add docutils stubs, they existed before, but were mainly consisting of module-level |
|
i'm about a third of the way through the type annotations for the |
|
In case it's useful, here's what stubtest has to say about docutils on master: |
|
draft pull request up (#5237) input most welcome |
|
FYI: https://pypi.org/project/docutils-stubs/ When I posted a comment at last, I asked about the permission to docutils project. But I did not get any answers. As a result, I made a stub package as a 3rd party package. |
Do you want to open a pull request to merge that into typeshed? I'd be happy to review based on the work I've done so far in #5237 |
|
AFAIK, permissions from the upstream project is needed to merge stubs into the typeshed, right? I've never gotten it. And we have to update it to the latest one (I made it for the old versions). |
righto. let's wait for a maintainer to chime in. I've just tried your |
|
Yes. That's the reason why I made it. I've used it to type-check Sphinx project itself. |
|
|
We no longer require permission from the upstream library (which would be docutils here) to add stubs to typeshed. (See the changes in #2608; I can't find that wording in CONTRIBUTING.md any more but I don't think we changed our stance.) It would be great to see the different docutils stubs merged. |
This was referenced Jun 20, 2021
tristanlatr
pushed a commit
to tristanlatr/pydoctor
that referenced
this issue
Jun 22, 2021
tsibley
added a commit
to nextstrain/cli
that referenced
this issue
Feb 28, 2022
types-docutils isn't sufficient with recent (?) mypy versions, causing:
nextstrain/cli/rst/sphinx.py:71: error: "dispatch_visit" undefined in superclass
nextstrain/cli/rst/sphinx.py:88: error: "dispatch_departure" undefined in superclass
which seems to be because the docutils-stubs/nodes.pyi file installed by
types-docutils contains
def __getattr__(…) -> Any
for nodes.NodeVisitor, which is apparently not understood by mypy.
Typeshed knows it's docutils stubs aren't great.¹ The docutils-stubs
distribution has a docutils-stubs/nodes.pyi² that mypy understands, but
installing that then breaks pyright. Oy vey.
¹ python/typeshed#1269
² Yes, both the docutils-stubs and types-docutils distributions install
a "docutils-stubs" directory in Python's site-packages. This is how
typestubs are supposed to be installed for the package "docutils".
@tk0miya did this ever happen? |
AlexWaygood
added
the
help wanted
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
It seems
third_party/3/docutilscontains only very few classes and modules of docutils.https://github.com/python/typeshed/tree/master/third_party/3/docutils
For example, the only one class
referenceis defined atnodes.pyi. But actualdocutils.nodesmodule provides many classes and functions:As a result, mypy fails for hinting.
The text was updated successfully, but these errors were encountered: