[Python-checkins] bpo-43698: do not use `...` as argument name in docs (GH-30502)
miss-islington
webhook-mailer at python.org
Wed Jan 26 07:42:43 EST 2022
https://github.com/python/cpython/commit/49971b2d1890c15eeec2d83ea3e8d178f266c4f9
commit: 49971b2d1890c15eeec2d83ea3e8d178f266c4f9
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-01-26T04:42:39-08:00
summary:
bpo-43698: do not use `...` as argument name in docs (GH-30502)
(cherry picked from commit b9d8980d89bfaa4bf16d60f0488adcc9d2cbf5ef)
Co-authored-by: Nikita Sobolev <mail at sobolevn.me>
files:
M Doc/faq/design.rst
M Doc/glossary.rst
M Doc/library/abc.rst
M Doc/library/functions.rst
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index d0aee4e607268..01fa5c77d8659 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -267,12 +267,9 @@ 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()
@@ -280,14 +277,14 @@ example::
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:
+ 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
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index da9dc9ceebfc4..f759c3fb05607 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -278,12 +278,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
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 424ae547d829a..35be01e891e9d 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -185,15 +185,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):
...
@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
@@ -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):
...
@@ -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):
...
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 8df557e47a16e..9a9c707dc177a 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -210,7 +210,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.
More information about the Python-checkins
mailing list