Description

jacalata

opened on Jun 25, 2022

Issue body actions

Documentation

https://docs.python.org/3.11/distutils/index.html has this disclaimer

This document is being retained solely until the setuptools documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

I couldn't find anywhere tracking progress towards having that coverage in setuptools docs, so that's the purpose of this issue. I'm not sure whether there needs to be a consensus, or how to make the decision to check off a chapter as fully replaced.

• 1. An Introduction to Distutils
• 2. Writing the Setup Script
• 3. Writing the Setup Configuration File
• 4. Creating a Source Distribution
• 5. Creating Built Distributions
• 6. Distutils Examples
• 7. Extending Distutils
• 8. Command Reference
• 9. API Reference

This issue can track work being done in the setuptools docs: pypa/setuptools#3401

Activity

1. jacalata

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jun 25, 2022
2. merwok commented on Jul 23, 2022

   

   merwok

   on Jul 23, 2022

   Member

   More actions

   Rather than pure deletion, I think the docs could be retained to avoid breaking all the external links, with a small explanation for the removal of the package and links to equivalent setutpools docs.

   I think there are existing tickets about removing distutils, could you search for them and add links between this ticket and those ones?
3. CAM-Gerlach commented on Nov 3, 2022

   

   CAM-Gerlach

   on Nov 3, 2022

   Member

   More actions

   Rather than pure deletion, I think the docs could be retained to avoid breaking all the external links, with a small explanation for the removal of the package and links to equivalent setutpools docs.

   That's a good idea. distutils is removed completely from the stdlib in 3.12, what I will propose in a PR for 3.12 following your recommendations, is retaining the document and top-level sections headers to not break any links, add an admonition up top and messages to each section explaining distutils has been removed and linking to the up to date setuptools equivalents, but remove all the obsolete content, as it doesn't really belong here anymore and makes it much easier for users to miss or ignore the message (especially if deeplinked). And of course, users can always switch to an older Python version that includes distutils if they still actually need these docs (just like with any other removed module).

   For previous maintained versions (3.11 and 3.10), the content can be retained as-is, but the messages redirecting users could be added, to help direct users to the Setuptools equivalents now rather than only when Python 3.12 is released and it is fully removed. To make merging straightforward (and also not block it on a final decision), I can drop a PR with this first (as well as one with the other docs changes for distutils removal), which can be backported, and then a followup PR only for 3.12 to remove all the obsolete section content.

   A few sections don't have direct Setuptools equivalents, but this would give Setuptools a full year to decide whether they want to add the relevant section and link it here, move the existing section over to their docs and maintain it themselves, or leave it deliberately undocumented as internal implementation details. And of course, users could still switch to an older version to see them.

   I think there are existing tickets about removing distutils, could you search for them and add links between this ticket and those ones?

   #92584 (issue) and #99061 (PR)

   Reacted by Petr Viktorin
4. CAM-Gerlach

   added

   3.12only security fixesonly security fixes

   on Nov 3, 2022
5. StanFromIreland commented on Aug 17, 2025

   

   StanFromIreland

   on Aug 17, 2025

   Member

   More actions

   These have been removed in all bugfix versions, is there anything left to do here?
6. StanFromIreland

   added

   pendingThe issue will be closed if no feedback is providedThe issue will be closed if no feedback is provided

   on Aug 17, 2025
7. github-project-automation

   added this to docs issueson Aug 17, 2025
8. github-project-automation

   moved this to Todo in docs issueson Aug 17, 2025
9. AA-Turner

   closed this as not plannedon Aug 17, 2025

Issue actions