Menu
▾
▴
docutils-develop
|
From: Adam T. <aa-...@us...> - 2022-01-03 03:49:16
|
--- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 03:49 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Chris S. <chr...@us...> - 2022-01-03 04:05:31
|
Firstly, definitely +1 in general for "inline" type annotations. > In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified That's an interesting take 😬 As noted in the original post, the major use-case of these type annotations are for third-party extension development, e.g. to allow for programmatic (mypy) type checking against docutils usage. Third-party extensions should "only" care about the public API --- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 03:49 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2022-01-03 09:09:09
|
> I couldn't work out how to respond to Günter's post > [1](https://sourceforge.net/p/docutils/mailman/message/37410168/) > through Sourceforge's web interface You may use any e-mail application to send a mail to Doc...@li.... It's explained in the documentation [Docutils Mailing Lists(https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-develop) A click on the link given there will open an e-mail application in most browsers. --- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 04:05 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Adam T. <aa-...@us...> - 2022-01-03 10:18:13
|
This is also sort of my problem -- I have many mail aliases (e.g. doc...@ex...) that forward to the single account I send from (ad...@ex...). This allows me to filter incoming emails and if one alias gets on a spam list it isn't a massive deal. That does mean that sending to public mailing lists is an issue though -- why I prefer bug trackers/forums like discourse. If needed though I'll sort myself out eventually! A --- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 10:13 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Adam T. <aa-...@us...> - 2022-01-03 10:13:02
|
> That's an interesting take 😬 Aha sorry - imprecision of language strikes again! For almost everyone, type annotations of the public API will be far and away the most useful. For developers of Docutils itself, I believe also annotating private methods will be useful -- my comment was more arguing against just annotating the public API, but carried with it the implicit assumption that the public API would be annotated regardless. Sorry for the misunderstanding! A --- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 04:05 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2022-01-03 12:39:06
|
I.e. we should not use "not annotated" as the only indication of a non-public or provisional part of the API. It would still help in the major task of clearly defining the public API, if we could state that by default: * all functions, classes, and variables are provisional unless annotated * annotated objects that are not part of the public API must say so (either using underscore or in the docstring). * if a module is marked as provisional, this holds for all objects defined in this module, whether they are annotated or not. --- ** [feature-requests:#87] [FR] Giving type annotations to docutils** **Status:** open **Group:** Default **Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner **Last Updated:** Mon Jan 03, 2022 10:18 AM UTC **Owner:** nobody *Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* [1]: https://sourceforge.net/p/docutils/mailman/message/37410168/ > > 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. Günter @milde -- happy to help with this if you'd like? > > 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? In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful. I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion. A --- Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
|
From: Günter M. <mi...@us...> - 2024-08-05 20:03:02
|
Thanks for the first commits with type hints.
We should, however, mention, that using the type hints (with e.g. mypy) requires Python 3.10 or newer. With 3.9 and mypy 0.812, I get, e.g., for `mypy docutils/core.py` the result:
Found 392 errors in 14 files (checked 1 source file)
Also, the boilerplate (TYPE_CHECKING blocks) are quite large. How about a dedicated module for Docutils-specific type definitions?
We may also define shortcuts/aliases for often used Unions like `str | os.PathLike[str]` which may offer a better intelligible way of representing
`pathdict: dict[str, list[str | os.PathLike[str]] | str | os.PathLike[str]]`, say.
---
**[feature-requests:#87] [FR] Giving type annotations to docutils**
**Status:** open
**Group:** Default
**Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam Turner
**Last Updated:** Mon Jan 03, 2022 12:39 PM UTC
**Owner:** nobody
*Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface*
[1]: https://sourceforge.net/p/docutils/mailman/message/37410168/
> > 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.
Günter @milde -- happy to help with this if you'd like?
> > 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?
In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful.
I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion.
A
---
Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/
To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options. Or, if this is a mailing list, you can unsubscribe from the mailing list. |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X