From 2f0d394ab3a990b9d0d139cf5c5cf0946cf069af Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 14 Nov 2025 00:52:09 +0900 Subject: [PATCH 1/6] Update document for winreg.SetValueEx --- Doc/library/winreg.rst | 17 ++++++++++++++++- PC/winreg.c | 3 ++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index b150c53735d634..f599195dfba552 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -488,7 +488,8 @@ This module offers the following functions: *type* is an integer that specifies the type of the data. See :ref:`Value Types ` for the available types. - *value* is a string that specifies the new value. + *value* is the new value to set. Accepts str, int, list of str, bytes-like object, + or None depending on the *type* parameter. This method can also set additional value and type information for the specified key. The key identified by the key parameter must have been opened with @@ -691,64 +692,78 @@ For more information, see `Registry Value Types .. data:: REG_BINARY Binary data in any form. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_DWORD 32-bit number. + You should pass an :class:`int` or :const:`None` in Python for this type. .. data:: REG_DWORD_LITTLE_ENDIAN A 32-bit number in little-endian format. Equivalent to :const:`REG_DWORD`. + You should pass an :class:`int` or :const:`None` in Python for this type. .. data:: REG_DWORD_BIG_ENDIAN A 32-bit number in big-endian format. + You should pass an :class:`int` or :const:`None` in Python for this type. .. data:: REG_EXPAND_SZ Null-terminated string containing references to environment variables (``%PATH%``). + You should pass a :class:`str` or :const:`None` in Python for this type. .. data:: REG_LINK A Unicode symbolic link. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_MULTI_SZ A sequence of null-terminated strings, terminated by two null characters. (Python handles this termination automatically.) + You should pass a :class:`list` of :class:`str` or :const:`None` in Python for this type. .. data:: REG_NONE No defined value type. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_QWORD A 64-bit number. + You should pass an :class:`int` or :const:`None` in Python for this type. .. versionadded:: 3.6 .. data:: REG_QWORD_LITTLE_ENDIAN A 64-bit number in little-endian format. Equivalent to :const:`REG_QWORD`. + You should pass an :class:`int` or :const:`None` in Python for this type. .. versionadded:: 3.6 .. data:: REG_RESOURCE_LIST A device-driver resource list. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_FULL_RESOURCE_DESCRIPTOR A hardware setting. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_RESOURCE_REQUIREMENTS_LIST A hardware resource list. + You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. .. data:: REG_SZ A null-terminated string. + You should pass a :class:`str` or :const:`None` in Python for this type. .. _handle-object: diff --git a/PC/winreg.c b/PC/winreg.c index c1be920fc1d92f..5f25782f73485a 100644 --- a/PC/winreg.c +++ b/PC/winreg.c @@ -1835,7 +1835,8 @@ winreg.SetValueEx REG_RESOURCE_LIST -- A device-driver resource list. REG_SZ -- A null-terminated string. value: object - A string that specifies the new value. + The new value to set. Accepts str, int, list of str, bytes-like object, + or None depending on the type parameter. / Stores data in the value field of an open registry key. From 20942f33301eada8c5b9371e23638a3b9bd61682 Mon Sep 17 00:00:00 2001 From: AN Long Date: Sat, 15 Nov 2025 00:50:50 +0900 Subject: [PATCH 2/6] Update by review comments --- Doc/library/winreg.rst | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index f599195dfba552..ef6a7535191690 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -692,78 +692,82 @@ For more information, see `Registry Value Types .. data:: REG_BINARY Binary data in any form. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_DWORD 32-bit number. - You should pass an :class:`int` or :const:`None` in Python for this type. + *value* must be an :class:`int` in Python for this type. .. data:: REG_DWORD_LITTLE_ENDIAN A 32-bit number in little-endian format. Equivalent to :const:`REG_DWORD`. - You should pass an :class:`int` or :const:`None` in Python for this type. + *value* must be an :class:`int` in Python for this type. .. data:: REG_DWORD_BIG_ENDIAN A 32-bit number in big-endian format. - You should pass an :class:`int` or :const:`None` in Python for this type. + *value* must be an :class:`int` in Python for this type. .. data:: REG_EXPAND_SZ Null-terminated string containing references to environment variables (``%PATH%``). - You should pass a :class:`str` or :const:`None` in Python for this type. + *value* must be a :class:`str` in Python for this type. .. data:: REG_LINK A Unicode symbolic link. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_MULTI_SZ A sequence of null-terminated strings, terminated by two null characters. (Python handles this termination automatically.) - You should pass a :class:`list` of :class:`str` or :const:`None` in Python for this type. + *value* must be a :class:`list` of :class:`str` in Python for this type. .. data:: REG_NONE No defined value type. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_QWORD A 64-bit number. - You should pass an :class:`int` or :const:`None` in Python for this type. + *value* must be an :class:`int` in Python for this type. .. versionadded:: 3.6 .. data:: REG_QWORD_LITTLE_ENDIAN A 64-bit number in little-endian format. Equivalent to :const:`REG_QWORD`. - You should pass an :class:`int` or :const:`None` in Python for this type. + *value* must be an :class:`int` in Python for this type. .. versionadded:: 3.6 .. data:: REG_RESOURCE_LIST A device-driver resource list. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_FULL_RESOURCE_DESCRIPTOR A hardware setting. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_RESOURCE_REQUIREMENTS_LIST A hardware resource list. - You should pass a :term:`bytes-like object` or :const:`None` in Python for this type. + *value* must be a :term:`bytes-like object` in Python for this type. .. data:: REG_SZ A null-terminated string. - You should pass a :class:`str` or :const:`None` in Python for this type. + *value* must be a :class:`str` in Python for this type. + +Note that :const:`None` is also accepted for these types. when :const:`None` +is passed, it is converted to the corresponding zero or empty value for the type +(0 for integers, empty string for strings, empty list for multi-strings, etc.). .. _handle-object: From 5a804d73e472e0e45a81b47229089cc0bcc28f0a Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 16 Nov 2025 17:38:29 +0900 Subject: [PATCH 3/6] Update generated codes --- PC/clinic/winreg.c.h | 5 +++-- PC/winreg.c | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/PC/clinic/winreg.c.h b/PC/clinic/winreg.c.h index d76a8d8aef8cb8..95b7c40543c1ee 100644 --- a/PC/clinic/winreg.c.h +++ b/PC/clinic/winreg.c.h @@ -1489,7 +1489,8 @@ PyDoc_STRVAR(winreg_SetValueEx__doc__, " REG_RESOURCE_LIST -- A device-driver resource list.\n" " REG_SZ -- A null-terminated string.\n" " value\n" -" A string that specifies the new value.\n" +" The new value to set. Accepts str, int, list of str, bytes-like object,\n" +" or None depending on the type parameter.\n" "\n" "This method can also set additional value and type information for the\n" "specified key. The key identified by the key parameter must have been\n" @@ -1842,4 +1843,4 @@ winreg_QueryReflectionKey(PyObject *module, PyObject *arg) #ifndef WINREG_QUERYREFLECTIONKEY_METHODDEF #define WINREG_QUERYREFLECTIONKEY_METHODDEF #endif /* !defined(WINREG_QUERYREFLECTIONKEY_METHODDEF) */ -/*[clinic end generated code: output=ce7e8e38884851fb input=a9049054013a1b77]*/ +/*[clinic end generated code: output=f18c13666adff557 input=a9049054013a1b77]*/ diff --git a/PC/winreg.c b/PC/winreg.c index 5f25782f73485a..b3194c68abfc2a 100644 --- a/PC/winreg.c +++ b/PC/winreg.c @@ -1855,7 +1855,7 @@ the configuration registry to help the registry perform efficiently. static PyObject * winreg_SetValueEx_impl(PyObject *module, HKEY key, const wchar_t *value_name, PyObject *reserved, DWORD type, PyObject *value) -/*[clinic end generated code: output=295db04deb456d9e input=900a9e3990bfb196]*/ +/*[clinic end generated code: output=295db04deb456d9e input=2dd9471b4aff5b84]*/ { LONG rc; BYTE *data = NULL; From 8273644617b2750621e2a69e7d17917a73339395 Mon Sep 17 00:00:00 2001 From: AN Long Date: Sun, 23 Nov 2025 23:18:45 +0900 Subject: [PATCH 4/6] Update by review comments --- Doc/library/winreg.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index ef6a7535191690..1ccd85f9aba755 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -488,8 +488,8 @@ This module offers the following functions: *type* is an integer that specifies the type of the data. See :ref:`Value Types ` for the available types. - *value* is the new value to set. Accepts str, int, list of str, bytes-like object, - or None depending on the *type* parameter. + *value* is the new value to set. The acceptable types depend on the *type* + parameter. This method can also set additional value and type information for the specified key. The key identified by the key parameter must have been opened with @@ -692,7 +692,8 @@ For more information, see `Registry Value Types .. data:: REG_BINARY Binary data in any form. - *value* must be a :term:`bytes-like object` in Python for this type. + *value* must be a :term:`bytes-like object` for this type. + Returns a :class:`bytes` object, or :const:`None` for empty values. .. data:: REG_DWORD @@ -725,6 +726,7 @@ For more information, see `Registry Value Types A sequence of null-terminated strings, terminated by two null characters. (Python handles this termination automatically.) *value* must be a :class:`list` of :class:`str` in Python for this type. + Returns a :class:`list` of :class:`str`, or an empty list for empty values. .. data:: REG_NONE From 7b80e4b64e871d4eeb239d72cbb0f7c3b3de50b8 Mon Sep 17 00:00:00 2001 From: AN Long Date: Wed, 24 Dec 2025 01:39:43 +0900 Subject: [PATCH 5/6] Update by review comment --- Doc/library/winreg.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index 7a4c7c678823ed..3b106b533aa0c8 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -692,8 +692,8 @@ For more information, see `Registry Value Types .. data:: REG_BINARY Binary data in any form. - *value* must be a :term:`bytes-like object` for this type. - Returns a :class:`bytes` object, or :const:`None` for empty values. + *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_DWORD @@ -720,6 +720,7 @@ For more information, see `Registry Value Types A Unicode symbolic link. *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_MULTI_SZ @@ -732,6 +733,7 @@ For more information, see `Registry Value Types No defined value type. *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_QWORD @@ -751,23 +753,26 @@ For more information, see `Registry Value Types A device-driver resource list. *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_FULL_RESOURCE_DESCRIPTOR A hardware setting. *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_RESOURCE_REQUIREMENTS_LIST A hardware resource list. *value* must be a :term:`bytes-like object` in Python for this type. + Returns a :class:`bytes` object, or ``None`` for empty values. .. data:: REG_SZ A null-terminated string. *value* must be a :class:`str` in Python for this type. -Note that :const:`None` is also accepted for these types. when :const:`None` +Note that ``None`` is also accepted for these types. When ``None`` is passed, it is converted to the corresponding zero or empty value for the type (0 for integers, empty string for strings, empty list for multi-strings, etc.). From 3b7ef7c95daaa55b8d430f456c9f6cae1651f203 Mon Sep 17 00:00:00 2001 From: AN Long Date: Fri, 26 Dec 2025 01:38:22 +0900 Subject: [PATCH 6/6] Update document for QueryValue and QueryValueEx --- Doc/library/winreg.rst | 15 +++++++++------ PC/clinic/winreg.c.h | 11 ++++++----- PC/winreg.c | 13 +++++++------ 3 files changed, 22 insertions(+), 17 deletions(-) diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index 3b106b533aa0c8..148317a73b74b6 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -378,7 +378,8 @@ This module offers the following functions: .. function:: QueryValue(key, sub_key) - Retrieves the unnamed value for a key, as a string. + Retrieves the unnamed value for a key. This function only works with + :const:`REG_SZ` type values and always returns a :class:`str`. *key* is an already open key, or one of the predefined :ref:`HKEY_* constants `. @@ -389,8 +390,8 @@ This module offers the following functions: Values in the registry have name, type, and data components. This method retrieves the data for a key's first value that has a ``NULL`` name. But the - underlying API call doesn't return the type, so always use - :func:`QueryValueEx` if possible. + underlying API call doesn't return the type and only supports :const:`REG_SZ`, + so always use :func:`QueryValueEx` if possible. .. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValue @@ -410,11 +411,13 @@ This module offers the following functions: +-------+-----------------------------------------+ | Index | Meaning | +=======+=========================================+ - | ``0`` | The value of the registry item. | + | ``0`` | The value of the registry item. The | + | | type depends on the registry type (see | + | | :ref:`Value Types `). | +-------+-----------------------------------------+ | ``1`` | An integer giving the registry type for | - | | this value (see table in docs for | - | | :meth:`SetValueEx`) | + | | this value (see :ref:`Value Types | + | | `). | +-------+-----------------------------------------+ .. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValueEx diff --git a/PC/clinic/winreg.c.h b/PC/clinic/winreg.c.h index fb2a232b65edf5..7183d83ecfbb43 100644 --- a/PC/clinic/winreg.c.h +++ b/PC/clinic/winreg.c.h @@ -1199,9 +1199,9 @@ PyDoc_STRVAR(winreg_QueryValue__doc__, "\n" "Values in the registry have name, type, and data components. This method\n" "retrieves the data for a key\'s first value that has a NULL name.\n" -"But since the underlying API call doesn\'t return the type, you\'ll\n" -"probably be happier using QueryValueEx; this function is just here for\n" -"completeness."); +"But since the underlying API call doesn\'t return the type and only\n" +"supports REG_SZ, you\'ll probably be happier using QueryValueEx; this\n" +"function is just here for completeness."); #define WINREG_QUERYVALUE_METHODDEF \ {"QueryValue", _PyCFunction_CAST(winreg_QueryValue), METH_FASTCALL, winreg_QueryValue__doc__}, @@ -1262,7 +1262,8 @@ PyDoc_STRVAR(winreg_QueryValueEx__doc__, "Behaves mostly like QueryValue(), but also returns the type of the\n" "specified value name associated with the given open registry key.\n" "\n" -"The return value is a tuple of the value and the type_id."); +"The return value is a tuple of (value, type), where type is an integer\n" +"identifying the registry type (e.g., winreg.REG_SZ, winreg.REG_DWORD)."); #define WINREG_QUERYVALUEEX_METHODDEF \ {"QueryValueEx", _PyCFunction_CAST(winreg_QueryValueEx), METH_FASTCALL, winreg_QueryValueEx__doc__}, @@ -1837,4 +1838,4 @@ winreg_QueryReflectionKey(PyObject *module, PyObject *arg) #ifndef WINREG_QUERYREFLECTIONKEY_METHODDEF #define WINREG_QUERYREFLECTIONKEY_METHODDEF #endif /* !defined(WINREG_QUERYREFLECTIONKEY_METHODDEF) */ -/*[clinic end generated code: output=4f78646e9b48780e input=a9049054013a1b77]*/ +/*[clinic end generated code: output=7acf1902c8754e9b input=a9049054013a1b77]*/ diff --git a/PC/winreg.c b/PC/winreg.c index 58c32282d11be6..b7c2ee8a614685 100644 --- a/PC/winreg.c +++ b/PC/winreg.c @@ -1488,14 +1488,14 @@ Retrieves the unnamed value for a key. Values in the registry have name, type, and data components. This method retrieves the data for a key's first value that has a NULL name. -But since the underlying API call doesn't return the type, you'll -probably be happier using QueryValueEx; this function is just here for -completeness. +But since the underlying API call doesn't return the type and only +supports REG_SZ, you'll probably be happier using QueryValueEx; this +function is just here for completeness. [clinic start generated code]*/ static PyObject * winreg_QueryValue_impl(PyObject *module, HKEY key, const wchar_t *sub_key) -/*[clinic end generated code: output=b665ce9ae391fda9 input=41cafbbf423b21d6]*/ +/*[clinic end generated code: output=b665ce9ae391fda9 input=5399c0495cade4b0]*/ { LONG rc; HKEY childKey = key; @@ -1587,12 +1587,13 @@ Retrieves the type and value of a specified sub-key. Behaves mostly like QueryValue(), but also returns the type of the specified value name associated with the given open registry key. -The return value is a tuple of the value and the type_id. +The return value is a tuple of (value, type), where type is an integer +identifying the registry type (e.g., winreg.REG_SZ, winreg.REG_DWORD). [clinic start generated code]*/ static PyObject * winreg_QueryValueEx_impl(PyObject *module, HKEY key, const wchar_t *name) -/*[clinic end generated code: output=2cdecaa44c8c333e input=cf366cada4836891]*/ +/*[clinic end generated code: output=2cdecaa44c8c333e input=131cf296d605685e]*/ { long rc; BYTE *retBuf, *tmp;