gh-121658: Add MimeTypes.add_type docs

[stinovlas]

Closes #121658.

Add missing MimeTypes.add_type documentation.

• Issue: gh-121658

---

📚 Documentation preview 📚: https://cpython-previews--121665.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-app[bot]]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes, you will be put in the comfy chair!

[Eclips4]

Please could you include a versionadded note?

A

This was added more than 22 years ago. Do you think it's still need a versionadded note?

[AA-Turner]

Yes, because the documentation is new. The only other way to compare in documentation is to look at older versions (e.g. https://docs.python.org/3.10/), which don't list the method.

However, if the method was present when mimetypes was added to the stdlib, I probably wouldn't add a note.

A

[stinovlas]

Yes, because the documentation is new. The only other way to compare in documentation is to look at older versions (e.g. https://docs.python.org/3.10/), which don't list the method.

However, if the method was present when mimetypes was added to the stdlib, I probably wouldn't add a note.

I digged in the git history and found out that the function has been added in Python 2.3, six years before Python 3.0 came out. Since we only feature documentation for Python 3 nowadays and this has been in Python 3 since the beginning, I don't thing that note is necessary.

But if you insist, I can add a note that this has been added in Python 2.3.

[AA-Turner]

Since we only feature documentation for Python 3 nowadays and this has been in Python 3 since the beginning, I don't thing that note is necessary.

Python 3 is not divorced from 2; indeed elements of Python 0.9 survive to this day. Note that there are many .. version{added,changed}:: that have 2.x. The mimetypes module has documentation going back to Python 1.6.

I do think it is good practice to note, but we could add these version added/changed markers in a follow-up commit if need be.

A

[hugovk]

Note that there are many .. version{added,changed}:: that have 2.x.

Hmm, I only find five: four of which are in "What's New in Python 2.7" (a historical release note), and the only one in the library was recently added in https://github.com/python/cpython/pull/109020 ;)

❯ rg "version(added|changed):: 2"  Doc
Doc/whatsnew/2.7.rst
2374:  .. versionchanged:: 2.7.13
2589:.. versionadded:: 2.7.15
2779:.. versionadded:: 2.7.14
2792:.. versionchanged:: 2.7.14

Doc/library/calendar.rst
506:.. versionadded:: 2.5

There was some discussion last year about removing old ones: https://github.com/python/cpython/issues/108514

The current policy is that the Python x (3) manual should have a complete history of feature changes so that one can write and maintain code compatible with any minor x.y (3.y) version.

The discussion was about removing or hiding somewhere between 3.0 and 3.6, so I don't think we need to note additions/changes in 2.x.

[AA-Turner]

My comeuppance for writing that on the train sans laptop, I suppose! In that case let's not add the note for now.

Personally I do think these notes are very useful, even when historical, as it means that you can have confidence that a function exists in all the versions of Python that you support without needing to double-check. But that can be a separate discussion.

A

[stinovlas]

I added a note about this being added in Python 2.3. I guess it can't hurt.

[stinovlas]

After pushing a version note, it seems that there was some documentation added in #122301 (although quite different from this one), which is not linked in the original issue #121658. So, where do we go from here?

[hugovk]

After pushing a version note, it seems that there was some documentation added in #122301 (although quite different from this one), which is not linked in the original issue #121658. So, where do we go from here?

The text already added in https://github.com/python/cpython/pull/122301 is more detailed, except the .. versionadded:: 2.3 bit which probably isn't very useful in 2024.

Let's close this PR, thank you anyway for your contribution!