gh-86184: Update document for SetValue and QueryValue in winreg

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 <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 <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       |
+   |       | <value-types>`).                        |
    +-------+-----------------------------------------+
 
    .. audit-event:: winreg.QueryValue key,sub_key,value_name winreg.QueryValueEx
@@ -488,7 +491,8 @@ This module offers the following functions:
    *type* is an integer that specifies the type of the data. See
    :ref:`Value Types <value-types>` for the available types.
 
-   *value* is a string that specifies the new value.
+   *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
@@ -691,64 +695,89 @@ 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.
+   Returns a :class:`bytes` object, or ``None`` for empty values.
 
 .. data:: REG_DWORD
 
    32-bit number.
+   *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`.
+   *value* must be an :class:`int` in Python for this type.
 
 .. data:: REG_DWORD_BIG_ENDIAN
 
    A 32-bit number in big-endian format.
+   *value* must be an :class:`int` in Python for this type.
 
 .. data:: REG_EXPAND_SZ
 
    Null-terminated string containing references to environment
    variables (``%PATH%``).
+   *value* must be a :class:`str` in Python for this type.
 
 .. data:: REG_LINK
 
    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
 
    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
 
    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
 
    A 64-bit number.
+   *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`.
+   *value* must be an :class:`int` in Python for this type.
 
    .. versionadded:: 3.6
 
 .. data:: REG_RESOURCE_LIST
 
    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 ``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.).
 
 
 .. _handle-object:

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;
@@ -1824,7 +1825,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.
@@ -1843,7 +1845,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;