Update jupyter core 1.3, begin adding magic command docs.

build/ci.yml

@@ -4,7 +4,7 @@ trigger:
 
 variables:
   Build.Major: 0
-  Build.Minor: 10
+  Build.Minor: 11
   Drops.Dir: $(Build.ArtifactStagingDirectory)/drops
 
 jobs:

src/Jupyter/CustomShell/ClientInfoHandler.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
 using Microsoft.Jupyter.Core;
 using Microsoft.Jupyter.Core.Protocol;
@@ -83,9 +84,11 @@ IShellServer shellServer
             this.shellServer = shellServer;
         }
 
+        /// <inheritdoc />
         public string MessageType => "iqsharp_clientinfo_request";
 
-        public void Handle(Message message)
+        /// <inheritdoc />
+        public async Task HandleAsync(Message message)
         {
             var content = message.To<ClientInfoContent>();
             metadata.UserAgent = content.UserAgent ?? metadata.UserAgent;

src/Jupyter/CustomShell/EchoHandler.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
 using Microsoft.Jupyter.Core;
 using Microsoft.Jupyter.Core.Protocol;
@@ -34,7 +35,7 @@ IShellServer shellServer
 
         public string MessageType => "iqsharp_echo_request";
 
-        public void Handle(Message message)
+        public async Task HandleAsync(Message message)
         {
             // Find out the thing we need to echo back.
             var value = (message.Content as UnknownContent).Data["value"] as string;

src/Jupyter/Extensions.cs

@@ -4,7 +4,7 @@
 using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
-using System.Text;
+using System.Text.RegularExpressions;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Jupyter.Core;
 using Microsoft.Jupyter.Core.Protocol;
@@ -169,5 +169,32 @@ public static T WithStackTraceDisplay<T>(this T simulator, IChannel channel)
             };
             return simulator;
         }
+
+        /// <summary>
+        ///      Removes common indents from each line in a string,
+        ///      similarly to Python's <c>textwrap.dedent()</c> function.
+        /// </summary>
+        internal static string Dedent(this string text)
+        {
+            // First, start by finding the length of common indents,
+            // disregarding lines that are only whitespace.
+            var leadingWhitespaceRegex = new Regex(@"^[ \t]*");
+            var minWhitespace = int.MaxValue;
+            foreach (var line in text.Split("\n"))
+            {
+                if (!string.IsNullOrWhiteSpace(line))
+                {
+                    var match = leadingWhitespaceRegex.Match(line);
+                    minWhitespace = match.Success
+                                ? System.Math.Min(minWhitespace, match.Value.Length)
+                                : minWhitespace = 0;
+                }
+            }
+
+            // We can use that to build a new regex that strips
+            // out common indenting.
+            var leftTrimRegex = new Regex(@$"^[ \t]{{{minWhitespace}}}", RegexOptions.Multiline);
+            return leftTrimRegex.Replace(text, "");
+        }
     }
 }

src/Jupyter/IQSharpEngine.cs

@@ -15,6 +15,7 @@
 using Newtonsoft.Json.Converters;
 using Microsoft.Jupyter.Core.Protocol;
 using Newtonsoft.Json;
+using System.Threading.Tasks;
 
 namespace Microsoft.Quantum.IQSharp.Jupyter
 {
@@ -39,7 +40,7 @@ public IQSharpEngine(
             PerformanceMonitor performanceMonitor,
             IShellRouter shellRouter,
             IEventService eventService
-        ) : base(shell, context, logger)
+        ) : base(shell, shellRouter, context, logger, services)
         {
             this.performanceMonitor = performanceMonitor;
             performanceMonitor.Start();
@@ -86,7 +87,7 @@ IEventService eventService
         /// cell is expected to have a Q# snippet, which gets compiled and we return the name of
         /// the operations found. These operations are then available for simulation and estimate.
         /// </summary>
-        public override ExecutionResult ExecuteMundane(string input, IChannel channel)
+        public override async Task<ExecutionResult> ExecuteMundane(string input, IChannel channel)
         {
             channel = channel.WithNewLines();
 

src/Jupyter/Jupyter.csproj

@@ -22,7 +22,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Jupyter.Core" Version="1.2.36563" />
+    <PackageReference Include="Microsoft.Jupyter.Core" Version="1.3.52077" />
     <PackageReference Include="System.Reactive" Version="4.3.2" />
   </ItemGroup>
 

src/Jupyter/Magic/AbstractMagic.cs

@@ -3,7 +3,7 @@
 
 using System;
 using System.Collections.Generic;
-
+using System.Threading.Tasks;
 using Microsoft.Jupyter.Core;
 using Microsoft.Quantum.IQSharp.Common;
 using Microsoft.Quantum.IQSharp.Jupyter;
@@ -34,8 +34,8 @@ public AbstractMagic(string keyword, Documentation docs)
         ///     returned execution function displays the given exceptions to its
         ///     display channel.
         /// </summary>
-        public Func<string, IChannel, ExecutionResult> SafeExecute(Func<string, IChannel, ExecutionResult> magic) =>
-            (input, channel) =>
+        public Func<string, IChannel, Task<ExecutionResult>> SafeExecute(Func<string, IChannel, ExecutionResult> magic) =>
+            async (input, channel) =>
             {
                 channel = channel.WithNewLines();
 

src/Jupyter/Magic/ConfigMagic.cs

@@ -25,7 +25,48 @@ public class ConfigMagic : AbstractMagic
         public ConfigMagic(IConfigurationSource configurationSource) : base(
             "config",
             new Documentation {
-                Summary = "Allows setting or querying configuration options."
+                Summary = "Allows setting or querying configuration options.",
+                Description = @"
+                    This magic command allows for setting or querying
+                    configuration options used to control the behavior of the
+                    IQ# kernel (e.g.: state visualization options), and to
+                    save those options to a JSON file in the current working
+                    directory.
+                ".Dedent(),
+                Examples = new []
+                {
+                    @"
+                        Print a list of all currently set configuration options:
+                        ```
+                        In []: %config
+                        Out[]: Configuration key                 Value
+                               --------------------------------- -----------
+                               dump.basisStateLabelingConvention ""BigEndian""
+                               dump.truncateSmallAmplitudes      true
+                        ```
+                    ",
+
+                    @"
+                        Configure the `DumpMachine` and `DumpRegister` callables
+                        to use big-endian convention:
+                        ```
+                        In []: %config dump.basisStateLabelingConvention = ""BigEndian""
+                        Out[]: ""BigEndian""
+                        ```
+                    ".Dedent(),
+
+                    @"
+                        Save current configuration options to `.iqsharp-config.json`
+                        in the current working directory:
+                        ```
+                        In []: %config --save
+                        Out[]: 
+                        ```
+                        Note that options saved this way will be applied automatically
+                        the next time a notebook in the current working
+                        directory is loaded.
+                    ".Dedent()
+                }
             })
         {
             this.ConfigurationSource = configurationSource;