[Python-checkins] [3.12] GH-92584: Remove distutils from the newtypes tutorial includes (GH-108024) (#108333)
Yhg1s
webhook-mailer at python.org
Tue Aug 22 16:07:19 EDT 2023
https://github.com/python/cpython/commit/200af4294e9a99bf0d4f535c43f75f304eb53497
commit: 200af4294e9a99bf0d4f535c43f75f304eb53497
branch: 3.12
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Yhg1s <thomas at python.org>
date: 2023-08-22T22:07:15+02:00
summary:
[3.12] GH-92584: Remove distutils from the newtypes tutorial includes (GH-108024) (#108333)
GH-92584: Remove distutils from the newtypes tutorial includes (GH-108024)
(cherry picked from commit e97b7bef4fbe71821d59d2f41f311e514fd29e39)
Co-authored-by: Adam Turner <9087854+AA-Turner at users.noreply.github.com>
files:
A Doc/includes/newtypes/custom.c
A Doc/includes/newtypes/custom2.c
A Doc/includes/newtypes/custom3.c
A Doc/includes/newtypes/custom4.c
A Doc/includes/newtypes/pyproject.toml
A Doc/includes/newtypes/setup.py
A Doc/includes/newtypes/sublist.c
A Doc/includes/newtypes/test.py
D Doc/includes/custom.c
D Doc/includes/custom2.c
D Doc/includes/custom3.c
D Doc/includes/custom4.c
D Doc/includes/setup.py
D Doc/includes/sublist.c
D Doc/includes/test.py
M Doc/extending/newtypes_tutorial.rst
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index f8684df5dd829..c2bc5f699a159 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -45,7 +45,7 @@ extension module :mod:`!custom`:
allows defining heap-allocated extension types using the
:c:func:`PyType_FromSpec` function, which isn't covered in this tutorial.
-.. literalinclude:: ../includes/custom.c
+.. literalinclude:: ../includes/newtypes/custom.c
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
from the previous chapter. This file defines three things:
@@ -196,36 +196,32 @@ This adds the type to the module dictionary. This allows us to create
>>> mycustom = custom.Custom()
That's it! All that remains is to build it; put the above code in a file called
-:file:`custom.c` and:
+:file:`custom.c`,
+
+.. literalinclude:: ../includes/newtypes/pyproject.toml
+
+in a file called :file:`pyproject.toml`, and
.. code-block:: python
- from distutils.core import setup, Extension
- setup(name="custom", version="1.0",
- ext_modules=[Extension("custom", ["custom.c"])])
+ from setuptools import Extension, setup
+ setup(ext_modules=[Extension("custom", ["custom.c"])])
in a file called :file:`setup.py`; then typing
.. code-block:: shell-session
- $ python setup.py build
+ $ python -m pip install .
-at a shell should produce a file :file:`custom.so` in a subdirectory; move to
-that directory and fire up Python --- you should be able to ``import custom`` and
-play around with Custom objects.
+in a shell should produce a file :file:`custom.so` in a subdirectory
+and install it; now fire up Python --- you should be able to ``import custom``
+and play around with ``Custom`` objects.
That wasn't so hard, was it?
Of course, the current Custom type is pretty uninteresting. It has no data and
doesn't do anything. It can't even be subclassed.
-.. note::
- While this documentation showcases the standard :mod:`!distutils` module
- for building C extensions, it is recommended in real-world use cases to
- use the newer and better-maintained ``setuptools`` library. Documentation
- on how to do this is out of scope for this document and can be found in
- the `Python Packaging User's Guide <https://packaging.python.org/tutorials/distributing-packages/>`_.
-
Adding data and methods to the Basic example
============================================
@@ -234,7 +230,7 @@ Let's extend the basic example to add some data and methods. Let's also make
the type usable as a base class. We'll create a new module, :mod:`!custom2` that
adds these capabilities:
-.. literalinclude:: ../includes/custom2.c
+.. literalinclude:: ../includes/newtypes/custom2.c
This version of the module has a number of changes.
@@ -516,17 +512,21 @@ We rename :c:func:`!PyInit_custom` to :c:func:`!PyInit_custom2`, update the
module name in the :c:type:`PyModuleDef` struct, and update the full class
name in the :c:type:`PyTypeObject` struct.
-Finally, we update our :file:`setup.py` file to build the new module:
+Finally, we update our :file:`setup.py` file to include the new module,
.. code-block:: python
- from distutils.core import setup, Extension
- setup(name="custom", version="1.0",
- ext_modules=[
- Extension("custom", ["custom.c"]),
- Extension("custom2", ["custom2.c"]),
- ])
+ from setuptools import Extension, setup
+ setup(ext_modules=[
+ Extension("custom", ["custom.c"]),
+ Extension("custom2", ["custom2.c"]),
+ ])
+
+and then we re-install so that we can ``import custom2``:
+
+.. code-block:: shell-session
+ $ python -m pip install .
Providing finer control over data attributes
============================================
@@ -537,7 +537,7 @@ version of our module, the instance variables :attr:`!first` and :attr:`!last`
could be set to non-string values or even deleted. We want to make sure that
these attributes always contain strings.
-.. literalinclude:: ../includes/custom3.c
+.. literalinclude:: ../includes/newtypes/custom3.c
To provide greater control, over the :attr:`!first` and :attr:`!last` attributes,
@@ -684,7 +684,7 @@ To allow a :class:`!Custom` instance participating in a reference cycle to
be properly detected and collected by the cyclic GC, our :class:`!Custom` type
needs to fill two additional slots and to enable a flag that enables these slots:
-.. literalinclude:: ../includes/custom4.c
+.. literalinclude:: ../includes/newtypes/custom4.c
First, the traversal method lets the cyclic GC know about subobjects that could
@@ -808,7 +808,7 @@ increases an internal counter:
>>> print(s.increment())
2
-.. literalinclude:: ../includes/sublist.c
+.. literalinclude:: ../includes/newtypes/sublist.c
As you can see, the source code closely resembles the :class:`!Custom` examples in
diff --git a/Doc/includes/custom.c b/Doc/includes/newtypes/custom.c
similarity index 100%
rename from Doc/includes/custom.c
rename to Doc/includes/newtypes/custom.c
diff --git a/Doc/includes/custom2.c b/Doc/includes/newtypes/custom2.c
similarity index 100%
rename from Doc/includes/custom2.c
rename to Doc/includes/newtypes/custom2.c
diff --git a/Doc/includes/custom3.c b/Doc/includes/newtypes/custom3.c
similarity index 100%
rename from Doc/includes/custom3.c
rename to Doc/includes/newtypes/custom3.c
diff --git a/Doc/includes/custom4.c b/Doc/includes/newtypes/custom4.c
similarity index 100%
rename from Doc/includes/custom4.c
rename to Doc/includes/newtypes/custom4.c
diff --git a/Doc/includes/newtypes/pyproject.toml b/Doc/includes/newtypes/pyproject.toml
new file mode 100644
index 0000000000000..ea7937a317147
--- /dev/null
+++ b/Doc/includes/newtypes/pyproject.toml
@@ -0,0 +1,7 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "custom"
+version = "1"
diff --git a/Doc/includes/newtypes/setup.py b/Doc/includes/newtypes/setup.py
new file mode 100644
index 0000000000000..67f83673bcc65
--- /dev/null
+++ b/Doc/includes/newtypes/setup.py
@@ -0,0 +1,8 @@
+from setuptools import Extension, setup
+setup(ext_modules=[
+ Extension("custom", ["custom.c"]),
+ Extension("custom2", ["custom2.c"]),
+ Extension("custom3", ["custom3.c"]),
+ Extension("custom4", ["custom4.c"]),
+ Extension("sublist", ["sublist.c"]),
+])
diff --git a/Doc/includes/sublist.c b/Doc/includes/newtypes/sublist.c
similarity index 100%
rename from Doc/includes/sublist.c
rename to Doc/includes/newtypes/sublist.c
diff --git a/Doc/includes/test.py b/Doc/includes/newtypes/test.py
similarity index 94%
rename from Doc/includes/test.py
rename to Doc/includes/newtypes/test.py
index 09ebe3fec0bdb..55a5cf9f68b94 100644
--- a/Doc/includes/test.py
+++ b/Doc/includes/newtypes/test.py
@@ -187,13 +187,6 @@
>>> gc.enable()
"""
-import os
-import sys
-from distutils.util import get_platform
-PLAT_SPEC = "%s-%d.%d" % (get_platform(), *sys.version_info[:2])
-src = os.path.join("build", "lib.%s" % PLAT_SPEC)
-sys.path.append(src)
-
if __name__ == "__main__":
import doctest, __main__
doctest.testmod(__main__)
diff --git a/Doc/includes/setup.py b/Doc/includes/setup.py
deleted file mode 100644
index a38a39de3e7c8..0000000000000
--- a/Doc/includes/setup.py
+++ /dev/null
@@ -1,9 +0,0 @@
-from distutils.core import setup, Extension
-setup(name="noddy", version="1.0",
- ext_modules=[
- Extension("noddy", ["noddy.c"]),
- Extension("noddy2", ["noddy2.c"]),
- Extension("noddy3", ["noddy3.c"]),
- Extension("noddy4", ["noddy4.c"]),
- Extension("shoddy", ["shoddy.c"]),
- ])
More information about the Python-checkins
mailing list