Raise a proper unexpected-keyword-argument TypeError on bind failure

When a method call fails to bind and one of the supplied keyword arguments
matches no parameter of any candidate overload, the generic 'No method
matches given arguments' message did not mention the keyword argument at
all (only positional argument types are echoed), leaving the actual
mistake invisible, e.g.:

    market_order(symbol, -10, as_tag="EmergencyFlatten")
    -> No method matches given arguments for market_order:
       (<class 'Symbol'>, <class 'int'>). The following overloads ...

Now such calls raise the Python-style error instead, naming the offending
kwarg and suggesting the closest parameter name when one exists:

    market_order() got an unexpected keyword argument 'as_tag'.
    Did you mean 'tag'?

When every kwarg name is valid for some overload but binding still fails,
the existing no-method-matches message is preserved.

Author: jhonabreul

src/runtime/MethodBinder.cs

@@ -1016,6 +1016,14 @@ internal virtual NewReference Invoke(BorrowedReference inst, BorrowedReference a
                 // If we already have an exception pending, don't create a new one
                 if (!Exceptions.ErrorOccurred())
                 {
+                    // A keyword argument whose name no candidate overload accepts gets the
+                    // Python-native "unexpected keyword argument" error: the generic no-match
+                    // message below does not echo kwargs, leaving the actual mistake invisible.
+                    if (TryRaiseUnexpectedKeywordArgumentError(kw, info, methodinfo))
+                    {
+                        return default;
+                    }
+
                     var value = new StringBuilder("No method matches given arguments");
                     // Use the snake_case name Python callers use, matching the hinted signatures below.
                     if (methodinfo != null && methodinfo.Length > 0)
@@ -1123,6 +1131,134 @@ internal virtual NewReference Invoke(BorrowedReference inst, BorrowedReference a
             return Converter.ToPython(result, returnType);
         }
 
+        /// <summary>
+        /// When a bind failure involves a keyword argument whose name no candidate overload
+        /// accepts, raises the Python-style "got an unexpected keyword argument" TypeError
+        /// (with a "Did you mean" hint when a similarly-named parameter exists) and returns
+        /// true. Returns false when every kwarg name is accepted by at least one overload,
+        /// so the generic no-match error is raised instead.
+        /// </summary>
+        private bool TryRaiseUnexpectedKeywordArgumentError(BorrowedReference kw, MethodBase info, MethodInfo[] methodinfo)
+        {
+            var kwCount = kw == null ? 0 : (int)Runtime.PyDict_Size(kw);
+            if (kwCount <= 0)
+            {
+                return false;
+            }
+
+            // The same candidate set Bind considered: parameter names are snake_case for
+            // snake_case-registered methods and original for the original ones, matching
+            // the names the caller can actually use.
+            var methods = info == null
+                ? GetMethods()
+                : new List<MethodInformation>(1) { new MethodInformation(info, true) };
+            var parameterNames = new HashSet<string>(StringComparer.Ordinal);
+            foreach (var method in methods)
+            {
+                foreach (var parameterName in method.ParameterNames)
+                {
+                    parameterNames.Add(parameterName);
+                }
+            }
+
+            // Report the first unknown kwarg in call order, like CPython does.
+            string unexpectedName = null;
+            using (var keyList = Runtime.PyDict_Keys(kw))
+            {
+                for (var i = 0; i < kwCount && unexpectedName == null; i++)
+                {
+                    var name = Runtime.GetManagedString(Runtime.PyList_GetItem(keyList.Borrow(), i));
+                    if (name != null && !parameterNames.Contains(name))
+                    {
+                        unexpectedName = name;
+                    }
+                }
+            }
+
+            if (unexpectedName == null)
+            {
+                return false;
+            }
+
+            string methodName = null;
+            if (methodinfo != null && methodinfo.Length > 0)
+            {
+                methodName = MethodSignatureFormatter.SnakeCaseName(methodinfo[0]);
+            }
+            else if (list.Count > 0)
+            {
+                methodName = MethodSignatureFormatter.SnakeCaseName(list[0].MethodBase);
+            }
+            if (string.IsNullOrEmpty(methodName))
+            {
+                return false;
+            }
+
+            var message = $"{methodName}() got an unexpected keyword argument '{unexpectedName}'";
+            var suggestion = ClosestParameterName(unexpectedName, parameterNames);
+            if (suggestion != null)
+            {
+                message += $". Did you mean '{suggestion}'?";
+            }
+
+            Exceptions.RaiseTypeError(message);
+            return true;
+        }
+
+        /// <summary>
+        /// The candidate parameter name closest to the unexpected kwarg name, or null when
+        /// none is similar enough to suggest. A candidate is considered when it is within
+        /// a small edit distance of the name, or when one contains the other (e.g. 'as_tag'
+        /// suggests 'tag'); containment requires 3+ characters so tiny names don't match.
+        /// </summary>
+        private static string ClosestParameterName(string name, HashSet<string> parameterNames)
+        {
+            const int MinContainmentLength = 3;
+            var threshold = Math.Max(2, name.Length / 3);
+            string best = null;
+            var bestDistance = int.MaxValue;
+            foreach (var candidate in parameterNames)
+            {
+                var distance = KeywordEditDistance(name, candidate);
+                var related = distance <= threshold
+                    || (candidate.Length >= MinContainmentLength && name.Length >= MinContainmentLength
+                        && (candidate.IndexOf(name, StringComparison.OrdinalIgnoreCase) >= 0
+                            || name.IndexOf(candidate, StringComparison.OrdinalIgnoreCase) >= 0));
+                if (related && (distance < bestDistance
+                    || (distance == bestDistance && string.CompareOrdinal(candidate, best) < 0)))
+                {
+                    bestDistance = distance;
+                    best = candidate;
+                }
+            }
+            return best;
+        }
+
+        // Case-insensitive Levenshtein distance, local to keyword suggestions.
+        private static int KeywordEditDistance(string a, string b)
+        {
+            a = a.ToLowerInvariant();
+            b = b.ToLowerInvariant();
+            if (a.Length == 0) return b.Length;
+            if (b.Length == 0) return a.Length;
+
+            var prev = new int[b.Length + 1];
+            var curr = new int[b.Length + 1];
+            for (var j = 0; j <= b.Length; j++) prev[j] = j;
+
+            for (var i = 1; i <= a.Length; i++)
+            {
+                curr[0] = i;
+                for (var j = 1; j <= b.Length; j++)
+                {
+                    var cost = a[i - 1] == b[j - 1] ? 0 : 1;
+                    curr[j] = Math.Min(Math.Min(curr[j - 1] + 1, prev[j] + 1), prev[j - 1] + cost);
+                }
+                (prev, curr) = (curr, prev);
+            }
+            return prev[b.Length];
+        }
+
         /// <summary>
         /// Utility class to store the information about a <see cref="MethodBase"/>
         /// </summary>

src/testing/methodtest.cs

@@ -709,6 +709,11 @@ public static string DefaultParamsWithOverloading(int a = 5, int b = 6, int c =
             return $"{a}{b}{c}{d}XXX";
         }
 
+        public static string OrderLikeMethod(string symbol, decimal quantity, bool asynchronous = false, string tag = "", object orderProperties = null)
+        {
+            return string.Format("{0}:{1}:{2}:{3}", symbol, quantity, asynchronous, tag);
+        }
+
         public static string ParamsArrayOverloaded(int i = 1)
         {
             return "without params-array";

tests/test_method.py

@@ -1104,6 +1104,53 @@ def test_default_params():
     with pytest.raises(TypeError):
         MethodTest.DefaultParams(1,2,3,4,5)
 
+def test_unexpected_keyword_argument_with_suggestion():
+    # A kwarg no overload accepts raises the Python-style error naming the kwarg,
+    # with a did-you-mean hint when a similarly-named parameter exists.
+    with pytest.raises(TypeError) as excinfo:
+        MethodTest.order_like_method("SPY", 10, as_tag="EmergencyFlatten")
+    message = str(excinfo.value)
+    assert "order_like_method() got an unexpected keyword argument 'as_tag'" in message
+    assert "Did you mean 'tag'?" in message
+
+    # Same behavior when calling through the original PascalCase name; parameter
+    # names are the original ones there.
+    with pytest.raises(TypeError) as excinfo:
+        MethodTest.OrderLikeMethod("SPY", 10, asTag="EmergencyFlatten")
+    message = str(excinfo.value)
+    assert "order_like_method() got an unexpected keyword argument 'asTag'" in message
+    assert "Did you mean 'tag'?" in message
+
+
+def test_unexpected_keyword_argument_without_suggestion():
+    # No parameter is remotely similar: the kwarg is still named, but no hint is added.
+    with pytest.raises(TypeError) as excinfo:
+        MethodTest.order_like_method("SPY", 10, completely_unrelated_name=1)
+    message = str(excinfo.value)
+    assert "order_like_method() got an unexpected keyword argument " \
+           "'completely_unrelated_name'" in message
+    assert "Did you mean" not in message
+
+
+def test_unexpected_keyword_argument_reports_first_in_call_order():
+    with pytest.raises(TypeError) as excinfo:
+        MethodTest.order_like_method("SPY", 10, first_bogus=1, second_bogus=2)
+    assert "got an unexpected keyword argument 'first_bogus'" in str(excinfo.value)
+
+
+def test_valid_keyword_arguments_still_bind():
+    res = MethodTest.order_like_method("SPY", 10, asynchronous=True, tag="mytag")
+    assert res == "SPY:10:True:mytag"
+
+
+def test_valid_keyword_argument_names_keep_no_match_message():
+    # All kwarg names are real parameters, but the call still cannot bind ('d' is
+    # supplied both positionally and by name): the classic no-method-matches
+    # message must be preserved for this case.
+    with pytest.raises(TypeError) as excinfo:
+        MethodTest.DefaultParams(1, 2, 3, 4, d=5)
+    assert "No method matches given arguments for default_params" in str(excinfo.value)
+
 def test_optional_params():
     res = MethodTest.OptionalParams(1, 2, 3, 4)
     assert res == "1234"