bpo-26110: Document `CALL_METHOD_KW` (GH-26159)

Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>

2 files changed, 27 insertions, 1 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 193e400..a4746bc 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -1176,6 +1176,18 @@ All of the following opcodes use their arguments.
    .. versionadded:: 3.7
 
 
+.. opcode:: CALL_METHOD_KW (argc)
+
+   Calls a method in a similar fashion as :opcode:`CALL_METHOD`, but also supports keyword arguments.
+   *argc* is the number of positional and keyword arguments.
+   This opcode is designed to be used with :opcode:`LOAD_METHOD`.  TOS is a
+   tuple of keyword argument names.  Argument values are below that.
+   Below them, the two items described in :opcode:`LOAD_METHOD` are on the
+   stack (either ``self`` and an unbound method object or ``NULL`` and an
+   arbitrary callable).  All of them are popped from the stack and the return value is pushed.
+
+   .. versionadded:: 3.11
+
 .. opcode:: MAKE_FUNCTION (flags)
 
    Pushes a new function object on the stack.  From bottom to top, the consumed
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 5036882..9058b26 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -90,7 +90,7 @@ Improved Modules
 Optimizations
 =============
 
-* Compiler optimizes now simple C-style formatting with literal format
+* Compiler now optimizes simple C-style formatting with literal format
   containing only format codes ``%s``, ``%r`` and ``%a`` and makes it as
   fast as corresponding f-string expression.
   (Contributed by Serhiy Storchaka in :issue:`28307`.)
@@ -99,6 +99,20 @@ Optimizations
   almost eliminated when no exception is raised.
   (Contributed by Mark Shannon in :issue:`40222`.)
 
+* Method calls with keywords are now faster due to bytecode
+  changes which avoid creating bound method instances. Previously, this
+  optimization was applied only to method calls with purely positional
+  arguments.
+  (Contributed by Ken Jin and Mark Shannon in :issue:`26110`, based on ideas
+  implemented in PyPy.)
+
+CPython bytecode changes
+========================
+
+* Added a new :opcode:`CALL_METHOD_KW` opcode.  Calls a method in a similar
+  fashion as :opcode:`CALL_METHOD`, but also supports keyword arguments.  Works
+  in tandem with :opcode:`LOAD_METHOD`.
+
 
 Build Changes
 =============