PEP 637: Add another rationale, and more (#1615)

* Add another rationale for this syntax

* Add missing escapes

* Improve wording as per comment from @stevendaprano

* added another sentence to clarify what `trio.run` actually does

pep-0637.rst

@@ -118,6 +118,40 @@ specification would improve notation and provide additional value:
        >>> # new syntax
        >>> ds["empty"][lon=1:5, lat=6:] = 10
 
+6. Functions/methods whose argument is another function (plus its
+   arguments) need some way to determine which arguments are destined for
+   the target function, and which are used to configure how they run the
+   target. This is simple (if non-extensible) for positional parameters,
+   but we need some way to distinguish these for keywords.[#trio-run]_
+
+   An indexed notation would afford a Pythonic way to pass keyword
+   arguments to these functions without cluttering the caller's code.
+
+   ::
+
+     >>> # Let's start this example with basic syntax without keywords.
+     >>> # the positional values are arguments to `func` while
+     >>> # `name=` is processed by `trio.run`.
+     >>> trio.run(func, value1, value2, name="func")
+     >>> # `trio.run` ends up calling `func(value1, value2)`.
+
+     >>> # If we want/need to pass value2 by keyword (keyword-only argument,
+     >>> # additional arguments that won't break backwards compatibility ...),
+     >>> # currently we need to resort to functools.partial:
+     >>> trio.run(functools.partial(func, param2=value2), value1, name="func")
+     >>> trio.run(functools.partial(func, value1, param2=value2), name="func")
+
+     >>> # One possible workaround is to convert `trio.run` to an object
+     >>> # with a `__call__` method, and use an "option" helper,
+     >>> trio.run.option(name="func")(func, value1, param2=value2)
+     >>> # However, foo(bar)(baz) is uncommon and thus disruptive to the reader.
+     >>> # Also, you need to remember the name of the `option` method.
+
+     >>> # This PEP allows us to replace `option` with `__getitem__`.
+     >>> # The call is now shorter, more mnemonic, and looks+works like typing
+     >>> trio.run[name="func"](func, value1, param2=value2)
+
+
 It is important to note that how the notation is interpreted is up to the
 implementation. This PEP only defines and dictates the behavior of python
 regarding passed keyword arguments, not how these arguments should be
@@ -957,6 +991,8 @@ References
        (https://mail.python.org/archives/list/[email protected]/thread/6OGAFDWCXT5QVV23OZWKBY4TXGZBVYZS/)
 .. [#pep-0001] "PEP 1 -- PEP Purpose and Guidelines"
        (https://www.python.org/dev/peps/pep-0001/#what-belongs-in-a-successful-pep)
+.. [#trio-run] "trio.run() should take \*\*kwargs in addition to \*args"
+       (https://github.com/python-trio/trio/issues/470)
 .. [#numpy-ml] "[Numpy-discussion] Request for comments on PEP 637 - Support for indexing with keyword arguments"
        (http://numpy-discussion.10968.n7.nabble.com/Request-for-comments-on-PEP-637-Support-for-indexing-with-keyword-arguments-td48489.html)