gh-145644: Update function related explanations on "controlflow.rst"#145645
gh-145644: Update function related explanations on "controlflow.rst"#145645hyperkai wants to merge 6 commits intopython:mainfrom
Conversation
picnixz
left a comment
There was a problem hiding this comment.
This is the tutorial:
- Exceptions messages must only be updated if they match the runtime message.
- Leave out
var-positionaland other terminologies out of the tutorial. It will become too much for a beginner. Formal terms are better suited for formal documentation.
|
|
||
|
|
||
| .. _tut-defaultargs: | ||
| .. _tut-defaultparams: |
There was a problem hiding this comment.
Changing this will break URLs, and blog post referrring to that.
| and their order is not important. This also includes | ||
| non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too). | ||
| No argument may receive a value more than once. | ||
| No arguments are possible only if no required parameters exist. |
There was a problem hiding this comment.
This is not an equivalent sentence. We want to say that you cannot specify a parameter twice.
Doc/tutorial/controlflow.rst
Outdated
| Traceback (most recent call last): | ||
| File "<stdin>", line 1, in <module> | ||
| TypeError: function() got multiple values for argument 'a' | ||
| TypeError: function() got multiple values for parameter 'a' |
There was a problem hiding this comment.
Has this been changed at the C level? if not, don't change it.
| receives a :ref:`tuple <tut-tuples>` containing the positional | ||
| arguments beyond the formal parameter list. (``*name`` must occur | ||
| before ``**name``.) For example, if we define a function like this:: | ||
| When a final var-keyword parameter ``**name`` is present, it defaults to an empty |
There was a problem hiding this comment.
Formal parameter is correct. And I would keep the "receives an empty dictionary" because it's really a new empty dictionary every time.
| arguments beyond the formal parameter list. (``*name`` must occur | ||
| before ``**name``.) For example, if we define a function like this:: | ||
| When a final var-keyword parameter ``**name`` is present, it defaults to an empty | ||
| dictionary (see :ref:`typesmapping`) to receive all keyword arguments except for |
There was a problem hiding this comment.
This is inaccurate. It's not meant to receive the keyword arguments. It's really a dictionary already containing the arguments.
| parameter ``*name`` (described in the next subsection) which defaults to an empty | ||
| :ref:`tuple <tut-tuples>` to receive all positional arguments except for those received |
| before ``**name``.) For example, if we define a function like this:: | ||
| When a final var-keyword parameter ``**name`` is present, it defaults to an empty | ||
| dictionary (see :ref:`typesmapping`) to receive all keyword arguments except for | ||
| those corresponding to other parameters. This may be combined with a var-positional |
There was a problem hiding this comment.
We don't want to introduce the terminology of "var-positional" or "var-keyword" in this tutorial.
| ------------------ | ||
|
|
||
| By default, arguments may be passed to a Python function either by position | ||
| By default, arguments can be passed to a Python function either by position |
|
|
||
| If ``/`` and ``*`` are not present in the function definition, arguments may | ||
| be passed to a function by position or by keyword. | ||
| Positional-or-keyword paremeters don't precede ``/``, don't follow ``*`` or ``*args``, |
| >>> | ||
|
|
||
| But using ``/`` (positional only arguments), it is possible since it allows ``name`` as a positional argument and ``'name'`` as a key in the keyword arguments:: | ||
| But using ``/`` (positional-only parameters) and calling ``foo()`` works because |
There was a problem hiding this comment.
Strictly speaking, you call foo, not foo(). foo() is already the result of the call.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
Fix: #145644
📚 Documentation preview 📚: https://cpython-previews--145645.org.readthedocs.build/