docutils-develop

[Docutils-develop] Giving type annotations to docutils

[Komiya T. <i.t...@gm...>]

Hi developers,

Now I and @cocoatomo started to make type stubs for docutils on
typeshed project. typeshed is a collection of type annotations (type
hints) for many libraries.
https://github.com/tk0miya/typeshed

At present, typeshed library contains type annotations for docutils.
But it is broken. As a result, mypy, a well known type checker, fails
to inspect typing source codes using docutils.
https://github.com/python/typeshed/issues/1269

Our goal is to provide correct type annotations to docutils. I think
there are two ways to do that. The first one is update type stubs on
typeshed project. Another one is add type annotations into docutils
itself. What do you think?

Thanks,
Takeshi KOMIYA

Re: [Docutils-develop] Giving type annotations to docutils

[Komiya T. <i.t...@gm...>]

Hi all,

After a half year, finally, I and @cocoatomo finished to give type
annotations to docutils.
I'd like to publish them ASAP. I think it is better if docutils
package contains them because
the synchronize of code and annotation is important. So they should be
maintained at same place.
But, if you're not interested in, I'd like to maintain it from myside.

What do you think?

Thanks,
Takeshi KOMIYA

2018年3月14日(水) 23:10 Komiya Takeshi <i.t...@gm...>:
>
> Hi developers,
>
> Now I and @cocoatomo started to make type stubs for docutils on
> typeshed project. typeshed is a collection of type annotations (type
> hints) for many libraries.
> https://github.com/tk0miya/typeshed
>
> At present, typeshed library contains type annotations for docutils.
> But it is broken. As a result, mypy, a well known type checker, fails
> to inspect typing source codes using docutils.
> https://github.com/python/typeshed/issues/1269
>
> Our goal is to provide correct type annotations to docutils. I think
> there are two ways to do that. The first one is update type stubs on
> typeshed project. Another one is add type annotations into docutils
> itself. What do you think?
>
> Thanks,
> Takeshi KOMIYA

Re: [Docutils-develop] Giving type annotations to docutils

[Komiya T. <i.t...@gm...>]

Hi all,

I noticed py2 and py36- support will be dropped in the next release.
It helps to integrate type annotations in docutils-stub package into
upstream.
I believe it helps to develop third-party extensions (including Sphinx).
Is there any chance to merge it into the docutils?

Thanks,
Takeshi KOMIYA

2018年10月13日(土) 13:50 Komiya Takeshi <i.t...@gm...>:
>
> Hi all,
>
> After a half year, finally, I and @cocoatomo finished to give type
> annotations to docutils.
> I'd like to publish them ASAP. I think it is better if docutils
> package contains them because
> the synchronize of code and annotation is important. So they should be
> maintained at same place.
> But, if you're not interested in, I'd like to maintain it from myside.
>
> What do you think?
>
> Thanks,
> Takeshi KOMIYA
>
> 2018年3月14日(水) 23:10 Komiya Takeshi <i.t...@gm...>:
> >
> > Hi developers,
> >
> > Now I and @cocoatomo started to make type stubs for docutils on
> > typeshed project. typeshed is a collection of type annotations (type
> > hints) for many libraries.
> > https://github.com/tk0miya/typeshed
> >
> > At present, typeshed library contains type annotations for docutils.
> > But it is broken. As a result, mypy, a well known type checker, fails
> > to inspect typing source codes using docutils.
> > https://github.com/python/typeshed/issues/1269
> >
> > Our goal is to provide correct type annotations to docutils. I think
> > there are two ways to do that. The first one is update type stubs on
> > typeshed project. Another one is add type annotations into docutils
> > itself. What do you think?
> >
> > Thanks,
> > Takeshi KOMIYA

Re: [Docutils-develop] Giving type annotations to docutils

[Guenter M. <mi...@us...>]

Dear Takeshi KOMIYA, dear Docutils developers,

On 2022-01-02, Komiya Takeshi wrote:
> Hi all,

> I noticed py2 and py36- support will be dropped in the next release.

Yes, I am currently working on this, ... soon in the repository.

> It helps to integrate type annotations in docutils-stub package into
> upstream.
> I believe it helps to develop third-party extensions (including Sphinx).
> Is there any chance to merge it into the docutils?

In my view, it would make sense to have annotations right in the "master".

This could also be used as an indicator for the public API: 

In the `Docutils Backwards Compatibility Policy`__, we could change the
clause about the "scope of the public API" to an "opt-in" scheme: only
function/class interfaces with annotations belong to the stable, public
API while not annotated function interfaces may be changed or removed in
future versions if this helps to improve or clean up the code base.

What do other Docutils developers/contributors/users think?

Thanks,

Günter


__ https://docutils.sourceforge.io/docs/dev/policies.html#backwards-compatibility-policy

Re: [Docutils-develop] Giving type annotations to docutils

[Guenter M. <mi...@us...>]

Dear Takeshi KOMIYA, dear Docutils developers,

Adam Turner opened feature request #87
(https://sourceforge.net/p/docutils/feature-requests/87/)
for this issue. I suggest moving the discussion there.

Thanks, Günter