win32 console debug

Author: stephenrauch

docs/pages/building_prompts.rst

@@ -674,3 +674,79 @@ loop. Prompting the user for input is as simple as calling
 The ``patch_stdout=True`` parameter is optional, but it's recommended, because
 other coroutines could print to stdout. This option ensures that other output
 won't destroy the prompt.
+
+
+Debugging on Windows
+--------------------
+
+Debugging applications on windows under a debugger/ide can be difficult
+because the IDE may use its own 'console' which Prompt Toolkit is unable
+to use productively. In these cases it is possible to set an environment
+variable which allows Prompt Toolkit to create a console window and
+attach the appropriate handles to allow the program to use the console
+productively.
+
+Two conditions need to be present for this to work. First, the code needs
+to be imported before anything else that may use the std file handles, or
+the console, because they may cache these handles, and thus wouldn't work
+as hoped.
+
+:module:`~prompt_toolkit.shortcuts` does this import with the following:
+
+.. code:: python
+
+ if is_windows():
+ from .terminal import win32_console_debug
+ from .terminal.win32_output import Win32Output
+ from .terminal.conemu_output import ConEmuOutput
+ else:
+
+If not using :module:`~prompt_toolkit.shortcuts` this can be done with:
+
+.. code:: python
+
+ from prompt_toolkit.terminal import win32_console_debug
+
+The second condition needed is to set an environment variable::
+
+ SET USE_WIN_CONSOLE=Window Identifier
+
+or alternatively, if managing the import directly, right after the import,
+call:
+
+.. code:: python
+
+ win32_console_debug.ensure_console(title="Window Identifier")
+
+or, if it is preferred to only invoke when the application is being
+'debugged', set an environment variable::
+
+ SET USE_WIN_CONSOLE_DEBUG=Window Identifier
+
+or right after the import, call:
+
+.. code:: python
+
+ win32_console_debug.ensure_console(
+ debugger_only=True, title="Window Identifier")
+
+The console will be reused (based on the "Window Identifier" passed in)
+when restarting the application.
+
+
+Other Console Support (or starting in pre-existing terminals)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As an additional operating mode, :module:`~prompt_toolkit.shortcuts` may be
+directly executed in a terminal::
+
+ c:\> python win_console_debug.py Window Identifier
+
+When run as a script it will prep the terminal to allow it to be connected to.
+This allows other terminals to be supported by debugging with an environment
+variable of::
+
+ SET USE_EXISTING_WIN_CONSOLE=Window Identifier
+
+USE_EXISTING_WIN_CONSOLE will not create a console if a console to connect
+to does not already exist.

prompt_toolkit/shortcuts.py

@@ -63,6 +63,7 @@
  pygments_Style = None
 
 if is_windows():
+ from .terminal import win32_console_debug
  from .terminal.win32_output import Win32Output
  from .terminal.conemu_output import ConEmuOutput
 else: