convention, while *windll* libraries call functions using the ``stdcall``
calling convention. *oledll* also uses the ``stdcall`` calling convention, and
assumes the functions return a Windows :c:type:`HRESULT` error code. The error
-code is used to automatically raise a :class:`WindowsError` exception when the
+code is used to automatically raise a :class:`OSError` exception when the
function call fails.
+.. versionchanged:: 3.3
+ Windows errors used to raise :exc:`WindowsError`, which is now an alias
+ of :exc:`OSError`.
+
+
Here are some examples for Windows. Note that ``msvcrt`` is the MS standard C
library containing most standard C functions, and uses the cdecl calling
convention::
>>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in ?
- WindowsError: exception: access violation reading 0x00000020
+ OSError: exception: access violation reading 0x00000020
>>>
There are, however, enough ways to crash Python with :mod:`ctypes`, so you
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "<stdin>", line 3, in ValidHandle
- WindowsError: [Errno 126] The specified module could not be found.
+ OSError: [Errno 126] The specified module could not be found.
>>>
``WinError`` is a function which will call Windows ``FormatMessage()`` api to
assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT`
values contain information specifying whether the function call failed or
succeeded, together with additional error code. If the return value signals a
- failure, an :class:`WindowsError` is automatically raised.
+ failure, an :class:`OSError` is automatically raised.
+
+ .. versionchanged:: 3.3
+ :exc:`WindowsError` used to be raised.
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
.. function:: WinError(code=None, descr=None)
Windows only: this function is probably the worst-named thing in ctypes. It
- creates an instance of WindowsError. If *code* is not specified,
+ creates an instance of OSError. If *code* is not specified,
``GetLastError`` is called to determine the error code. If *descr* is not
specified, :func:`FormatError` is called to get a textual description of the
error.
+ .. versionchanged:: 3.3
+ An instance of :exc:`WindowsError` used to be created.
+
.. function:: wstring_at(address, size=-1)
*key* is the predefined handle to connect to.
The return value is the handle of the opened key. If the function fails, a
- :exc:`WindowsError` exception is raised.
+ :exc:`OSError` exception is raised.
+
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
.. function:: CreateKey(key, sub_key)
If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, a
- :exc:`WindowsError` exception is raised.
+ :exc:`OSError` exception is raised.
+
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
.. function:: CreateKeyEx(key, sub_key, reserved=0, access=KEY_ALL_ACCESS)
If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, a
- :exc:`WindowsError` exception is raised.
+ :exc:`OSError` exception is raised.
.. versionadded:: 3.2
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
+
.. function:: DeleteKey(key, sub_key)
*This method can not delete keys with subkeys.*
If the method succeeds, the entire key, including all of its values, is removed.
- If the method fails, a :exc:`WindowsError` exception is raised.
+ If the method fails, a :exc:`OSError` exception is raised.
+
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
.. function:: DeleteKeyEx(key, sub_key, access=KEY_ALL_ACCESS, reserved=0)
*This method can not delete keys with subkeys.*
If the method succeeds, the entire key, including all of its values, is
- removed. If the method fails, a :exc:`WindowsError` exception is raised.
+ removed. If the method fails, a :exc:`OSError` exception is raised.
On unsupported Windows versions, :exc:`NotImplementedError` is raised.
.. versionadded:: 3.2
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
+
.. function:: DeleteValue(key, value)
*index* is an integer that identifies the index of the key to retrieve.
The function retrieves the name of one subkey each time it is called. It is
- typically called repeatedly until a :exc:`WindowsError` exception is
+ typically called repeatedly until a :exc:`OSError` exception is
raised, indicating, no more values are available.
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
+
.. function:: EnumValue(key, index)
*index* is an integer that identifies the index of the value to retrieve.
The function retrieves the name of one subkey each time it is called. It is
- typically called repeatedly, until a :exc:`WindowsError` exception is
+ typically called repeatedly, until a :exc:`OSError` exception is
raised, indicating no more values.
The result is a tuple of 3 items:
| | :meth:`SetValueEx`) |
+-------+--------------------------------------------+
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
+
.. function:: ExpandEnvironmentStrings(str)
The result is a new handle to the specified key.
- If the function fails, :exc:`WindowsError` is raised.
+ If the function fails, :exc:`OSError` is raised.
.. versionchanged:: 3.2 Allow the use of named arguments.
+ .. versionchanged:: 3.3
+ This function used to raise a :exc:`WindowsError`, which is now an
+ alias of :exc:`OSError`.
+
.. function:: OpenKeyEx()