Repository navigation
[doc] replace 'distutils' examples with 'setuptools' #90163
Description
| BPO | 46005 |
|---|---|
| Nosy | @taleinat, @merwok, @sobolevn, @elmjag |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2021-12-07.08:08:57.511>
labels = ['3.11', 'type-feature', '3.10', 'docs']
title = "[doc] replace 'distutils' examples with 'setuptools'"
updated_at = <Date 2022-02-02.07:53:49.787>
user = 'https://github.com/elmjag'bugs.python.org fields:
activity = <Date 2022-02-02.07:53:49.787>
actor = 'elmjag'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-12-07.08:08:57.511>
creator = 'elmjag'
dependencies = []
files = []
hgrepos = []
issue_num = 46005
keywords = ['patch']
message_count = 6.0
messages = ['407896', '408333', '408428', '409512', '410844', '412341']
nosy_count = 5.0
nosy_names = ['taleinat', 'eric.araujo', 'docs@python', 'sobolevn', 'elmjag']
pr_nums = ['30062']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue46005'
versions = ['Python 3.10', 'Python 3.11']
Activity
elmjag commentedon Dec 7, 2021
As the distutils have been deprecated, the documentation on building C/C++ extension modules should be updated to use more future proof tool.
I guess the section:
'Building C and C++ Extensions with distutils'
should be replaced with:
'Building C and C++ Extensions with setuptools'
Here is link to the section that needs to be updated/replaced:
https://docs.python.org/3/extending/building.html#building-c-and-c-extensions-with-distutils
sobolevn commentedon Dec 11, 2021
Or maybe we should just include https://github.com/python/cpython/blob/main/Doc/distutils/_setuptools_disclaimer.rst as others do?
I will send my proposal :)
elmjag commentedon Dec 13, 2021
I think it would be very helpful to include an example how to build with setuptools as well. As it in the end boils down to two simple steps:
"from distutils.core import setup, Extension"
to
"from setuptools import setup, Extension"
It took me a lot of time to figure out that 'setuptools' have this 'drop-in replacement' API for distutils. IMHO, it's not very well documented anywhere.
I can make a PR with such addition, if you thinks it's good idea.
merwok commentedon Jan 2, 2022
Distutils is deprecated, and core Python docs are not the place to show how to use a specific build system (thanks to a lot of work, we now have multiple viable build systems!).
taleinat commentedon Jan 18, 2022
First, I think that it's good and useful to have full, well-maintained examples of how to build extension modules in the docs.
Second, until distutils is removed, I think we should keep the documentation for how to use it. Due to this, I don't think adding the "setuptools disclaimer" would be appropriate, since we shouldn't remove the section once the setuptools docs are updated.
It seems to me that we should:
Add a prominent note about distutils being deprecated and what that means: can one still use it, should one still use it, when is it planned to be removed, etc.
Add mention that 3rd-party tools are now the recommended way to build extensions. Include links to the sections in these libraries' docs explaining how to build extensions.
2 remaining items
jacalata commentedon Jun 25, 2022
This is the setuptools doc page: https://setuptools.pypa.io/en/latest/userguide/ext_modules.html, which is probably what needs to be updated
aisk commentedon Sep 18, 2023
Currently, distutil has been removed. Should we remove this section and only refer to other third-party tools, especially setuptools?
hugovk commentedon Sep 18, 2023
This is how the pages looks now for 3.12 (will become
/3/when 3.12 is released): https://docs.python.org/3.12/extending/building.htmlCompare with 3.11 (the current
/3/docs version): https://docs.python.org/3.11/extending/building.htmlFor 3.12 the distutils section has been removed, and replaced with a a reference to the setuptools page (in PR #95239).
Is there anything else that needs doing for this issue or can we close it?
merwok commentedon Sep 18, 2023
OK to close for me. @taleinat ?
AA-Turner commentedon Sep 19, 2023
#108030 addresses one final part (extending/windows).
A
StanFromIreland commentedon Aug 10, 2025
This is now under a new issue, I think this is complete then?