8000 Merge branch 'main' into issue-83417-venv-gitignore · python/cpython@41e541c · GitHub
[go: up one dir, main page]

Skip to content

Commit 41e541c

Browse files
authored
Merge branch 'main' into issue-83417-venv-gitignore
2 parents 31d0558 + e6db23f commit 41e541c

File tree

142 files changed

+5341
-2288
lines changed

Some content is hidden

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

142 files changed

+5341
-2288
lines changed

.github/workflows/reusable-docs.yml

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,30 @@ jobs:
1616
name: 'Docs'
1717
runs-on: ubuntu-latest
1818
timeout-minutes: 60
19+
env:
20+
branch_base: 'origin/${{ github.event.pull_request.base.ref }}'
21+
branch_pr: 'origin/${{ github.event.pull_request.head.ref }}'
22+
refspec_base: '+${{ github.event.pull_request.base.sha }}:remotes/origin/${{ github.event.pull_request.base.ref }}'
23+
refspec_pr: '+${{ github.event.pull_request.head.sha }}:remotes/origin/${{ github.event.pull_request.head.ref }}'
1924
steps:
20-
- uses: actions/checkout@v3
25+
- name: 'Check out latest PR branch commit'
26+
uses: actions/checkout@v3
27+
with:
28+
ref: ${{ github.event.pull_request.head.sha }}
29+
# Adapted from https://github.com/actions/checkout/issues/520#issuecomment-1167205721
30+
- name: 'Fetch commits to get branch diff'
31+
run: |
32+
# Fetch enough history to find a common ancestor commit (aka merge-base):
33+
git fetch origin ${{ env.refspec_pr }} --depth=$(( ${{ github.event.pull_request.commits }} + 1 )) \
34+
--no-tags --prune --no-recurse-submodules
35+
36+
# This should get the oldest commit in the local fetched history (which may not be the commit the PR branched from):
37+
COMMON_ANCESTOR=$( git rev-list --first-parent --max-parents=0 --max-count=1 ${{ env.branch_pr }} )
38+
DATE=$( git log --date=iso8601 --format=%cd "${COMMON_ANCESTOR}" )
39+
40+
# Get all commits since that commit date from the base branch (eg: master or main):
41+
git fetch origin ${{ env.refspec_base }} --shallow-since="${DATE}" \
42+
--no-tags --prune --no-recurse-submodules
2143
- name: 'Set up Python'
2244
uses: actions/setup-python@v4
2345
with:
@@ -28,13 +50,6 @@ jobs:
2850
run: make -C Doc/ venv
2951

3052
# To annotate PRs with Sphinx nitpicks (missing references)
31-
- name: 'Get list of changed files'
32-
if: github.event_name == 'pull_request'
33-
id: changed_files
34-
uses: Ana06/get-changed-files@v2.2.0
35-
with:
36-
filter: "Doc/**"
37-
format: csv # works for paths with spaces
3853
- name: 'Build HTML documentation'
3954
continue-on-error: true
4055
run: |
@@ -45,7 +60,7 @@ jobs:
4560
if: github.event_name == 'pull_request'
4661
run: |
4762
python Doc/tools/check-warnings.py \
48-
--check-and-annotate '${{ steps.changed_files.outputs.added_modified }}' \
63+
--annotate-diff '${{ env.branch_base }}' '${{ env.branch_pr }}' \
4964
--fail-if-regression \
5065
--fail-if-improved
5166

.pre-commit-config.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,5 @@ repos:
1414
hooks:
1515
- id: sphinx-lint
1616
args: [--enable=default-role]
17-
files: ^Doc/
17+
files: ^Doc/|^Misc/NEWS.d/next/
1818
types: [rst]

Doc/c-api/datetime.rst

Lines changed: 57 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,54 @@ DateTime Objects
88
Various date and time objects are supplied by the :mod:`datetime` module.
99
Before using any of these functions, the header file :file:`datetime.h` must be
1010
included in your source (note that this is not included by :file:`Python.h`),
11-
and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
11+
and the macro :c:macro:`!PyDateTime_IMPORT` must be invoked, usually as part of
1212
the module initialisation function. The macro puts a pointer to a C structure
13-
into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
13+
into a static variable, :c:data:`!PyDateTimeAPI`, that is used by the following
1414
macros.
1515

16+
.. c:type:: PyDateTime_Date
17+
18+
This subtype of :c:type:`PyObject` represents a Python date object.
19+
20+
.. c:type:: PyDateTime_DateTime
21+
22+
This subtype of :c:type:`PyObject` represents a Python datetime object.
23+
24+
.. c:type:: PyDateTime_Time
25+
26+
This subtype of :c:type:`PyObject` represents a Python time object.
27+
28+
.. c:type:: PyDateTime_Delta
29+
30+
This subtype of :c:type:`PyObject` represents the difference between two datetime values.
31+
32+
.. c:var:: PyTypeObject PyDateTime_DateType
33+
34+
This instance of :c:type:`PyTypeObject` represents the Python date type;
35+
it is the same object as :class:`datetime.date` in the Python layer.
36+
37+
.. c:var:: PyTypeObject PyDateTime_DateTimeType
38+
39+
This instance of :c:type:`PyTypeObject` represents the Python datetime type;
40+
it is the same object as :class:`datetime.datetime` in the Python layer.
41+
42+
.. c:var:: PyTypeObject PyDateTime_TimeType
43+
44+
This instance of :c:type:`PyTypeObject` represents the Python time type;
45+
it is the same object as :class:`datetime.time` in the Python layer.
46+
47+
.. c:var:: PyTypeObject PyDateTime_DeltaType
48+
49+
This instance of :c:type:`PyTypeObject` represents Python type for
50+
the difference between two datetime values;
51+
it is the same object as :class:`datetime.timedelta` in the Python layer.
52+
53+
.. c:var:: PyTypeObject PyDateTime_TZInfoType
54+
55+
This instance of :c:type:`PyTypeObject` represents the Python time zone info type;
56+
it is the same object as :class:`datetime.tzinfo` in the Python layer.
57+
58+
1659
Macro for access to the UTC singleton:
1760

1861
.. c:var:: PyObject* PyDateTime_TimeZone_UTC
@@ -28,7 +71,7 @@ Type-check macros:
2871
.. c:function:: int PyDate_Check(PyObject *ob)
2972
3073
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
31-
:c:data:`PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
74+
:c:data:`!PyDateTime_DateType`. *ob* must not be ``NULL``. This function always
3275
succeeds.
3376
3477
@@ -41,7 +84,7 @@ Type-check macros:
4184
.. c:function:: int PyDateTime_Check(PyObject *ob)
4285
4386
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
44-
:c:data:`PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
87+
:c:data:`!PyDateTime_DateTimeType`. *ob* must not be ``NULL``. This function always
4588
succeeds.
4689
4790
@@ -54,7 +97,7 @@ Type-check macros:
5497
.. c:function:: int PyTime_Check(PyObject *ob)
5598
5699
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
57-
:c:data:`PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
100+
:c:data:`!PyDateTime_TimeType`. *ob* must not be ``NULL``. This function always
58101
succeeds.
59102
60103
@@ -67,7 +110,7 @@ Type-check macros:
67110
.. c:function:: int PyDelta_Check(PyObject *ob)
68111
69112
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
70-
:c:data:`PyDateTime_DeltaType`. *ob* must not be ``NULL``. This function always
113+
:c:data:`!PyDateTime_DeltaType` F438 . *ob* must not be ``NULL``. This function always
71114
succeeds.
72115
73116
@@ -80,7 +123,7 @@ Type-check macros:
80123
.. c:function:: int PyTZInfo_Check(PyObject *ob)
81124
82125
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
83-
:c:data:`PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
126+
:c:data:`!PyDateTime_TZInfoType`. *ob* must not be ``NULL``. This function always
84127
succeeds.
85128
86129
@@ -133,15 +176,15 @@ Macros to create objects:
133176
:class:`datetime.timedelta` objects.
134177
135178
136-
.. c:function:: PyObject* PyTimeZone_FromOffset(PyDateTime_DeltaType* offset)
179+
.. c:function:: PyObject* PyTimeZone_FromOffset(PyObject *offset)
137180
138181
Return a :class:`datetime.timezone` object with an unnamed fixed offset
139182
represented by the *offset* argument.
140183
141184
.. versionadded:: 3.7
142185
143186
144-
.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyDateTime_DeltaType* offset, PyUnicode* name)
187+
.. c:function:: PyObject* PyTimeZone_FromOffsetAndName(PyObject *offset, PyObject *name)
145188
146189
Return a :class:`datetime.timezone` object with a fixed offset represented
147190
by the *offset* argument and with tzname *name*.
@@ -150,8 +193,8 @@ Macros to create objects:
150193
151194
152195
Macros to extract fields from date objects. The argument must be an instance of
153-
:c:data:`PyDateTime_Date`, including subclasses (such as
154-
:c:data:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
196+
:c:type:`PyDateTime_Date`, including subclasses (such as
197+
:c:type:`PyDateTime_DateTime`). The argument must not be ``NULL``, and the type is
155198
not checked:
156199
157200
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
@@ -170,7 +213,7 @@ not checked:
170213
171214
172215
Macros to extract fields from datetime objects. The argument must be an
173-
instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
216+
instance of :c:type:`PyDateTime_DateTime`, including subclasses. The argument
174217
must not be ``NULL``, and the type is not checked:
175218
176219
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
@@ -208,7 +251,7 @@ must not be ``NULL``, and the type is not checked:
208251
209252
210253
Macros to extract fields from time objects. The argument must be an instance of
211-
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
254+
:c:type:`PyDateTime_Time`, including subclasses. The argument must not be ``NULL``,
212255
and the type is not checked:
213256
214257
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
@@ -246,7 +289,7 @@ and the type is not checked:
246289
247290
248291
Macros to extract fields from time delta objects. The argument must be an
249-
instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
292+
instance of :c:type:`PyDateTime_Delta`, including subclasses. The argument must
250293
not be ``NULL``, and the type is not checked:
251294
252295
.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)

Doc/faq/design.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -584,9 +584,9 @@ exhaustive test suites that exercise every line of code in a module.
584584
An appropriate testing discipline can help build large complex applications in
585585
Python as well as having interface specifications would. In fact, it can be
586586
better because an interface specification cannot test certain properties of a
587-
program. For example, the :meth:`list.append` method is expected to add new elements
587+
program. For example, the :meth:`!list.append` method is expected to add new elements
588588
to the end of some internal list; an interface specification cannot test that
589-
your :meth:`list.append` implementation will actually do this correctly, but it's
589+
your :meth:`!list.append` implementation will actually do this correctly, but it's
590590
trivial to check this property in a test suite.
591591

592592
Writing test suites is very helpful, and you might want to design your code to

Doc/faq/gui.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ applications, the applications will not be truly stand-alone, as the application
4343
will still need the Tcl and Tk libraries.
4444

4545
One solution is to ship the application with the Tcl and Tk libraries, and point
46-
to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
46+
to them at run-time using the :envvar:`!TCL_LIBRARY` and :envvar:`!TK_LIBRARY`
4747
environment variables.
4848

4949
Various third-party freeze libraries such as py2exe and cx_Freeze have
@@ -55,16 +55,17 @@ Can I have Tk events handled while waiting for I/O?
5555

5656
On platforms other than Windows, yes, and you don't even
5757
need threads! But you'll have to restructure your I/O
58-
code a bit. Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
58+
code a bit. Tk has the equivalent of Xt's :c:func:`!XtAddInput` call, which allows you
5959
to register a callback function which will be called from the Tk mainloop when
6060
I/O is possible on a file descriptor. See :ref:`tkinter-file-handlers`.
6161

6262

6363
I can't get key bindings to work in Tkinter: why?
6464
-------------------------------------------------
6565

66-
An often-heard complaint is that event handlers bound to events with the
67-
:meth:`bind` method don't get handled even when the appropriate key is pressed.
66+
An often-heard complaint is that event handlers :ref:`bound <bindings-and-events>`
67+
to events with the :meth:`!bind` method
68+
don't get handled even when the appropriate key is pressed.
6869

6970
The most common cause is that the widget to which the binding applies doesn't
7071
have "keyboard focus". Check out the Tk documentation for the focus command.

Doc/faq/library.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ Is there an equivalent to C's onexit() in Python?
111111
-------------------------------------------------
112112
113113
The :mod:`atexit` module provides a register function that is similar to C's
114-
:c:func:`onexit`.
114+
:c:func:`!onexit`.
115115
116116
117117
Why don't my signal handlers work?
@@ -397,7 +397,7 @@ These aren't::
397397
D[x] = D[x] + 1
398398
399399
Operations that replace other objects may invoke those other objects'
400-
:meth:`__del__` method when their reference count reaches zero, and that can
400+
:meth:`~object.__del__` method when their reference count reaches zero, and that can
401401
affect things. This is especially true for the mass updates to dictionaries and
402402
lists. When in doubt, use a mutex!
403403
@@ -730,14 +730,17 @@ The :mod:`select` module is commonly used to help with asynchronous I/O on
730730
sockets.
731731
732732
To prevent the TCP connect from blocking, you can set the socket to non-blocking
733-
mode. Then when you do the :meth:`socket.connect`, you will either connect immediately
733+
mode. Then when you do the :meth:`~socket.socket.connect`,
734+
you will either connect immediately
734735
(unlikely) or get an exception that contains the error number as ``.errno``.
735736
``errno.EINPROGRESS`` indicates that the connection is in progress, but hasn't
736737
finished yet. Different OSes will return different values, so you're going to
737738
have to check what's returned on your system.
738739
739-
You can use the :meth:`socket.connect_ex` method to avoid creating an exception. It will
740-
just return the errno value. To poll, you can call :meth:`socket.connect_ex` again later
740+
You can use the :meth:`~socket.socket.connect_ex` method
741+
to avoid creating an exception.
742+
It will just return the errno value.
743+
To poll, you can call :meth:`~socket.socket.connect_ex` again later
741744
-- ``0`` or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
742745
socket to :meth:`select.select` to check if it's writable.
743746

Doc/faq/programming.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -454,7 +454,7 @@ There are two factors that produce this result:
454454
(the list), and both ``x`` and ``y`` refer to it.
455455
2) Lists are :term:`mutable`, which means that you can change their content.
456456

457-
After the call to :meth:`~list.append`, the content of the mutable object has
457+
After the call to :meth:`!append`, the content of the mutable object has
458458
changed from ``[]`` to ``[10]``. Since both the variables refer to the same
459459
object, using either name accesses the modified value ``[10]``.
460460

@@ -1397,7 +1397,7 @@ To see why this happens, you need to know that (a) if an object implements an
13971397
:meth:`~object.__iadd__` magic method, it gets called when the ``+=`` augmented
13981398
assignment
13991399
is executed, and its return value is what gets used in the assignment statement;
1400-
and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`~list.extend` on the list
1400+
and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`!extend` on the list
14011401
and returning the list. That's why we say that for lists, ``+=`` is a
14021402
"shorthand" for :meth:`!list.extend`::
14031403

@@ -1903,7 +1903,7 @@ identity tests. This prevents the code from being confused by objects such as
19031903
``float('NaN')`` that are not equal to themselves.
19041904

19051905
For example, here is the implementation of
1906-
:meth:`collections.abc.Sequence.__contains__`::
1906+
:meth:`!collections.abc.Sequence.__contains__`::
19071907

19081908
def __contains__(self, value):
19091909
for v in self:

0 commit comments

Comments
 (0)
0