From c478caa5cd00e68dc8b68111b98ee4422d904df1 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 21 Sep 2023 22:03:44 +0800 Subject: [PATCH 1/4] Add missing docs and costs in msvcrt --- Doc/library/msvcrt.rst | 115 ++++++++++++++++++++++++++++++++++++----- PC/msvcrtmodule.c | 4 ++ 2 files changed, 106 insertions(+), 13 deletions(-) diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index a24c037678de0c..54a2e55728b682 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -10,8 +10,8 @@ -------------- These functions provide access to some useful capabilities on Windows platforms. -Some higher-level modules use these functions to build the Windows -implementations of their services. For example, the :mod:`getpass` module uses +Some higher-level modules use these functions to build the Windows +implementations of their services. For example, the :mod:`getpass` module uses this in the implementation of the :func:`getpass` function. Further documentation on these functions can be found in the Platform API @@ -35,11 +35,11 @@ File Operations .. function:: locking(fd, mode, nbytes) - Lock part of a file based on file descriptor *fd* from the C runtime. Raises - :exc:`OSError` on failure. The locked region of the file extends from the + Lock part of a file based on file descriptor *fd* from the C runtime. Raises + :exc:`OSError` on failure. The locked region of the file extends from the current file position for *nbytes* bytes, and may continue beyond the end of the - file. *mode* must be one of the :const:`!LK_\*` constants listed below. Multiple - regions in a file may be locked at the same time, but may not overlap. Adjacent + file. *mode* must be one of the :const:`!LK_\*` constants listed below. Multiple + regions in a file may be locked at the same time, but may not overlap. Adjacent regions are not merged; they must be unlocked individually. .. audit-event:: msvcrt.locking fd,mode,nbytes msvcrt.locking @@ -49,7 +49,7 @@ File Operations LK_RLCK Locks the specified bytes. If the bytes cannot be locked, the program - immediately tries again after 1 second. If, after 10 attempts, the bytes cannot + immediately tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, :exc:`OSError` is raised. @@ -74,9 +74,9 @@ File Operations .. function:: open_osfhandle(handle, flags) - Create a C runtime file descriptor from the file handle *handle*. The *flags* + Create a C runtime file descriptor from the file handle *handle*. The *flags* parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, - and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter + and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter to :func:`os.fdopen` to create a file object. .. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle @@ -84,7 +84,7 @@ File Operations .. function:: get_osfhandle(fd) - Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if + Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if *fd* is not recognized. .. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle @@ -105,7 +105,7 @@ Console I/O .. function:: getch() Read a keypress and return the resulting character as a byte string. - Nothing is echoed to the console. This call will block if a keypress + Nothing is echoed to the console. This call will block if a keypress is not already available, but will not wait for :kbd:`Enter` to be pressed. If the pressed key was a special function key, this will return ``'\000'`` or ``'\xe0'``; the next call will return the keycode. @@ -119,7 +119,7 @@ Console I/O .. function:: getche() - Similar to :func:`getch`, but the keypress will be echoed if it represents a + Similar to :func:`getch`, but the keypress will be echoed if it represents a printable character. @@ -158,4 +158,93 @@ Other Functions .. function:: heapmin() Force the :c:func:`malloc` heap to clean itself up and return unused blocks to - the operating system. On failure, this raises :exc:`OSError`. + the operating system. On failure, this raises :exc:`OSError`. + + +.. function:: set_error_mode(mode) + + Changes the location where the C runtime writes an error message for an error + that might end the program. *mode* must be one of the :const:`!OUT_\*` or + :const:`REPORT_ERRMODE` constants listed below. Returns the old setting or -1 + if an error occurs. Only available in + :ref:`debug build of Python `. + + +.. data:: OUT_TO_DEFAULT + + Error sink is determined by the app's type. Only available in + :ref:`debug build of Python `. + + +.. data:: OUT_TO_STDERR + + Error sink is a standard error. Only available in + :ref:`debug build of Python `. + + +.. data:: OUT_TO_MSGBOX + + Error sink is a message box. Only available in + :ref:`debug build of Python `. + + +.. data:: REPORT_ERRMODE + + Report the current error mode value. Only available in + :ref:`debug build of Python `. + + +.. function:: CrtSetReportMode(type, mode) + + Specifies the destination or destinations for a specific report type + generated by ``_CrtDbgReport`` in the MS VC++ runtime. *type* must be one of + the :const:`!CRT_\*` constants listed below. *mode* must be one of the + :const:`!CRTDBG_\*` constants listed below. Only available in + :ref:`debug build of Python `. + + +.. function:: CrtSetReportFile(type, file) + + After you use :func:`CrtSetReportMode` to specify :const:`CRTDBG_MODE_FILE`, + you can specify the file handle to receive the message text. *type* must be + one of the :const:`!CRT_\*` constants listed below. *file* shuld be the file + handle your want specified. Only available in + :ref:`debug build of Python `. + + +.. data:: CRT_WARN + + Warnings, messages, and information that doesn't need immediate attention. + + +.. data:: CRT_ERROR + + Errors, unrecoverable problems, and issues that require immediate attention. + + +.. data:: CRT_ASSERT + + Assertion failures. + + +.. data:: CRTDBG_MODE_DEBUG + + Writes the message to the debugger's output window. + + +.. data:: CRTDBG_MODE_FILE + + Writes the message to a user-supplied file handle. :func:`CrtSetReportFile` + should be called to define the specific file or stream to use as + the destination. + + +.. data:: CRTDBG_MODE_WNDW + + Creates a message box to display the message along with the ``Abort``, + ``Retry``, and ``Ignore`` buttons. + + +.. data:: CRTDBG_REPORT_MODE + + Returns current **mode** for the specified **type**. diff --git a/PC/msvcrtmodule.c b/PC/msvcrtmodule.c index 9a3462141bffbf..5ff703217b421f 100644 --- a/PC/msvcrtmodule.c +++ b/PC/msvcrtmodule.c @@ -615,6 +615,10 @@ exec_module(PyObject* m) INSERTPTR(m, "CRTDBG_FILE_STDERR", _CRTDBG_FILE_STDERR); INSERTPTR(m, "CRTDBG_FILE_STDOUT", _CRTDBG_FILE_STDOUT); INSERTPTR(m, "CRTDBG_REPORT_FILE", _CRTDBG_REPORT_FILE); + INSERTINT(m, "OUT_TO_DEFAULT", _OUT_TO_DEFAULT); + INSERTINT(m, "OUT_TO_STDERR", _OUT_TO_STDERR); + INSERTINT(m, "OUT_TO_MSGBOX", _OUT_TO_MSGBOX); + INSERTINT(m, "REPORT_ERRMODE", _REPORT_ERRMODE); #endif #undef INSERTINT From affbe6b3756297eca76cb4cb8d7a4abc4de17672 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Thu, 21 Sep 2023 14:26:49 +0000 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Library/2023-09-21-14-26-44.gh-issue-74481.KAUDcD.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Library/2023-09-21-14-26-44.gh-issue-74481.KAUDcD.rst diff --git a/Misc/NEWS.d/next/Library/2023-09-21-14-26-44.gh-issue-74481.KAUDcD.rst b/Misc/NEWS.d/next/Library/2023-09-21-14-26-44.gh-issue-74481.KAUDcD.rst new file mode 100644 index 00000000000000..c2aca4eae64eda --- /dev/null +++ b/Misc/NEWS.d/next/Library/2023-09-21-14-26-44.gh-issue-74481.KAUDcD.rst @@ -0,0 +1 @@ +Add ``set_error_mode`` related constants in ``msvcrt`` module in Python debug build. From 33ed350509878f0d382764b0d6f5896d7ad8822c Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 21 Sep 2023 22:33:28 +0800 Subject: [PATCH 3/4] a few improves for the rst format --- Doc/library/msvcrt.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 54a2e55728b682..14b2dce31e4516 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -164,9 +164,9 @@ Other Functions .. function:: set_error_mode(mode) Changes the location where the C runtime writes an error message for an error - that might end the program. *mode* must be one of the :const:`!OUT_\*` or - :const:`REPORT_ERRMODE` constants listed below. Returns the old setting or -1 - if an error occurs. Only available in + that might end the program. *mode* must be one of the :const:`!OUT_\*` + constants listed below or :const:`REPORT_ERRMODE`. Returns the old setting + or -1 if an error occurs. Only available in :ref:`debug build of Python `. @@ -197,8 +197,8 @@ Other Functions .. function:: CrtSetReportMode(type, mode) Specifies the destination or destinations for a specific report type - generated by ``_CrtDbgReport`` in the MS VC++ runtime. *type* must be one of - the :const:`!CRT_\*` constants listed below. *mode* must be one of the + generated by :c:func:`_CrtDbgReport` in the MS VC++ runtime. *type* must be + one of the :const:`!CRT_\*` constants listed below. *mode* must be one of the :const:`!CRTDBG_\*` constants listed below. Only available in :ref:`debug build of Python `. @@ -247,4 +247,4 @@ Other Functions .. data:: CRTDBG_REPORT_MODE - Returns current **mode** for the specified **type**. + Returns current *mode* for the specified *type*. From 766f877c5a1be014076cb9aefc8d395b66ce7128 Mon Sep 17 00:00:00 2001 From: AN Long Date: Thu, 21 Sep 2023 22:45:41 +0800 Subject: [PATCH 4/4] fix missing ref in doc --- Doc/library/msvcrt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 14b2dce31e4516..0b059e746c61af 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -197,7 +197,7 @@ Other Functions .. function:: CrtSetReportMode(type, mode) Specifies the destination or destinations for a specific report type - generated by :c:func:`_CrtDbgReport` in the MS VC++ runtime. *type* must be + generated by :c:func:`!_CrtDbgReport` in the MS VC++ runtime. *type* must be one of the :const:`!CRT_\*` constants listed below. *mode* must be one of the :const:`!CRTDBG_\*` constants listed below. Only available in :ref:`debug build of Python `.