changeset:   106205:ef20dbbfe9f7
tag:         tip
user:        Victor Stinner <victor.stinner@gmail.com>
date:        Tue Jan 17 15:57:20 2017 +0100
files:       Tools/clinic/clinic.py
description:
Change how AC formats optional positional-only args

Change how Argument Clinic formats optional positional-only arguments in the
signature of a function docstring.


diff -r 5dd5d50c4d58 -r ef20dbbfe9f7 Tools/clinic/clinic.py
--- a/Tools/clinic/clinic.py	Tue Jan 17 15:28:36 2017 +0100
+++ b/Tools/clinic/clinic.py	Tue Jan 17 15:57:20 2017 +0100
@@ -4053,6 +4053,24 @@ class DSLParser:
                 # don't put any right brackets around non-positional-only parameters, ever.
                 p.right_bracket_count = 0
 
+        optional_positional_only = False
+        if positional_only and parameters[-1].converter.c_default == 'NULL':
+            # Put optional positional-only parameters into brakets,
+            # each argument is its own braket: func(arg, [opt1[, opt2]])
+            last_optional_positional = len(parameters) - 1
+            first_optional_positional = last_optional_positional
+            while first_optional_positional:
+                if parameters[first_optional_positional - 1].converter.c_default != 'NULL':
+                    break
+                first_optional_positional -= 1
+
+            bracket = 1
+            for p in parameters[first_optional_positional:last_optional_positional+1]:
+                p.right_bracket_count += bracket
+                bracket += 1
+
+            optional_positional_only = True
+
         right_bracket_count = 0
 
         def fix_right_bracket_count(desired):
@@ -4074,7 +4092,7 @@ class DSLParser:
         #   * if this is not a "docstring_only" signature
         #   * and if the last *shown* parameter is
         #     positional only
-        if not f.docstring_only:
+        if not f.docstring_only and not optional_positional_only:
             for p in reversed(parameters):
                 if not p.converter.show_in_signature:
                     continue
@@ -4105,7 +4123,12 @@ class DSLParser:
             line_length += len(s)
             add(s)
 
-        for p in parameters:
+        for p_index, p in enumerate(parameters):
+            try:
+                next_p = parameters[p_index + 1]
+            except IndexError:
+                next_p = None
+
             if not p.converter.show_in_signature:
                 continue
             assert p.name
@@ -4127,7 +4150,9 @@ class DSLParser:
                 add_parameter('*,')
 
             p_add, p_output = text_accumulator()
-            p_add(fix_right_bracket_count(p.right_bracket_count))
+
+            if not optional_positional_only:
+                p_add(fix_right_bracket_count(p.right_bracket_count))
 
             if isinstance(p.converter, self_converter):
                 # annotate first parameter as being a "self".
@@ -4148,14 +4173,24 @@ class DSLParser:
                 p_add('$')
 
             name = p.converter.signature_name or p.name
-            p_add(name)
-
-            if p.converter.is_optional():
-                p_add('=')
-                value = p.converter.py_default
-                if not value:
-                    value = repr(p.converter.default)
-                p_add(value)
+
+            if optional_positional_only:
+                if p.converter.is_optional():
+                    p_add(name)
+                else:
+                    p_add(name)
+            else:
+                p_add(name)
+
+                if p.converter.is_optional():
+                    p_add('=')
+                    value = p.converter.py_default
+                    if not value:
+                        value = repr(p.converter.default)
+                    p_add(value)
+
+            if optional_positional_only and next_p is not None:
+                p_add(fix_right_bracket_count(next_p.right_bracket_count))
 
             if (p != last_p) or need_a_trailing_slash:
                 p_add(',')