Argument Clinic: optional groups

[serhiy-storchaka]

BPO	20303
Nosy	@larryhastings, @serhiy-storchaka

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-01-19.13:29:40.132>
labels = ['type-feature', 'expert-argument-clinic', 'build']
title = 'Argument Clinic: optional groups'
updated_at = <Date 2015-05-05.12:12:59.075>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2015-05-05.12:12:59.075>
actor = 'serhiy.storchaka'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Build', 'Demos and Tools', 'Argument Clinic']
creation = <Date 2014-01-19.13:29:40.132>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 20303
keywords = []
message_count = 6.0
messages = ['208478', '208637', '208738', '242590', '242597', '242599']
nosy_count = 2.0
nosy_names = ['larry', 'serhiy.storchaka']
pr_nums = []
priority = 'low'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue20303'
versions = ['Python 3.4']

Linked PRs

• gh-64502: Fix Argument Clinic support of optional groups with defaults #155191
• [3.15] gh-64502: Fix Argument Clinic support of optional groups with defaults (GH-155191) #155209
• gh-64502: Support several optional groups on the same level in Argument Clinic #155210
• [3.14] gh-64502: Fix Argument Clinic support of optional groups with defaults (GH-155191) #155216
• [3.13] gh-64502: Fix Argument Clinic support of optional groups with defaults (GH-155191) #155217
• gh-64502: Convert curses methods with optional groups to Argument Clinic #155229

[serhiy-storchaka]

This is very very low priority issue. Currently Argument Clinic can't process following declaration:

/*[clinic input]
curses.window.chgat

    self: self(type="PyCursesWindowObject *")
    [
    y: int
        Y-coordinate.
    x: int
        X-coordinate.
    ]

    [
    num: int
        Number of characters.
    ]

    attr: long
        Attributes for the character.
    /

[clinic start generated code]*/

This stops three methods in the curse module to be converted to Argument Clinic.

[larryhastings]

Confirmed, and yes it's low priority.

[larryhastings]

When I fix bpo-20303, the new rules will be:

• You can have top-level optional groups anywhere.
• You may nest up to one nested group in a group.
• Whenever you nest a group in another group, all nested groups in that
  stack must favor the same side (left or right).

Here's are example of nesting. This is permitted:

[ a, [b, [c,]]]

This is not:

[a, [[b,] c,]]

because the nested group adjoining "a" is on the right, but the nested group adjoining "c" is on the left.

The generated names for group variables will probably change to "group_{n}", where n starts at 1 and is assigned going straight across to the right, ignoring nesting, like groups in regular expressions.

[serhiy-storchaka]

I tried to make a workaround with using default value instead of optional group, but for the following declaration an incorrect code is generated:

/*[clinic input]
_curses.window.getstr

    [
    y: int
        Y-coordinate.
    x: int
        X-coordinate.
    ]
    n: int = 1023
    /

[clinic start generated code]*/

Generated code is:

static PyObject *
_curses_window_getstr(PyCursesWindowObject *self, PyObject *args)
{
    PyObject *return_value = NULL;
    int group_left_1 = 0;
    int y = 0;
    int x = 0;
    int n = 1023;

    switch (PyTuple_GET_SIZE(args)) {
        case 1:
            if (!PyArg_ParseTuple(args, "i:getstr", &n))
                goto exit;
            break;
        case 3:
            if (!PyArg_ParseTuple(args, "iii:getstr", &y, &x, &n))
                goto exit;
            group_left_1 = 1;
            break;
        default:
            PyErr_SetString(PyExc_TypeError, "_curses.window.getstr requires 1 to 3 arguments");
            goto exit;
    }
    return_value = _curses_window_getstr_impl(self, group_left_1, y, x, n);

exit:
    return return_value;
}

Expected generated code:

static PyObject *
_curses_window_getstr(PyCursesWindowObject *self, PyObject *args)
{
    PyObject *return_value = NULL;
    int group_left_1 = 0;
    int y = 0;
    int x = 0;
    int n = 1023;

    switch (PyTuple_GET_SIZE(args)) {
        case 0:
        case 1:
            if (!PyArg_ParseTuple(args, "|i:getstr", &n))
                goto exit;
            break;
        case 2:
        case 3:
            if (!PyArg_ParseTuple(args, "ii|i:getstr", &y, &x, &n))
                goto exit;
            group_left_1 = 1;
            break;
        default:
            PyErr_SetString(PyExc_TypeError, "_curses.window.getstr requires 0 to 3 arguments");
            goto exit;
    }
    return_value = _curses_window_getstr_impl(self, group_left_1, y, x, n);

exit:
    return return_value;
}

This bug looks similar to bpo-24051.

[larryhastings]

Yes, when I implemented optional groups, I didn't realize that sometimes people mixed them with optional arguments (with default values). Clinic doesn't cope well when you mix the two.

Does this work?

/*[clinic input]
_curses.window.getstr

[
y: int
    Y-coordinate.
x: int
    X-coordinate.
]
[
n: int
]

I'm surprised people are adding new arguments to a function like curses.window.getstr().

[serhiy-storchaka]

Does this work?

No, Argument Clinic just rejects this (as in msg208478).

Perhaps a half of functions that need optional groups, need also support of default argument or other optional group.