diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index 89def6e2afe088..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 @@ -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 ` 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: diff --git a/PC/clinic/winreg.c.h b/PC/clinic/winreg.c.h index 92cf6e8a9be187..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__}, @@ -1483,7 +1484,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" @@ -1836,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=97295995db2c24e9 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=7acf1902c8754e9b input=a9049054013a1b77]*/ diff --git a/PC/winreg.c b/PC/winreg.c index 26bcd259efd987..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; @@ -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;