Skip to content

Commit e97b7be

Browse files
AA-TurnerAA-Turner
authored
GH-92584: Remove distutils from the newtypes tutorial includes (#108024)
1 parent 13966da commit e97b7be

File tree

10 files changed

+42
-43
lines changed

10 files changed

+42
-43
lines changed

‎Doc/extending/newtypes_tutorial.rst‎

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ extension module :mod:`!custom`:
4545
allows defining heap-allocated extension types using the
4646
:c:func:`PyType_FromSpec` function, which isn't covered in this tutorial.
4747

48-
.. literalinclude:: ../includes/custom.c
48+
.. literalinclude:: ../includes/newtypes/custom.c
4949

5050
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
5151
from the previous chapter. This file defines three things:
@@ -194,36 +194,32 @@ This adds the type to the module dictionary. This allows us to create
194194
>>> mycustom = custom.Custom()
195195
196196
That's it! All that remains is to build it; put the above code in a file called
197-
:file:`custom.c` and:
197+
:file:`custom.c`,
198+
199+
.. literalinclude:: ../includes/newtypes/pyproject.toml
200+
201+
in a file called :file:`pyproject.toml`, and
198202

199203
.. code-block:: python
200204
201-
from distutils.core import setup, Extension
202-
setup(name="custom", version="1.0",
203-
ext_modules=[Extension("custom", ["custom.c"])])
205+
from setuptools import Extension, setup
206+
setup(ext_modules=[Extension("custom", ["custom.c"])])
204207
205208
in a file called :file:`setup.py`; then typing
206209

207210
.. code-block:: shell-session
208211
209-
$ python setup.py build
212+
$ python -m pip install .
210213
211-
at a shell should produce a file :file:`custom.so` in a subdirectory; move to
212-
that directory and fire up Python --- you should be able to ``import custom`` and
213-
play around with Custom objects.
214+
in a shell should produce a file :file:`custom.so` in a subdirectory
215+
and install it; now fire up Python --- you should be able to ``import custom``
216+
and play around with ``Custom`` objects.
214217

215218
That wasn't so hard, was it?
216219

217220
Of course, the current Custom type is pretty uninteresting. It has no data and
218221
doesn't do anything. It can't even be subclassed.
219222

220-
.. note::
221-
While this documentation showcases the standard :mod:`!distutils` module
222-
for building C extensions, it is recommended in real-world use cases to
223-
use the newer and better-maintained ``setuptools`` library. Documentation
224-
on how to do this is out of scope for this document and can be found in
225-
the `Python Packaging User's Guide <https://packaging.python.org/tutorials/distributing-packages/>`_.
226-
227223

228224
Adding data and methods to the Basic example
229225
============================================
@@ -232,7 +228,7 @@ Let's extend the basic example to add some data and methods. Let's also make
232228
the type usable as a base class. We'll create a new module, :mod:`!custom2` that
233229
adds these capabilities:
234230

235-
.. literalinclude:: ../includes/custom2.c
231+
.. literalinclude:: ../includes/newtypes/custom2.c
236232

237233

238234
This version of the module has a number of changes.
@@ -514,17 +510,21 @@ We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the
514510
module name in the :c:type:`PyModuleDef` struct, and update the full class
515511
name in the :c:type:`PyTypeObject` struct.
516512

517-
Finally, we update our :file:`setup.py` file to build the new module:
513+
Finally, we update our :file:`setup.py` file to include the new module,
518514

519515
.. code-block:: python
520516
521-
from distutils.core import setup, Extension
522-
setup(name="custom", version="1.0",
523-
ext_modules=[
524-
Extension("custom", ["custom.c"]),
525-
Extension("custom2", ["custom2.c"]),
526-
])
517+
from setuptools import Extension, setup
518+
setup(ext_modules=[
519+
Extension("custom", ["custom.c"]),
520+
Extension("custom2", ["custom2.c"]),
521+
])
522+
523+
and then we re-install so that we can ``import custom2``:
524+
525+
.. code-block:: shell-session
527526
527+
$ python -m pip install .
528528
529529
Providing finer control over data attributes
530530
============================================
@@ -535,7 +535,7 @@ version of our module, the instance variables :attr:`!first` and :attr:`!last`
535535
could be set to non-string values or even deleted. We want to make sure that
536536
these attributes always contain strings.
537537

538-
.. literalinclude:: ../includes/custom3.c
538+
.. literalinclude:: ../includes/newtypes/custom3.c
539539

540540

541541
To provide greater control, over the :attr:`!first` and :attr:`!last` attributes,
@@ -682,7 +682,7 @@ To allow a :class:`!Custom` instance participating in a reference cycle to
682682
be properly detected and collected by the cyclic GC, our :class:`!Custom` type
683683
needs to fill two additional slots and to enable a flag that enables these slots:
684684

685-
.. literalinclude:: ../includes/custom4.c
685+
.. literalinclude:: ../includes/newtypes/custom4.c
686686

687687

688688
First, the traversal method lets the cyclic GC know about subobjects that could
@@ -806,7 +806,7 @@ increases an internal counter:
806806
>>> print(s.increment())
807807
2
808808
809-
.. literalinclude:: ../includes/sublist.c
809+
.. literalinclude:: ../includes/newtypes/sublist.c
810810

811811

812812
As you can see, the source code closely resembles the :class:`!Custom` examples in

Doc/includes/custom.c renamed to Doc/includes/newtypes/custom.c

File renamed without changes.

Doc/includes/custom2.c renamed to Doc/includes/newtypes/custom2.c

File renamed without changes.

Doc/includes/custom3.c renamed to Doc/includes/newtypes/custom3.c

File renamed without changes.

Doc/includes/custom4.c renamed to Doc/includes/newtypes/custom4.c

File renamed without changes.

‎Doc/includes/newtypes/pyproject.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[build-system]
2+
requires = ["setuptools"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "custom"
7+
version = "1"

‎Doc/includes/newtypes/setup.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
from setuptools import Extension, setup
2+
setup(ext_modules=[
3+
Extension("custom", ["custom.c"]),
4+
Extension("custom2", ["custom2.c"]),
5+
Extension("custom3", ["custom3.c"]),
6+
Extension("custom4", ["custom4.c"]),
7+
Extension("sublist", ["sublist.c"]),
8+
])

Doc/includes/sublist.c renamed to Doc/includes/newtypes/sublist.c

File renamed without changes.

Doc/includes/test.py renamed to Doc/includes/newtypes/test.py

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -187,13 +187,6 @@
187187
>>> gc.enable()
188188
"""
189189

190-
import os
191-
import sys
192-
from distutils.util import get_platform
193-
PLAT_SPEC = "%s-%d.%d" % (get_platform(), *sys.version_info[:2])
194-
src = os.path.join("build", "lib.%s" % PLAT_SPEC)
195-
sys.path.append(src)
196-
197190
if __name__ == "__main__":
198191
import doctest, __main__
199192
doctest.testmod(__main__)

‎Doc/includes/setup.py‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)