[New-bugs-announce] [issue43698] Use syntactically correct examples on abc package page

[Vladimir Ryabtsev]

New submission from Vladimir Ryabtsev <greatvovan at gmail.com>:

There are code snippets on the package's page (https://docs.python.org/3.10/library/abc.html) like this:

class C(ABC):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...

Here, the author probably wanted to demonstrate that the method may have _any other arguments_ in addition to `cls`, but it makes the code not compilable:

    def my_abstract_classmethod(cls, ...):
                                     ^
SyntaxError: invalid syntax

Additionally it uses the same Ellipsis as in the method's body (that is supposed to indicate a stub), which is confusing.

I think that all code samples must be syntactically correct, so that if a reader copypastes them into their code editor they would work right away. I suggest to remove ellipsis in the argument lists everywhere on the page and replace them with one of the following:

- sample parameters such as `a, b, c` or `my_arg1, my_arg2`,
- `*args, **kwargs`,
- nothing.

----------
assignee: docs at python
components: Documentation
messages: 390004
nosy: Vladimir Ryabtsev, docs at python
priority: normal
severity: normal
status: open
title: Use syntactically correct examples on abc package page
type: compile error
versions: Python 3.10, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue43698>
_______________________________________