Helping people understand function signature syntax

Documentation
1

(Bringing a conversation about how to explain slash and star in function signatures from another post which talked about using <abbr> tags, and a GitHub issue which experimented with tabs to show simplified vs complete signatures).

Another possibility is to add a “help” icon next to signatures. Click it, and a box opens that could have explanatory text and links to more information. It would be unobtrusive until needed and would work on mobile. The boxed text could either be the same for all help boxes, or tailored to the signature: if the signature has no slash, the help doesn’t need to mention the slash.

For example:

image
image1252×182 13.3 KB

Other ideas?

9 Likes
2

I would appreciate such an (i) which links to a common page regarding function signatures.
This page can hold many information regarding function signatures: /, *, *args, **kwargs, self, cls, type hints, default values, sentinels, avoid mutual default values, …

3 Likes
3

I quite like the tooltip / <abbr /> idea, as I think it is even less obtrusive than the help icon.

An alternative would be to define a standard |substitution| or .. include:: (à la the availibility templates) that we could use in the descriptions of callables that use /, or *,, e.g. “All parameters before the forward slash in the function signature are postitional-only (link).” – this could go at an appropriate point in the description of the parameters.

A

1 Like
4

I think a little popup infobox would be good. Ideally, this information would also be in an actual page in the Python docs. Maybe this would go parallel to the glossary and such sections at the end of the docs content page. Possibly it could also explain other conventions, like the use of [] for optional arguments or the like, which would also aid beginners. I see this as similar to how textbooks (especially in certain fields) sometimes have a “notational conventions” page at the front or back.

5

This syntax, since 3.8, rather is a regular Python syntax. I don’t think this requires an explanation for almost every builtin in sphinx docs. Probably, everyone can figure out that this is a function declaration and proceed to Sec 8.7 of the Language Reference.

On another hand, tooltip for (the whole argument list):

def foo(pos1, pos2, /, pok1, pok2, *, kw1, kw2):
    ...

might include something like:

positional-only parameters: pos1, pos2
positional-or-keyword parameters: pok1, pok2
keyword-only parameters: kw1, kw2

with a link to related Glossary entry. (BTW, maybe there should be separate entries for parameters of different types.)

This doesn’t explain syntax itself (but people could safely guess it from such descriptions), just a more verbose optional view, that explains whats going on.

Edit: this is a slight variation of Victor’s suggestion from the CPython’s issue thread. But maybe separate tooltips for every argument even better.

It might be worth to document (this notation is not hard to understand, but to my shame I don’t know it’s history).

But I would rather consider using it as a bug. It’s better to provide several function signatures, each with a valid python syntax. Take the range() as an example vs the str.find().

1 Like
6
  • Tooltip that shows up on hover over * or /, with an underline (like an abbr)
  • A hyperlink on * or / to a relevant section of docs.python.org describing the behaviour of that symbol in a function signature.
  • Having a “positional only” or “keyword only” or “positional and keyword” separation with the parameter listing / descriptions.

(I realize I’m possibly repeating stuff that might’ve been mentioned between OP and this post, apologies for that!)

I find the (i) based approach a bit weird, since it looks like it’s information specific to the function but it’s not. It’s generic information that’s attached to all functions in some form. We could specialise it for each function but IMO it’d be better to just put that information into the “body” underneath describing the function.

I think a tooltip or link on the / or * feels the most appropriate to me, with the tooltip being the one I prefer if we can have a link within it. A link in the tooltip won’t be feasible with abbr but it could be with a custom tooltip. That would let us have the relevant context available as something that can be injected dynamically, can be less verbose with a link to a more verbose description, could reasonably discoverable if stylized correctly IMO and is not particularly obstructive for people who are familiar with the details.

A hyperlink is a similar to a tooltip in many of the tradeoffs, although it might be slightly trickier to implement and can’t be injected dynamically if we want to preserve the current “disabling JS doesn’t remove information you’d have” semantic we have today (this is a good thing to have IMO).

Adding more verbosity to the body to identify the specific type of argument feels… odd. It’d expose a detail in a more visible and clear manner, but it’s going to be repetitive and inconsistent with functions like range where the signature has variants that can be difficult to convey clearly in this manner.

3 Likes
7

Unfortunately <abbr> has accessibility problems.

In the other thread, I posted:

So even if we think it’s okay the info added via <abbr> is hidden and inaccessible for mobile, most screen readers and Braille displays because it’s extra info that isn’t essential, the problem is that some screen readers will only read out the “hidden” info, and not the linked * or /.

For example, given something like this:

classmethod fromkeys(iterable, value=None, <abbr title="Parameters before the slash (/) are positional-only.">/</abbr>)

One screen reader will say:

classmethod, fromkeys, iterable, value equals none, slash

But another may say:

classmethod, fromkeys, iterable, value equals none, parameters before the slash, slash, are positional-only

And say it everywhere. Which is much worse than just hiding away some additional info.

3 Likes