Sync with CPython 3.12 (#951)

Co-authored-by: Matt Wang <[email protected]>

Author: pydoc-zh-tw[bot]

.scripts/poetry.lock

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-07-20 00:03+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2022-10-16 03:21+0800\n"
 "Last-Translator: Adrian Liaw <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -612,6 +612,10 @@ msgid ""
 "*converter* function in turn is called as follows::"
 msgstr ""
 
+#: ../../c-api/arg.rst:316
+msgid "status = converter(object, address);"
+msgstr "status = converter(object, address);"
+
 #: ../../c-api/arg.rst:318
 msgid ""
 "where *object* is the Python object to be converted and *address* is the :c:"
@@ -828,12 +832,44 @@ msgid ""
 "the :mod:`!_weakref` helper module for weak references::"
 msgstr ""
 
+#: ../../c-api/arg.rst:477
+msgid ""
+"static PyObject *\n"
+"weakref_ref(PyObject *self, PyObject *args)\n"
+"{\n"
+"    PyObject *object;\n"
+"    PyObject *callback = NULL;\n"
+"    PyObject *result = NULL;\n"
+"\n"
+"    if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n"
+"        result = PyWeakref_NewRef(object, callback);\n"
+"    }\n"
+"    return result;\n"
+"}"
+msgstr ""
+"static PyObject *\n"
+"weakref_ref(PyObject *self, PyObject *args)\n"
+"{\n"
+"    PyObject *object;\n"
+"    PyObject *callback = NULL;\n"
+"    PyObject *result = NULL;\n"
+"\n"
+"    if (PyArg_UnpackTuple(args, \"ref\", 1, 2, &object, &callback)) {\n"
+"        result = PyWeakref_NewRef(object, callback);\n"
+"    }\n"
+"    return result;\n"
+"}"
+
 #: ../../c-api/arg.rst:490
 msgid ""
 "The call to :c:func:`PyArg_UnpackTuple` in this example is entirely "
 "equivalent to this call to :c:func:`PyArg_ParseTuple`::"
 msgstr ""
 
+#: ../../c-api/arg.rst:493
+msgid "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)"
+msgstr "PyArg_ParseTuple(args, \"O|O:ref\", &object, &callback)"
+
 #: ../../c-api/arg.rst:498
 msgid "Building values"
 msgstr ""

c-api/arg.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-05-28 00:03+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2018-05-23 14:30+0000\n"
 "Last-Translator: Adrian Liaw <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -303,7 +303,7 @@ msgstr ""
 
 #: ../../c-api/buffer.rst:218
 msgid "Constants:"
-msgstr ""
+msgstr "常數："
 
 #: ../../c-api/buffer.rst:222
 msgid ""
@@ -533,13 +533,52 @@ msgid ""
 "dimensional array as follows:"
 msgstr ""
 
+#: ../../c-api/buffer.rst:368
+msgid ""
+"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * "
+"strides[n-1];\n"
+"item = *((typeof(item) *)ptr);"
+msgstr ""
+"ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * "
+"strides[n-1];\n"
+"item = *((typeof(item) *)ptr);"
+
 #: ../../c-api/buffer.rst:374
 msgid ""
 "As noted above, :c:member:`~Py_buffer.buf` can point to any location within "
 "the actual memory block. An exporter can check the validity of a buffer with "
 "this function:"
 msgstr ""
 
+#: ../../c-api/buffer.rst:378
+msgid ""
+"def verify_structure(memlen, itemsize, ndim, shape, strides, offset):\n"
+"    \"\"\"Verify that the parameters represent a valid array within\n"
+"       the bounds of the allocated memory:\n"
+"           char *mem: start of the physical memory block\n"
+"           memlen: length of the physical memory block\n"
+"           offset: (char *)buf - mem\n"
+"    \"\"\"\n"
+"    if offset % itemsize:\n"
+"        return False\n"
+"    if offset < 0 or offset+itemsize > memlen:\n"
+"        return False\n"
+"    if any(v % itemsize for v in strides):\n"
+"        return False\n"
+"\n"
+"    if ndim <= 0:\n"
+"        return ndim == 0 and not shape and not strides\n"
+"    if 0 in shape:\n"
+"        return True\n"
+"\n"
+"    imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n"
+"               if strides[j] <= 0)\n"
+"    imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)\n"
+"               if strides[j] > 0)\n"
+"\n"
+"    return 0 <= offset+imin and offset+imax+itemsize <= memlen"
+msgstr ""
+
 #: ../../c-api/buffer.rst:408
 msgid "PIL-style: shape, strides and suboffsets"
 msgstr ""
@@ -562,6 +601,34 @@ msgid ""
 "strides and suboffsets::"
 msgstr ""
 
+#: ../../c-api/buffer.rst:423
+msgid ""
+"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n"
+"                       Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n"
+"    char *pointer = (char*)buf;\n"
+"    int i;\n"
+"    for (i = 0; i < ndim; i++) {\n"
+"        pointer += strides[i] * indices[i];\n"
+"        if (suboffsets[i] >=0 ) {\n"
+"            pointer = *((char**)pointer) + suboffsets[i];\n"
+"        }\n"
+"    }\n"
+"    return (void*)pointer;\n"
+"}"
+msgstr ""
+"void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,\n"
+"                       Py_ssize_t *suboffsets, Py_ssize_t *indices) {\n"
+"    char *pointer = (char*)buf;\n"
+"    int i;\n"
+"    for (i = 0; i < ndim; i++) {\n"
+"        pointer += strides[i] * indices[i];\n"
+"        if (suboffsets[i] >=0 ) {\n"
+"            pointer = *((char**)pointer) + suboffsets[i];\n"
+"        }\n"
+"    }\n"
+"    return (void*)pointer;\n"
+"}"
+
 #: ../../c-api/buffer.rst:438
 msgid "Buffer-related functions"
 msgstr ""

c-api/buffer.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-04-18 00:04+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2022-10-16 03:20+0800\n"
 "Last-Translator: Matt Wang <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -41,6 +41,12 @@ msgstr ""
 "設定 :c:member:`~PyTypeObject.tp_call` 的類別之實例都是可呼叫的。該擴充槽 "
 "(slot) 的簽章為： ::"
 
+#: ../../c-api/call.rst:17
+msgid ""
+"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);"
+msgstr ""
+"PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);"
+
 #: ../../c-api/call.rst:19
 msgid ""
 "A call is made using a tuple for the positional arguments and a dict for the "
@@ -273,6 +279,10 @@ msgid ""
 "Currently equivalent to::"
 msgstr "給定一個 vectorcall *nargsf* 引數，回傳引數的實際數量。目前等同於： ::"
 
+#: ../../c-api/call.rst:153
+msgid "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)"
+msgstr "(Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET)"
+
 #: ../../c-api/call.rst:155
 msgid ""
 "However, the function ``PyVectorcall_NARGS`` should be used to allow for "

c-api/call.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-07-29 00:03+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2018-05-23 14:30+0000\n"
 "Last-Translator: Adrian Liaw <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -41,6 +41,10 @@ msgstr ""
 msgid "The type of a destructor callback for a capsule.  Defined as::"
 msgstr ""
 
+#: ../../c-api/capsule.rst:29
+msgid "typedef void (*PyCapsule_Destructor)(PyObject *);"
+msgstr "typedef void (*PyCapsule_Destructor)(PyObject *);"
+
 #: ../../c-api/capsule.rst:31
 msgid ""
 "See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor "

c-api/capsule.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-07-18 00:03+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2015-12-09 17:51+0000\n"
 "Last-Translator: Matt Wang <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -61,6 +61,18 @@ msgstr ""
 msgid "The structure is defined as::"
 msgstr "該結構被定義為： ::"
 
+#: ../../c-api/complex.rst:35
+msgid ""
+"typedef struct {\n"
+"    double real;\n"
+"    double imag;\n"
+"} Py_complex;"
+msgstr ""
+"typedef struct {\n"
+"    double real;\n"
+"    double imag;\n"
+"} Py_complex;"
+
 #: ../../c-api/complex.rst:43
 msgid ""
 "Return the sum of two complex numbers, using the C :c:type:`Py_complex` "

c-api/complex.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-03-07 17:26+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2018-07-15 18:56+0800\n"
 "Last-Translator: \n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -26,6 +26,15 @@ msgid ""
 "`PyContext`, :c:type:`PyContextVar`, and :c:type:`PyContextToken`, e.g.::"
 msgstr ""
 
+#: ../../c-api/contextvars.rst:20
+msgid ""
+"// in 3.7.0:\n"
+"PyContext *PyContext_New(void);\n"
+"\n"
+"// in 3.7.1+:\n"
+"PyObject *PyContext_New(void);"
+msgstr ""
+
 #: ../../c-api/contextvars.rst:26
 msgid "See :issue:`34762` for more details."
 msgstr "更多細節請見 :issue:`34762`。"

c-api/contextvars.po

@@ -355,15 +355,15 @@ msgstr "為了方便模組實作 DB API 的巨集："
 #: ../../c-api/datetime.rst:320
 msgid ""
 "Create and return a new :class:`datetime.datetime` object given an argument "
-"tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`."
+"tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`."
 msgstr ""
-"給定一個適合傳遞給 :meth:`datetime.datetime.fromtimestamp()` 的引數元組，建立"
-"並回傳一個新的 :class:`datetime.datetime` 物件。"
+"給定一個適合傳遞給 :meth:`datetime.datetime.fromtimestamp` 的引數元組，建立並"
+"回傳一個新的 :class:`datetime.datetime` 物件。"
 
 #: ../../c-api/datetime.rst:326
 msgid ""
 "Create and return a new :class:`datetime.date` object given an argument "
-"tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`."
+"tuple suitable for passing to :meth:`datetime.date.fromtimestamp`."
 msgstr ""
-"給定一個適合傳遞給 :meth:`datetime.date.fromtimestamp()` 的引數元組，建立並回"
-"傳一個新的 :class:`datetime.date` 物件。"
+"給定一個適合傳遞給 :meth:`datetime.date.fromtimestamp` 的引數元組，建立並回傳"
+"一個新的 :class:`datetime.date` 物件。"

c-api/datetime.po

@@ -9,7 +9,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-09-03 00:03+0000\n"
+"POT-Creation-Date: 2024-09-01 22:24+0800\n"
 "PO-Revision-Date: 2017-09-22 18:26+0000\n"
 "Last-Translator: Liang-Bo Wang <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -200,13 +200,62 @@ msgstr ""
 msgid "For example::"
 msgstr "舉例來說： ::"
 
+#: ../../c-api/dict.rst:181
+msgid ""
+"PyObject *key, *value;\n"
+"Py_ssize_t pos = 0;\n"
+"\n"
+"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n"
+"    /* do something interesting with the values... */\n"
+"    ...\n"
+"}"
+msgstr ""
+
 #: ../../c-api/dict.rst:189
 msgid ""
 "The dictionary *p* should not be mutated during iteration.  It is safe to "
 "modify the values of the keys as you iterate over the dictionary, but only "
 "so long as the set of keys does not change.  For example::"
 msgstr ""
 
+#: ../../c-api/dict.rst:193
+msgid ""
+"PyObject *key, *value;\n"
+"Py_ssize_t pos = 0;\n"
+"\n"
+"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n"
+"    long i = PyLong_AsLong(value);\n"
+"    if (i == -1 && PyErr_Occurred()) {\n"
+"        return -1;\n"
+"    }\n"
+"    PyObject *o = PyLong_FromLong(i + 1);\n"
+"    if (o == NULL)\n"
+"        return -1;\n"
+"    if (PyDict_SetItem(self->dict, key, o) < 0) {\n"
+"        Py_DECREF(o);\n"
+"        return -1;\n"
+"    }\n"
+"    Py_DECREF(o);\n"
+"}"
+msgstr ""
+"PyObject *key, *value;\n"
+"Py_ssize_t pos = 0;\n"
+"\n"
+"while (PyDict_Next(self->dict, &pos, &key, &value)) {\n"
+"    long i = PyLong_AsLong(value);\n"
+"    if (i == -1 && PyErr_Occurred()) {\n"
+"        return -1;\n"
+"    }\n"
+"    PyObject *o = PyLong_FromLong(i + 1);\n"
+"    if (o == NULL)\n"
+"        return -1;\n"
+"    if (PyDict_SetItem(self->dict, key, o) < 0) {\n"
+"        Py_DECREF(o);\n"
+"        return -1;\n"
+"    }\n"
+"    Py_DECREF(o);\n"
+"}"
+
 #: ../../c-api/dict.rst:214
 msgid ""
 "Iterate over mapping object *b* adding key-value pairs to dictionary *a*. "
@@ -235,6 +284,18 @@ msgid ""
 "if an exception was raised. Equivalent Python (except for the return value)::"
 msgstr ""
 
+#: ../../c-api/dict.rst:240
+msgid ""
+"def PyDict_MergeFromSeq2(a, seq2, override):\n"
+"    for key, value in seq2:\n"
+"        if override or key not in a:\n"
+"            a[key] = value"
+msgstr ""
+"def PyDict_MergeFromSeq2(a, seq2, override):\n"
+"    for key, value in seq2:\n"
+"        if override or key not in a:\n"
+"            a[key] = value"
+
 #: ../../c-api/dict.rst:247
 msgid ""
 "Register *callback* as a dictionary watcher. Return a non-negative integer "