[doc] replace 'distutils' examples with 'setuptools'

[elmjag]

BPO	46005
Nosy	@taleinat, @merwok, @sobolevn, @elmjag
PRs	bpo-46005: add note about setuptools to Doc/extending/building.rst #30062

^{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']

[elmjag]

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]

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]

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:

• install 'setuptools' package
• change import line:

"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]

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]

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:

1. 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.

2. 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.

[elmjag]

I agree that documenting third-party tools in CPython docs is a bit weird. I guess this is more an issue with setuptools docs. IMHO here is no clear explanation on how to build extension modules there.

As a temporary work around, I wrote an example of building extension module with setuptools here:

https://elmjag.github.io/setuptools.html

[jacalata]

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]

Currently, distutil has been removed. Should we remove this section and only refer to other third-party tools, especially setuptools?

[hugovk]

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.html

Compare with 3.11 (the current /3/ docs version): https://docs.python.org/3.11/extending/building.html

For 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]

OK to close for me. @taleinat ?

[AA-Turner]

#108030 addresses one final part (extending/windows).

A