Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e240c70

Browse files
mdickinsonmdickinson
committed
Merge remote-tracking branch 'mdickinson/fraction-format' into fraction-format
2 parents 67e020c + b358b37 commit e240c70

384 files changed

Lines changed: 7587 additions & 4832 deletions

File tree

Some content is hidden

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

‎.github/workflows/doc.yml‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -50,18 +50,8 @@ jobs:
5050
run: make -C Doc/ venv
5151
- name: 'Check documentation'
5252
run: make -C Doc/ check
53-
- name: 'Upload NEWS'
54-
uses: actions/upload-artifact@v3
55-
with:
56-
name: NEWS
57-
path: Doc/build/NEWS
5853
- name: 'Build HTML documentation'
5954
run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
60-
- name: 'Upload docs'
61-
uses: actions/upload-artifact@v3
62-
with:
63-
name: doc-html
64-
path: Doc/build/html
6555

6656
# Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
6757
doctest:

‎Doc/_static/og-image.png‎

14.2 KB
Loading

‎Doc/c-api/apiabiversion.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ See :ref:`stable` for a discussion of API and ABI stability across versions.
5858
Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
5959
hexversion ``0x030a00f0``.
6060

61+
Use this for numeric comparisons, e.g. ``#if PY_VERSION_HEX >= ...``.
62+
6163
This version is also available via the symbol :data:`Py_Version`.
6264

6365
.. c:var:: const unsigned long Py_Version

‎Doc/c-api/refcounting.rst‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
Reference Counting
88
******************
99

10-
The macros in this section are used for managing reference counts of Python
11-
objects.
10+
The functions and macros in this section are used for managing reference counts
11+
of Python objects.
1212

1313

1414
.. c:function:: Py_ssize_t Py_REFCNT(PyObject *o)
@@ -129,6 +129,11 @@ objects.
129129
It is a good idea to use this macro whenever decrementing the reference
130130
count of an object that might be traversed during garbage collection.
131131
132+
.. versionchanged:: 3.12
133+
The macro argument is now only evaluated once. If the argument has side
134+
effects, these are no longer duplicated.
135+
136+
132137
.. c:function:: void Py_IncRef(PyObject *o)
133138
134139
Increment the reference count for object *o*. A function version of :c:func:`Py_XINCREF`.
@@ -139,3 +144,40 @@ objects.
139144
140145
Decrement the reference count for object *o*. A function version of :c:func:`Py_XDECREF`.
141146
It can be used for runtime dynamic embedding of Python.
147+
148+
149+
.. c:macro:: Py_SETREF(dst, src)
150+
151+
Macro safely decrementing the `dst` reference count and setting `dst` to
152+
`src`.
153+
154+
As in case of :c:func:`Py_CLEAR`, "the obvious" code can be deadly::
155+
156+
Py_DECREF(dst);
157+
dst = src;
158+
159+
The safe way is::
160+
161+
Py_SETREF(dst, src);
162+
163+
That arranges to set `dst` to `src` _before_ decrementing reference count of
164+
*dst* old value, so that any code triggered as a side-effect of `dst`
165+
getting torn down no longer believes `dst` points to a valid object.
166+
167+
.. versionadded:: 3.6
168+
169+
.. versionchanged:: 3.12
170+
The macro arguments are now only evaluated once. If an argument has side
171+
effects, these are no longer duplicated.
172+
173+
174+
.. c:macro:: Py_XSETREF(dst, src)
175+
176+
Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead
177+
of :c:func:`Py_DECREF`.
178+
179+
.. versionadded:: 3.6
180+
181+
.. versionchanged:: 3.12
182+
The macro arguments are now only evaluated once. If an argument has side
183+
effects, these are no longer duplicated.

‎Doc/c-api/structures.rst‎

Lines changed: 18 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -228,29 +228,30 @@ Implementing functions and methods
228228
Structure used to describe a method of an extension type. This structure has
229229
four fields:
230230
231-
+------------------+---------------+-------------------------------+
232-
| Field | C Type | Meaning |
233-
+==================+===============+===============================+
234-
| :attr:`ml_name` | const char \* | name of the method |
235-
+------------------+---------------+-------------------------------+
236-
| :attr:`ml_meth` | PyCFunction | pointer to the C |
237-
| | | implementation |
238-
+------------------+---------------+-------------------------------+
239-
| :attr:`ml_flags` | int | flag bits indicating how the |
240-
| | | call should be constructed |
241-
+------------------+---------------+-------------------------------+
242-
| :attr:`ml_doc` | const char \* | points to the contents of the |
243-
| | | docstring |
244-
+------------------+---------------+-------------------------------+
245-
246-
The :attr:`ml_meth` is a C function pointer. The functions may be of different
231+
.. c:member:: const char* ml_name
232+
233+
name of the method
234+
235+
.. c:member:: PyCFunction ml_meth
236+
237+
pointer to the C implementation
238+
239+
.. c:member:: int ml_flags
240+
241+
flags bits indicating how the call should be constructed
242+
243+
.. c:member:: const char* ml_doc
244+
245+
points to the contents of the docstring
246+
247+
The :c:member:`ml_meth` is a C function pointer. The functions may be of different
247248
types, but they always return :c:expr:`PyObject*`. If the function is not of
248249
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
249250
Even though :c:type:`PyCFunction` defines the first parameter as
250251
:c:expr:`PyObject*`, it is common that the method implementation uses the
251252
specific C type of the *self* object.
252253
253-
The :attr:`ml_flags` field is a bitfield which can include the following flags.
254+
The :c:member:`ml_flags` field is a bitfield which can include the following flags.
254255
The individual flags indicate either a calling convention or a binding
255256
convention.
256257

‎Doc/c-api/typeobj.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,8 @@ Quick Reference
147147
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
148148
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
149149
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
150+
| [:c:member:`~PyTypeObject.tp_watched`] | char | | | | | |
151+
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
150152

151153
.. [#slots]
152154
@@ -2090,6 +2092,13 @@ and :c:type:`PyType_Type` effectively act as defaults.)
20902092
.. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9)
20912093

20922094

2095+
.. c:member:: char PyTypeObject.tp_watched
2096+
2097+
Internal. Do not use.
2098+
2099+
.. versionadded:: 3.12
2100+
2101+
20932102
.. _static-types:
20942103

20952104
Static Types

‎Doc/conf.py‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,25 @@
1313
# General configuration
1414
# ---------------------
1515

16-
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
17-
'pyspecific', 'c_annotations', 'escape4chm',
18-
'asdl_highlight', 'peg_highlight', 'glossary_search']
16+
extensions = [
17+
'asdl_highlight',
18+
'c_annotations',
19+
'escape4chm',
20+
'glossary_search',
21+
'peg_highlight',
22+
'pyspecific',
23+
'sphinx.ext.coverage',
24+
'sphinx.ext.doctest',
25+
]
26+
27+
# Skip if downstream redistributors haven't installed it
28+
try:
29+
import sphinxext.opengraph
30+
except ImportError:
31+
pass
32+
else:
33+
extensions.append('sphinxext.opengraph')
34+
1935

2036
doctest_global_setup = '''
2137
try:
@@ -89,6 +105,14 @@
89105
# Short title used e.g. for <title> HTML tags.
90106
html_short_title = '%s Documentation' % release
91107

108+
# Deployment preview information, from Netlify
109+
# (See netlify.toml and https://docs.netlify.com/configure-builds/environment-variables/#git-metadata)
110+
html_context = {
111+
"is_deployment_preview": os.getenv("IS_DEPLOYMENT_PREVIEW"),
112+
"repository_url": os.getenv("REPOSITORY_URL"),
113+
"pr_id": os.getenv("REVIEW_ID")
114+
}
115+
92116
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
93117
# using the given strftime format.
94118
html_last_updated_fmt = '%b %d, %Y'
@@ -114,7 +138,7 @@
114138
html_use_opensearch = 'https://docs.python.org/' + version
115139

116140
# Additional static files.
117-
html_static_path = ['tools/static']
141+
html_static_path = ['_static', 'tools/static']
118142

119143
# Output file base name for HTML help builder.
120144
htmlhelp_basename = 'python' + release.replace('.', '')
@@ -238,3 +262,13 @@
238262
# Relative filename of the data files
239263
refcount_file = 'data/refcounts.dat'
240264
stable_abi_file = 'data/stable_abi.dat'
265+
266+
# sphinxext-opengraph config
267+
ogp_site_url = 'https://docs.python.org/3/'
268+
ogp_site_name = 'Python documentation'
269+
ogp_image = '_static/og-image.png'
270+
ogp_custom_meta_tags = [
271+
'<meta property="og:image:width" content="200">',
272+
'<meta property="og:image:height" content="200">',
273+
'<meta name="theme-color" content="#3776ab">',
274+
]

‎Doc/howto/enum.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ And a function to display the chores for a given day::
158158
... for chore, days in chores.items():
159159
... if day in days:
160160
... print(chore)
161+
...
161162
>>> show_chores(chores_for_ethan, Weekday.SATURDAY)
162163
answer SO questions
163164

@@ -459,6 +460,31 @@ sense to allow sharing some common behavior between a group of enumerations.
459460
(See `OrderedEnum`_ for an example.)
460461

461462

463+
.. _enum-dataclass-support:
464+
465+
Dataclass support
466+
-----------------
467+
468+
When inheriting from a :class:`~dataclasses.dataclass`,
469+
the :meth:`~Enum.__repr__` omits the inherited class' name. For example::
470+
471+
>>> @dataclass
472+
... class CreatureDataMixin:
473+
... size: str
474+
... legs: int
475+
... tail: bool = field(repr=False, default=True)
476+
...
477+
>>> class Creature(CreatureDataMixin, Enum):
478+
... BEETLE = 'small', 6
479+
... DOG = 'medium', 4
480+
...
481+
>>> Creature.DOG
482+
<Creature.DOG: size='medium', legs=4>
483+
484+
Use the :func:`!dataclass` argument ``repr=False``
485+
to use the standard :func:`repr`.
486+
487+
462488
Pickling
463489
--------
464490

@@ -687,6 +713,7 @@ It is also possible to name the combinations::
687713
... W = 2
688714
... X = 1
689715
... RWX = 7
716+
...
690717
>>> Perm.RWX
691718
<Perm.RWX: 7>
692719
>>> ~Perm.RWX

‎Doc/includes/typestruct.h‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,4 +80,7 @@ typedef struct _typeobject {
8080

8181
destructor tp_finalize;
8282
vectorcallfunc tp_vectorcall;
83+
84+
/* bitset of which type-watchers care about this type */
85+
char tp_watched;
8386
} PyTypeObject;

‎Doc/library/argparse.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -565,6 +565,7 @@ arguments they contain. For example::
565565

566566
>>> with open('args.txt', 'w', encoding=sys.getfilesystemencoding()) as fp:
567567
... fp.write('-f\nbar')
568+
...
568569
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
569570
>>> parser.add_argument('-f')
570571
>>> parser.parse_args(['-f', 'foo', '@args.txt'])

0 commit comments

Comments
 (0)