Unify method signature format in `str`

[ofey404]

Documentation

Currently, there are two different method signature style in builtin type str.

• The new style, marking the positional only parameters, like zfill(self, width, /)
• The old style, leading with S., and should use an extra line to describe the signature.
  • Currently there are 9 S. started methods: count, endswith, find, format, format_map, index, rfind, rindex and startswith.

Example of new style and old style:

## New Style:

help(str.zfill)
# Help on method_descriptor:
# 
# zfill(self, width, /)
#     Pad a numeric string with zeros on the left, to fill a field of the given width.
#     
#     The string is never truncated.


## Old Style:

help(str.find)
# Help on method_descriptor:
# 
# find(...)
#     S.find(self, sub, start=None, end=None, /) -> int
# 
#     Return the lowest index in S where substring sub is found,
#     such that sub is contained within S[start:end].  Optional
#     arguments start and end are interpreted as in slice notation.
# 
#     Return -1 on failure.

Suggestion

Change the 9 old style documentation to the new style:

• count, endswith, find, format, format_map, index, rfind, rindex and startswith.

Take str.find as an example, it would be more concise and consistent:

help(str.find)
# Help on method_descriptor:
# 
# find(self, sub, start=None, end=None, /) -> int
# 
#     Return the lowest index in S where substring sub is found,
#     such that sub is contained within S[start:end].  Optional
#     arguments start and end are interpreted as in slice notation.
# 
#     Return -1 on failure.

[arhadthedev]

I noticed that these methods are the only ones in https://github.com/python/cpython/blob/main/Objects/unicodeobject.c not converted to Argument Clinic.

I'll shortly create a porting PR that addresses this. All methods have tree arguments so I hope that simplification of help syncing and argument parsing will outweight an extra level of the clinic's abstraction.

[ofey404]

I noticed that these methods are the only ones in https://github.com/python/cpython/blob/main/Objects/unicodeobject.c not converted to Argument Clinic.

Thank you for your attention!

Those remaining unported functions are mostly about parse_args_finds_unicode, and have a PyObject *args as its parameter.

• I guess those need special treatment, so I created gh-96354: Port docstring of unicode_find family to Argument Clinic #96356

About parse_args_finds_unicode

Basically the additional check in parse_args_finds_unicode is to check the substring is a unicode object.

• As the parsing argument part is handled by clinic, I think we can extract ensure_unicode
• it will make the logic cleaner.

/*
Wraps asciilib_parse_args_finds() and additionally ensures that the
first argument is a unicode object.
*/

static inline int
parse_args_finds_unicode(const char * function_name, PyObject *args,
                         PyObject **substring,
                         Py_ssize_t *start, Py_ssize_t *end)
{
    if (asciilib_parse_args_finds(function_name, args, substring, start, end)) {
        if (ensure_unicode(*substring) < 0)
            return 0;
        return 1;
    }
    return 0;
}

[merwok]

I suggest getting the opinion of a core dev (someone who’s changed that module, or who has done argument clinic conversions) about this issue and proposed fix! It’s always useful to confirm that a change is wanted, and that the idea for the solution is in a good direction, before spending much time working.

[ofey404]

I suggest getting the opinion of a core dev (someone who’s changed that module, or who has done argument clinic conversions) about this issue and proposed fix! It’s always useful to confirm that a change is wanted, and that the idea for the solution is in a good direction, before spending much time working.

Yes, I think so. But I quite don’t know how to get in touch with a core dev , and the community might lack manpower on reviewing.

[ofey404]

Hello @methane , I notice that you previously used Argument clinic in Objects/unicodeobject.c, would you like to have a look at this issue and PR #96356 ?

Hello @larryhastings , although Great Argument Clinic Conversion Derby is over, would you like to review the Argument Clinic usage here?

[StanFromIreland]

All but format and formatmap have been converted to AC in #117431 e.g. 7ecd55d

[StanFromIreland]

It seems they have all been fixed anyway:

Help on method descriptor format:

format(self, /, *args, **kwargs) unbound builtins.str method
    Return a formatted version of the string, using substitutions from args and kwargs.
    The substitutions are identified by braces ('{' and '}').

Help on method descriptor find:

find(self, sub[, start[, end]], /) unbound builtins.str method
    Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].

    Optional arguments start and end are interpreted as in slice notation.
    Return -1 on failure.

Help on method descriptor format_map:

format_map(self, mapping, /) unbound builtins.str method
    Return a formatted version of the string, using substitutions from mapping.
    The substitutions are identified by braces ('{' and '}').