Skip to content

Commit 92b4d80

Browse files
ken71301ken71301
committed
Deploying to gh-pages from @ 94e3735 🚀
1 parent 4231250 commit 92b4d80

File tree

598 files changed

+7762
-6213
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

598 files changed

+7762
-6213
lines changed

‎.buildinfo

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
22
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: 0fa2007971f18ba5d26c0deb45619674
3+
config: ed20a0ffdb2c79674424722536501fd3
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_images/mac_installer_01_introduction.png

186 KB
Loading

‎_images/mac_installer_02_readme.png

200 KB
Loading

‎_images/mac_installer_03_license.png

118 KB
Loading

‎_images/mac_installer_04_installation_type.png

122 KB
Loading

‎_images/mac_installer_05_custom_install.png

165 KB
Loading

‎_images/mac_installer_06_summary.png

154 KB
Loading

‎_images/mac_installer_07_applications.png

145 KB
Loading

‎_images/mac_installer_08_install_certificates.png

170 KB
Loading

‎_images/mac_installer_09_custom_install_free_threaded.png

188 KB
Loading

‎_sources/c-api/buffer.rst.txt

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -244,7 +244,6 @@ The following fields are not influenced by *flags* and must always be filled in
244244
with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
245245
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
246246

247-
248247
readonly, format
249248
~~~~~~~~~~~~~~~~
250249

@@ -253,7 +252,8 @@ readonly, format
253252
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
254253
MUST provide a writable buffer or else report failure. Otherwise, the
255254
exporter MAY provide either a read-only or writable buffer, but the choice
256-
MUST be consistent for all consumers.
255+
MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE`
256+
can be used to request a simple writable buffer.
257257

258258
.. c:macro:: PyBUF_FORMAT
259259
@@ -265,8 +265,9 @@ readonly, format
265265
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
266266
can be used as a stand-alone flag to request a simple writable buffer.
267267

268-
:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
269-
The latter already implies format ``B`` (unsigned bytes).
268+
:c:macro:`PyBUF_FORMAT` must be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`, because
269+
the latter already implies format ``B`` (unsigned bytes). :c:macro:`!PyBUF_FORMAT` cannot be
270+
used on its own.
270271

271272

272273
shape, strides, suboffsets

‎_sources/c-api/exceptions.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -733,7 +733,7 @@ Exception Classes
733733
This creates a class object derived from :exc:`Exception` (accessible in C as
734734
:c:data:`PyExc_Exception`).
735735
736-
The :attr:`!__module__` attribute of the new class is set to the first part (up
736+
The :attr:`~type.__module__` attribute of the new class is set to the first part (up
737737
to the last dot) of the *name* argument, and the class name is set to the last
738738
part (after the last dot). The *base* argument can be used to specify alternate
739739
base classes; it can either be only one class or a tuple of classes. The *dict*

‎_sources/c-api/long.rst.txt

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,6 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
139139
.. versionadded:: 3.13
140140
141141
142-
.. XXX alias PyLong_AS_LONG (for now)
143142
.. c:function:: long PyLong_AsLong(PyObject *obj)
144143
145144
.. index::
@@ -161,6 +160,16 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
161160
.. versionchanged:: 3.10
162161
This function will no longer use :meth:`~object.__int__`.
163162
163+
.. c:namespace:: NULL
164+
165+
.. c:function:: long PyLong_AS_LONG(PyObject *obj)
166+
167+
A :term:`soft deprecated` alias.
168+
Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
169+
it can fail with :exc:`OverflowError` or another exception.
170+
171+
.. deprecated:: 3.14
172+
The function is soft deprecated.
164173
165174
.. c:function:: int PyLong_AsInt(PyObject *obj)
166175

‎_sources/c-api/object.rst.txt

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -367,14 +367,14 @@ Object Protocol
367367
The result will be ``1`` when at least one of the checks returns ``1``,
368368
otherwise it will be ``0``.
369369
370-
If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
370+
If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
371371
determine the subclass status as described in :pep:`3119`. Otherwise,
372372
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
373-
i.e. contained in ``cls.__mro__``.
373+
i.e. contained in :attr:`cls.__mro__ <type.__mro__>`.
374374
375375
Normally only class objects, i.e. instances of :class:`type` or a derived
376376
class, are considered classes. However, objects can override this by having
377-
a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
377+
a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).
378378
379379
380380
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -386,15 +386,15 @@ Object Protocol
386386
The result will be ``1`` when at least one of the checks returns ``1``,
387387
otherwise it will be ``0``.
388388
389-
If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
389+
If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
390390
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
391391
is an instance of *cls* if its class is a subclass of *cls*.
392392
393393
An instance *inst* can override what is considered its class by having a
394-
:attr:`~instance.__class__` attribute.
394+
:attr:`~object.__class__` attribute.
395395
396396
An object *cls* can override if it is considered a class, and what its base
397-
classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
397+
classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
398398
of base classes).
399399
400400

‎_sources/c-api/type.rst.txt

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ Type Objects
5353
.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
5454
5555
Return the type object's internal namespace, which is otherwise only
56-
exposed via a read-only proxy (``cls.__dict__``). This is a
56+
exposed via a read-only proxy (:attr:`cls.__dict__ <type.__dict__>`).
57+
This is a
5758
replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
5859
The returned dictionary must be treated as read-only.
5960
@@ -140,7 +141,7 @@ Type Objects
140141
Return true if *a* is a subtype of *b*.
141142
142143
This function only checks for actual subtypes, which means that
143-
:meth:`~class.__subclasscheck__` is not called on *b*. Call
144+
:meth:`~type.__subclasscheck__` is not called on *b*. Call
144145
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
145146
would do.
146147
@@ -174,29 +175,30 @@ Type Objects
174175
175176
.. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
176177
177-
Return the type's name. Equivalent to getting the type's ``__name__`` attribute.
178+
Return the type's name. Equivalent to getting the type's
179+
:attr:`~type.__name__` attribute.
178180
179181
.. versionadded:: 3.11
180182
181183
.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
182184
183185
Return the type's qualified name. Equivalent to getting the
184-
type's ``__qualname__`` attribute.
186+
type's :attr:`~type.__qualname__` attribute.
185187
186188
.. versionadded:: 3.11
187189
188190
.. c:function:: PyObject* PyType_GetFullyQualifiedName(PyTypeObject *type)
189191
190192
Return the type's fully qualified name. Equivalent to
191-
``f"{type.__module__}.{type.__qualname__}"``, or ``type.__qualname__`` if
192-
``type.__module__`` is not a string or is equal to ``"builtins"``.
193+
``f"{type.__module__}.{type.__qualname__}"``, or :attr:`type.__qualname__`
194+
if :attr:`type.__module__` is not a string or is equal to ``"builtins"``.
193195
194196
.. versionadded:: 3.13
195197
196198
.. c:function:: PyObject* PyType_GetModuleName(PyTypeObject *type)
197199
198-
Return the type's module name. Equivalent to getting the ``type.__module__``
199-
attribute.
200+
Return the type's module name. Equivalent to getting the
201+
:attr:`type.__module__` attribute.
200202
201203
.. versionadded:: 3.13
202204

‎_sources/c-api/typeobj.rst.txt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -567,12 +567,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
567567

568568
For :ref:`statically allocated type objects <static-types>`,
569569
the *tp_name* field should contain a dot.
570-
Everything before the last dot is made accessible as the :attr:`__module__`
570+
Everything before the last dot is made accessible as the :attr:`~type.__module__`
571571
attribute, and everything after the last dot is made accessible as the
572-
:attr:`~definition.__name__` attribute.
572+
:attr:`~type.__name__` attribute.
573573

574574
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
575-
:attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined
575+
:attr:`~type.__name__` attribute, and the :attr:`~type.__module__` attribute is undefined
576576
(unless explicitly set in the dictionary, as explained above). This means your
577577
type will be impossible to pickle. Additionally, it will not be listed in
578578
module documentations created with pydoc.
@@ -1131,7 +1131,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
11311131

11321132
.. c:macro:: Py_TPFLAGS_MANAGED_DICT
11331133
1134-
This bit indicates that instances of the class have a ``__dict__``
1134+
This bit indicates that instances of the class have a `~object.__dict__`
11351135
attribute, and that the space for the dictionary is managed by the VM.
11361136

11371137
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
@@ -1335,8 +1335,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
13351335
.. c:member:: const char* PyTypeObject.tp_doc
13361336
13371337
An optional pointer to a NUL-terminated C string giving the docstring for this
1338-
type object. This is exposed as the :attr:`__doc__` attribute on the type and
1339-
instances of the type.
1338+
type object. This is exposed as the :attr:`~type.__doc__` attribute on the
1339+
type and instances of the type.
13401340

13411341
**Inheritance:**
13421342

@@ -2036,7 +2036,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
20362036
A collection of subclasses. Internal use only. May be an invalid pointer.
20372037

20382038
To get a list of subclasses, call the Python method
2039-
:py:meth:`~class.__subclasses__`.
2039+
:py:meth:`~type.__subclasses__`.
20402040

20412041
.. versionchanged:: 3.12
20422042

‎_sources/c-api/unicode.rst.txt

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,7 @@ These APIs can be used to work with surrogates:
317317
318318
.. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
319319
320-
Join two surrogate characters and return a single :c:type:`Py_UCS4` value.
320+
Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
321321
*high* and *low* are respectively the leading and trailing surrogates in a
322322
surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
323323
be in the range [0xDC00; 0xDFFF].
@@ -338,6 +338,8 @@ APIs:
338338
This is the recommended way to allocate a new Unicode object. Objects
339339
created using this function are not resizable.
340340
341+
On error, set an exception and return ``NULL``.
342+
341343
.. versionadded:: 3.3
342344
343345
@@ -614,6 +616,8 @@ APIs:
614616
615617
Return the length of the Unicode object, in code points.
616618
619+
On error, set an exception and return ``-1``.
620+
617621
.. versionadded:: 3.3
618622
619623
@@ -657,6 +661,8 @@ APIs:
657661
not out of bounds, and that the object can be modified safely (i.e. that it
658662
its reference count is one).
659663
664+
Return ``0`` on success, ``-1`` on error with an exception set.
665+
660666
.. versionadded:: 3.3
661667
662668
@@ -666,6 +672,8 @@ APIs:
666672
Unicode object and the index is not out of bounds, in contrast to
667673
:c:func:`PyUnicode_READ_CHAR`, which performs no error checking.
668674
675+
Return character on success, ``-1`` on error with an exception set.
676+
669677
.. versionadded:: 3.3
670678
671679
@@ -674,6 +682,7 @@ APIs:
674682
675683
Return a substring of *unicode*, from character index *start* (included) to
676684
character index *end* (excluded). Negative indices are not supported.
685+
On error, set an exception and return ``NULL``.
677686
678687
.. versionadded:: 3.3
679688
@@ -990,6 +999,9 @@ These are the UTF-8 codec APIs:
990999
object. Error handling is "strict". Return ``NULL`` if an exception was
9911000
raised by the codec.
9921001
1002+
The function fails if the string contains surrogate code points
1003+
(``U+D800`` - ``U+DFFF``).
1004+
9931005
9941006
.. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
9951007
@@ -1002,6 +1014,9 @@ These are the UTF-8 codec APIs:
10021014
On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
10031015
return ``NULL``.
10041016
1017+
The function fails if the string contains surrogate code points
1018+
(``U+D800`` - ``U+DFFF``).
1019+
10051020
This caches the UTF-8 representation of the string in the Unicode object, and
10061021
subsequent calls will return a pointer to the same buffer. The caller is not
10071022
responsible for deallocating the buffer. The buffer is deallocated and
@@ -1429,8 +1444,9 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
14291444
Compare a Unicode object with a char buffer which is interpreted as
14301445
being UTF-8 or ASCII encoded and return true (``1``) if they are equal,
14311446
or false (``0``) otherwise.
1432-
If the Unicode object contains surrogate characters or
1433-
the C string is not valid UTF-8, false (``0``) is returned.
1447+
If the Unicode object contains surrogate code points
1448+
(``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8,
1449+
false (``0``) is returned.
14341450
14351451
This function does not raise exceptions.
14361452

‎_sources/deprecations/pending-removal-in-3.14.rst.txt

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,6 @@ Pending Removal in Python 3.14
4747
* :mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
4848
(Contributed by Alan Williams in :gh:`72346`.)
4949

50-
* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
51-
taken into consideration by the import system (:gh:`97879`).
52-
5350
* :mod:`importlib.abc` deprecated classes:
5451

5552
* :class:`!importlib.abc.ResourceReader`

‎_sources/deprecations/pending-removal-in-3.15.rst.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ Pending Removal in Python 3.15
1717
* The :option:`!--cgi` flag to the :program:`python -m http.server`
1818
command-line interface has been deprecated since Python 3.13.
1919

20+
* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
21+
taken into consideration by the import system (:gh:`97879`).
22+
2023
* :class:`locale`:
2124

2225
* The :func:`~locale.getdefaultlocale` function

‎_sources/extending/newtypes.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
296296
descriptors that are used at runtime is that any attribute defined this way can
297297
have an associated doc string simply by providing the text in the table. An
298298
application can use the introspection API to retrieve the descriptor from the
299-
class object, and get the doc string using its :attr:`!__doc__` attribute.
299+
class object, and get the doc string using its :attr:`~type.__doc__` attribute.
300300

301301
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
302302
of ``NULL`` is required.

‎_sources/extending/newtypes_tutorial.rst.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ only used for variable-sized objects and should otherwise be zero.
144144
If you want your type to be subclassable from Python, and your type has the same
145145
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
146146
inheritance. A Python subclass of your type will have to list your type first
147-
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
147+
in its :attr:`~type.__bases__`, or else it will not be able to call your type's
148148
:meth:`~object.__new__` method without getting an error. You can avoid this problem by
149149
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
150150
base type does. Most of the time, this will be true anyway, because either your

‎_sources/faq/programming.rst.txt

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1613,9 +1613,16 @@ method too, and it must do so carefully. The basic implementation of
16131613
self.__dict__[name] = value
16141614
...
16151615

1616-
Most :meth:`!__setattr__` implementations must modify
1617-
:meth:`self.__dict__ <object.__dict__>` to store
1618-
local state for self without causing an infinite recursion.
1616+
Many :meth:`~object.__setattr__` implementations call :meth:`!object.__setattr__` to set
1617+
an attribute on self without causing infinite recursion::
1618+
1619+
class X:
1620+
def __setattr__(self, name, value):
1621+
# Custom logic here...
1622+
object.__setattr__(self, name, value)
1623+
1624+
Alternatively, it is possible to set attributes by inserting
1625+
entries into :attr:`self.__dict__ <object.__dict__>` directly.
16191626

16201627

16211628
How do I call a method defined in a base class from a derived class that extends it?

‎_sources/glossary.rst.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ Glossary
342342
docstring
343343
A string literal which appears as the first expression in a class,
344344
function or module. While ignored when the suite is executed, it is
345-
recognized by the compiler and put into the :attr:`!__doc__` attribute
345+
recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
346346
of the enclosing class, function or module. Since it is available via
347347
introspection, it is the canonical place for documentation of the
348348
object.
@@ -1231,7 +1231,7 @@ Glossary
12311231
type
12321232
The type of a Python object determines what kind of object it is; every
12331233
object has a type. An object's type is accessible as its
1234-
:attr:`~instance.__class__` attribute or can be retrieved with
1234+
:attr:`~object.__class__` attribute or can be retrieved with
12351235
``type(obj)``.
12361236

12371237
type alias

‎_sources/howto/annotations.rst.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,9 @@ Your code will have to have a separate code path if the object
102102
you're examining is a class (``isinstance(o, type)``).
103103
In that case, best practice relies on an implementation detail
104104
of Python 3.9 and before: if a class has annotations defined,
105-
they are stored in the class's ``__dict__`` dictionary. Since
105+
they are stored in the class's :attr:`~type.__dict__` dictionary. Since
106106
the class may or may not have annotations defined, best practice
107-
is to call the ``get`` method on the class dict.
107+
is to call the :meth:`~dict.get` method on the class dict.
108108

109109
To put it all together, here is some sample code that safely
110110
accesses the ``__annotations__`` attribute on an arbitrary
@@ -121,8 +121,8 @@ the type of ``ann`` using :func:`isinstance` before further
121121
examination.
122122

123123
Note that some exotic or malformed type objects may not have
124-
a ``__dict__`` attribute, so for extra safety you may also wish
125-
to use :func:`getattr` to access ``__dict__``.
124+
a :attr:`~type.__dict__` attribute, so for extra safety you may also wish
125+
to use :func:`getattr` to access :attr:`!__dict__`.
126126

127127

128128
Manually Un-Stringizing Stringized Annotations

0 commit comments

Comments
 (0)