Add option ConsoleSupportLevel (#1730)

Author: BCSharp

Documentation/upgrading-from-ipy2.md

@@ -31,6 +31,55 @@ System.StringSplitOptions["None"]
 
 Similarly, `True` and `False` are also keywords in Python 3.
 
+## Redirecting output
+
+With IronPython 2, standard output was written to the runtime's `SharedIO.OutputWriter` (which was `Console.Out` by default). This is no longer the case with IronPython 3 where the standard output is a binary stream. The output is now written to runtime's `SharedIO.OutputStream`. Similarly, standard input and error are now using `SharedIO.InputStream` and `SharedIO.ErrorStream` respectively.
+
+Because of this, using a `TextWriter` to capture output will no longer work. As a workaround, in order to use a `TextWriter` as the main method of redirection, one could wrap the writer inside a stream (for example, see [`TextStream`][TextStream]).
+
+```c#
+// IronPython 2
+var engine = Python.CreateEngine();
+var textWriter = new MyTextWriter();
+// no longer works in IronPython 3!
+engine.Runtime.IO.RedirectToConsole();
+Console.SetOut(textWriter);
+```
+
+```c#
+// IronPython 3
+var engine = Python.CreateEngine();
+var textWriter = new MyTextWriter();
+engine.Runtime.IO.SetOutput(new TextStream(textWriter), textWriter);
+```
+
+Another way of achieving the redirection behavior similar to IronPython 2 is to set engine option `ConsoleSupportLevel` to `SupportLevel.Basic`. IronPython 3 still uses binary streams for standard input and output but **all three** standard streams are set to use `TextStream`, forwarding to the corresponding writers/reader.
+
+```c#
+// IronPython 3
+var engine = Python.CreateEngine(new Dictionary<string, object> { 
+    { "ConsoleSupportLevel", Microsoft.Scripting.Runtime.SharedIO.SupportLevel.Basic },
+});
+var textWriter = new MyTextWriter();
+// works again!
+engine.Runtime.IO.RedirectToConsole();
+Console.SetOut(textWriter);
+```
+
+This method is particularly useful when embedding the IronPython 3 engine in a host that sets console's writers/reader before the engine is created and the host's code is not accessible to the user (for instance, scripting in [LINQPad]).
+
+```c#
+// IronPython 3 in LINQPad
+var engine = Python.CreateEngine(new Dictionary<string, object> { 
+    { "ConsoleSupportLevel", Microsoft.Scripting.Runtime.SharedIO.SupportLevel.Basic },
+});
+engine.Execute("print('abc')"); // shows output in the "Results" pane
+dynamic ans = engine.Execute("input()"); // pauses the script and asks for input at the bottom of the "Results" pane; terminate your input with Ctrl+Z, Enter
+```
+
+[TextStream]: https://github.com/IronLanguages/dlr/blob/master/Src/Microsoft.Scripting/Utils/TextStream.cs
+[LINQPad]: https://www.linqpad.net/
+
 ## `int` Type
 
 One of the major backward incompatible changes in Python 3 is [PEP 237 – Unifying Long Integers and Integers][PEP 0237]: Essentially, `long` renamed to `int`. That is, there is only one built-in integral type, named `int`; but it behaves mostly like the old `long` type. From the pure Python perspective this means that `int` should be used wherever previously `long` was used. More consideration has to be applied in interop cases with .NET.
@@ -206,27 +255,3 @@ IronPython's `range` is a generator that produces a sequence of `int` values. Th
 
 [PEP 0237]: https://python.org/dev/peps/pep-0237
 
-
-## Redirecting output
-
-With IronPython 2, standard output was written to the runtime's `SharedIO.OutputWriter` (which was `Console.Out` by default). This is no longer the case with IronPython 3 where the standard output is a binary stream. The output is now written to runtime's `SharedIO.OutputStream`. Similarly, standard input and error are now using `SharedIO.InputStream` and `SharedIO.ErrorStream` respectively.
-
-Because of this, using a `TextWriter` to capture output will no longer work. As a workaround, in order to use a `TextWriter` as the main method of redirection, one could wrap the writer inside a stream (for example, see [TextStream][TextStream]).
-
-IronPython 2
-```c#
-var engine = Python.CreateEngine();
-var textWriter = new MyTextWriter();
-// no longer works!
-engine.Runtime.IO.RedirectToConsole();
-Console.SetOut(textWriter);
-```
-
-IronPython 3
-```c#
-var engine = Python.CreateEngine();
-var textWriter = new MyTextWriter();
-engine.Runtime.IO.SetOutput(new TextStream(textWriter), textWriter);
-```
-
-[TextStream]: https://github.com/IronLanguages/main/blob/master/Runtime/Microsoft.Dynamic/Utils/TextStream.cs

Src/DLR

@@ -1866,6 +1866,7 @@ internal void DelSystemStateValue(string name) {
 
         private void SetStandardIO() {
             SharedIO io = DomainManager.SharedIO;
+            io.ConsoleSupportLevel = PythonOptions.ConsoleSupportLevel;
 
             var stdin = PythonIOModule.CreateConsole(this, io, ConsoleStreamType.Input, "<stdin>", out PythonIOModule.FileIO fstdin);
             var stdout = PythonIOModule.CreateConsole(this, io, ConsoleStreamType.Output, "<stdout>", out PythonIOModule.FileIO fstdout);

Src/IronPython/Runtime/PythonContext.cs

@@ -5,9 +5,11 @@
 using System;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
+using System.Globalization;
 using System.Text.RegularExpressions;
 
 using Microsoft.Scripting;
+using Microsoft.Scripting.Runtime;
 
 namespace IronPython.Runtime {
 
@@ -125,6 +127,11 @@ public sealed class PythonOptions : LanguageOptions {
 
         public bool Quiet { get; }
 
+        /// <summary>
+        /// On Basic level, console IO streams are emulated using console writer/reader.
+        /// </summary>
+        public SharedIO.SupportLevel ConsoleSupportLevel { get; }
+
         internal bool NoImportLib { get; } // TODO: get rid of me when we no longer bootstrap importlib
 
         public PythonOptions() 
@@ -158,6 +165,7 @@ public PythonOptions(IDictionary<string, object> options)
             NoImportLib = GetOption(options, "NoImportLib", false);
             Isolated = GetOption(options, "Isolated", false);
             Utf8Mode = GetOption(options, "Utf8Mode", false);
+            ConsoleSupportLevel = GetOption(options, "ConsoleSupportLevel", SharedIO.SupportLevel.Full);
         }
 
         private static IDictionary<string, object> EnsureSearchPaths(IDictionary<string, object> options) {