This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: [doc] replace 'distutils' examples with 'setuptools'
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, elmjag, eric.araujo, sobolevn, taleinat
Priority: normal Keywords: patch

Created on 2021-12-07 08:08 by elmjag, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 30062 open sobolevn, 2021-12-11 19:23
Messages (6)
msg407896 - (view) Author: Elmir (elmjag) Date: 2021-12-07 08:08
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
msg408333 - (view) Author: Nikita Sobolev (sobolevn) * (Python triager) Date: 2021-12-11 19:21
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 :)
msg408428 - (view) Author: Elmir (elmjag) Date: 2021-12-13 07:53
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.
msg409512 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2022-01-02 18:42
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!).
msg410844 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2022-01-18 07:14
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.
msg412341 - (view) Author: Elmir (elmjag) Date: 2022-02-02 07:53
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
History
Date User Action Args
2022-04-11 14:59:53adminsetgithub: 90163
2022-02-02 07:53:49elmjagsetmessages: + msg412341
2022-01-18 07:14:32taleinatsetnosy: + taleinat
messages: + msg410844
2022-01-02 18:42:28eric.araujosetnosy: + eric.araujo
messages: + msg409512
2021-12-13 07:53:07elmjagsetmessages: + msg408428
2021-12-11 19:23:23sobolevnsetkeywords: + patch
stage: patch review
pull_requests: + pull_request28282
2021-12-11 19:21:24sobolevnsetnosy: + sobolevn
messages: + msg408333
2021-12-07 08:08:57elmjagcreate