Skip to content

bpo-43698: do not use ... as argument name in docs #30502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 26, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 8 additions & 11 deletions Doc/faq/design.rst
Original file line number Diff line number Diff line change
Expand Up @@ -266,27 +266,24 @@ For cases where you need to choose from a very large number of possibilities,
you can create a dictionary mapping case values to functions to call. For
example::

def function_1(...):
...

functions = {'a': function_1,
'b': function_2,
'c': self.method_1, ...}
'c': self.method_1}

func = functions[value]
func()

For calling methods on objects, you can simplify yet further by using the
:func:`getattr` built-in to retrieve methods with a particular name::

def visit_a(self, ...):
...
...
class MyVisitor:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This case is special. There was no class context defined. I've added it as well.

def visit_a(self):
...

def dispatch(self, value):
method_name = 'visit_' + str(value)
method = getattr(self, method_name)
method()
def dispatch(self, value):
method_name = 'visit_' + str(value)
method = getattr(self, method_name)
method()

It's suggested that you use a prefix for the method names, such as ``visit_`` in
this example. Without such a prefix, if values are coming from an untrusted
Expand Down
4 changes: 2 additions & 2 deletions Doc/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -282,12 +282,12 @@ Glossary
The decorator syntax is merely syntactic sugar, the following two
function definitions are semantically equivalent::

def f(...):
def f(arg):
...
f = staticmethod(f)

@staticmethod
def f(...):
def f(arg):
...

The same concept exists for classes, but is less commonly used there. See
Expand Down
10 changes: 5 additions & 5 deletions Doc/library/abc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -186,15 +186,15 @@ The :mod:`abc` module also provides the following decorator:

class C(ABC):
@abstractmethod
def my_abstract_method(self, ...):
def my_abstract_method(self, arg1):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
def my_abstract_method(self, arg1):
def my_abstract_method(self, arg):

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've used explicitly different names to highlight that they are different.

...
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
def my_abstract_classmethod(cls, arg2):
...
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
def my_abstract_staticmethod(arg3):
...

@property
Expand Down Expand Up @@ -255,7 +255,7 @@ The :mod:`abc` module also supports the following legacy decorators:
class C(ABC):
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
def my_abstract_classmethod(cls, arg):
...


Expand All @@ -276,7 +276,7 @@ The :mod:`abc` module also supports the following legacy decorators:
class C(ABC):
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
def my_abstract_staticmethod(arg):
...


Expand Down
2 changes: 1 addition & 1 deletion Doc/library/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -248,7 +248,7 @@ are always available. They are listed here in alphabetical order.

class C:
@classmethod
def f(cls, arg1, arg2, ...): ...
def f(cls, arg1, arg2): ...

The ``@classmethod`` form is a function :term:`decorator` -- see
:ref:`function` for details.
Expand Down