bpo-31884 subprocess: add Windows constants for process priority (#4150)

JamesGKent · vstinner · commit b5d9e0811463 · 2017-11-08T06:18:59.000-08:00
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
@@ -516,8 +516,20 @@ functions.
 
    If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
    passed to the underlying ``CreateProcess`` function.
-   *creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or
-   :data:`CREATE_NEW_PROCESS_GROUP`. (Windows only)
+   *creationflags*, if given, can be one or more of the following flags:
+
+      * :data:`CREATE_NEW_CONSOLE`
+      * :data:`CREATE_NEW_PROCESS_GROUP`
+      * :data:`ABOVE_NORMAL_PRIORITY_CLASS`
+      * :data:`BELOW_NORMAL_PRIORITY_CLASS`
+      * :data:`HIGH_PRIORITY_CLASS`
+      * :data:`IDLE_PRIORITY_CLASS`
+      * :data:`NORMAL_PRIORITY_CLASS`
+      * :data:`REALTIME_PRIORITY_CLASS`
+      * :data:`CREATE_NO_WINDOW`
+      * :data:`DETACHED_PROCESS`
+      * :data:`CREATE_DEFAULT_ERROR_MODE`
+      * :data:`CREATE_BREAKAWAY_FROM_JOB`
 
    Popen objects are supported as context managers via the :keyword:`with` statement:
    on exit, standard file descriptors are closed, and the process is waited for.
@@ -803,8 +815,8 @@ on Windows.
       :class:`Popen` is called with ``shell=True``.
 
 
-Constants
-^^^^^^^^^
+Windows Constants
+^^^^^^^^^^^^^^^^^
 
 The :mod:`subprocess` module exposes the following constants.
 
@@ -851,6 +863,84 @@ The :mod:`subprocess` module exposes the following constants.
 
    This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
 
+.. data:: ABOVE_NORMAL_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have an above average priority.
+
+   .. versionadded:: 3.7
+
+.. data:: BELOW_NORMAL_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have a below average priority.
+
+   .. versionadded:: 3.7
+
+.. data:: HIGH_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have a high priority.
+
+   .. versionadded:: 3.7
+
+.. data:: IDLE_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have an idle (lowest) priority.
+
+   .. versionadded:: 3.7
+
+.. data:: NORMAL_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have an normal priority. (default)
+
+   .. versionadded:: 3.7
+
+.. data:: REALTIME_PRIORITY_CLASS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will have realtime priority.
+   You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts
+   system threads that manage mouse input, keyboard input, and background disk
+   flushing. This class can be appropriate for applications that "talk" directly
+   to hardware or that perform brief tasks that should have limited interruptions.
+
+   .. versionadded:: 3.7
+
+.. data:: CREATE_NO_WINDOW
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will not create a window
+
+   .. versionadded:: 3.7
+
+.. data:: DETACHED_PROCESS
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   will not inherit its parent's console.
+   This value cannot be used with CREATE_NEW_CONSOLE.
+
+   .. versionadded:: 3.7
+
+.. data:: CREATE_DEFAULT_ERROR_MODE
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   does not inherit the error mode of the calling process. Instead, the new
+   process gets the default error mode.
+   This feature is particularly useful for multithreaded shell applications
+   that run with hard errors disabled.
+
+   .. versionadded:: 3.7
+
+.. data:: CREATE_BREAKAWAY_FROM_JOB
+
+   A :class:`Popen` ``creationflags`` parameter to specify that a new process
+   is not associated with the job.
+
+   .. versionadded:: 3.7
+
 .. _call-function-trio:
 
 Older high-level API
diff --git a/Lib/subprocess.py b/Lib/subprocess.py
@@ -164,13 +164,23 @@ def __init__(self, *, dwFlags=0, hStdInput=None, hStdOutput=None,
     from _winapi import (CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS_GROUP,
                          STD_INPUT_HANDLE, STD_OUTPUT_HANDLE,
                          STD_ERROR_HANDLE, SW_HIDE,
-                         STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW)
+                         STARTF_USESTDHANDLES, STARTF_USESHOWWINDOW,
+                         ABOVE_NORMAL_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS,
+                         HIGH_PRIORITY_CLASS, IDLE_PRIORITY_CLASS,
+                         NORMAL_PRIORITY_CLASS, REALTIME_PRIORITY_CLASS,
+                         CREATE_NO_WINDOW, DETACHED_PROCESS,
+                         CREATE_DEFAULT_ERROR_MODE, CREATE_BREAKAWAY_FROM_JOB)
 
     __all__.extend(["CREATE_NEW_CONSOLE", "CREATE_NEW_PROCESS_GROUP",
                     "STD_INPUT_HANDLE", "STD_OUTPUT_HANDLE",
                     "STD_ERROR_HANDLE", "SW_HIDE",
                     "STARTF_USESTDHANDLES", "STARTF_USESHOWWINDOW",
-                    "STARTUPINFO"])
+                    "STARTUPINFO",
+                    "ABOVE_NORMAL_PRIORITY_CLASS", "BELOW_NORMAL_PRIORITY_CLASS",
+                    "HIGH_PRIORITY_CLASS", "IDLE_PRIORITY_CLASS",
+                    "NORMAL_PRIORITY_CLASS", "REALTIME_PRIORITY_CLASS",
+                    "CREATE_NO_WINDOW", "DETACHED_PROCESS",
+                    "CREATE_DEFAULT_ERROR_MODE", "CREATE_BREAKAWAY_FROM_JOB"])
 
     class Handle(int):
         closed = False
diff --git a/Misc/NEWS.d/next/Library/2017-10-27.bpo-31884.bjhre9.rst b/Misc/NEWS.d/next/Library/2017-10-27.bpo-31884.bjhre9.rst
@@ -0,0 +1 @@
+added required constants to subprocess module for setting priotity on windows
diff --git a/Modules/_winapi.c b/Modules/_winapi.c
@@ -1595,6 +1595,18 @@ PyInit__winapi(void)
     WINAPI_CONSTANT(F_DWORD, WAIT_OBJECT_0);
     WINAPI_CONSTANT(F_DWORD, WAIT_ABANDONED_0);
     WINAPI_CONSTANT(F_DWORD, WAIT_TIMEOUT);
+    
+    WINAPI_CONSTANT(F_DWORD, ABOVE_NORMAL_PRIORITY_CLASS);
+    WINAPI_CONSTANT(F_DWORD, BELOW_NORMAL_PRIORITY_CLASS);
+    WINAPI_CONSTANT(F_DWORD, HIGH_PRIORITY_CLASS);
+    WINAPI_CONSTANT(F_DWORD, IDLE_PRIORITY_CLASS);
+    WINAPI_CONSTANT(F_DWORD, NORMAL_PRIORITY_CLASS);
+    WINAPI_CONSTANT(F_DWORD, REALTIME_PRIORITY_CLASS);
+    
+    WINAPI_CONSTANT(F_DWORD, CREATE_NO_WINDOW);
+    WINAPI_CONSTANT(F_DWORD, DETACHED_PROCESS);
+    WINAPI_CONSTANT(F_DWORD, CREATE_DEFAULT_ERROR_MODE);
+    WINAPI_CONSTANT(F_DWORD, CREATE_BREAKAWAY_FROM_JOB);
 
     WINAPI_CONSTANT("i", NULL);
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+added required constants to subprocess module for setting priotity on windows`