classification
Title: An unclear definition in Doc/glossary.rst
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: StevenHsuYL, docs@python, jack__d, mark.dickinson, terry.reedy
Priority: normal Keywords: patch

Created on 2021-07-16 05:11 by StevenHsuYL, last changed 2021-07-22 16:29 by mark.dickinson. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 27226 merged StevenHsuYL, 2021-07-18 13:05
Messages (9)
msg397597 - (view) Author: Steven Hsu (StevenHsuYL) * Date: 2021-07-16 05:11
In Doc/glossary.rst, the definition about "coercion" is as below:

"The implicit conversion of an instance of one type to another during an operation which involves two arguments of the same type."

However, in the example following this definition, it shows the arguments of "different" type in an adding operation, and one of them was converted to `float` for the operation.

Therefore, we should fix the definition of the coercion to as below:

"The implicit conversion of an instance of one type to another during an operation which involves two arguments of the different type."

Or am I realize this sentence wrong?
Thanks for review.

https://github.com/python/cpython/blob/main/Doc/glossary.rst
msg397645 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-07-16 18:28
Agreed that "of the same type" part is confusing. I suspect the intended meaning was that the operation *expects* both arguments to have the same type, so if the actual arguments have different types then they have to be coerced to a common type. In the example you mention, the 3 is converted to 3.0 so that the actual addition is applied to two arguments of the same type. So I think the "same type" part *was* intentional, if confusing.

But coercion was more of a real thing in Python 2, where there was a __coerce__ special method and a coerce builtin function. It isn't really a thing any more in Python 3, except inasmuch as it means "implicit type conversion". And I can't find any uses of :term:`coercion` elsewhere in the docs. Maybe we should just delete this glossary entry?

If all we mean by coercion is implicit type conversion, then the "operation which involves two arguments" part already seems over-specific: math.sqrt implicitly converts its argument to a float, for example.
msg397646 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-07-16 18:32
Searching further, none of the uses of "coerce" or "coercion" in the docs seem to be a good match for the definition in this glossary entry. For example, from ipaddress.rst:

> By default, attempting to create a network object with host bits set will
result in :exc:`ValueError` being raised. To request that the
additional bits instead be coerced to zero, the flag ``strict=False`` can
be passed to the constructor

and from configparser.rst:

> A convenience method which coerces the *option* in the specified *section* to an integer.

etc. I think we should just get rid of the glossary entry.
msg397689 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2021-07-17 03:42
OK with me.
msg397700 - (view) Author: Steven Hsu (StevenHsuYL) * Date: 2021-07-17 05:09
Thanks for your reply and suggestion.

I can totally understand your explanation about the definition of coercion.

In conclusion, I think this glossary entry may need some modification for better understanding, or simply be deleted.

So what's the next step?
Should I create a PR in GitHub?

Thanks for reply again.
msg397739 - (view) Author: Jack DeVries (jack__d) * Date: 2021-07-18 04:10
@StevenHsuYL yes, you can go ahead and create a PR for this if you'd like! Just follow the directions in the dev guide (link in sidebar).

I can't really tell for sure because I'm on my phone right now, but it looks like this might be your first time contributing to cpython; welcome! If you have any questions about the process, feel free to put them here.
msg397751 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-07-18 13:55
My one worry with removing the entry is that documentation of other projects may be referring to it via intersphinx. If we think this is likely to be a real problem, we could leave a stub entry, but I think it's  okay to go ahead and delete. To be on the safe side, I would suggest that only make the change for Python 3.11, though, and we don't backport the change to earlier versions of Python.
msg397983 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-07-22 12:18
New changeset c05a790693b3b00ac7cb5b96ad416ca9d8ecb14a by Steven Hsu in branch 'main':
bpo-44651: delete entry of "coercion" in Doc/glossary.rst (GH-27226)
https://github.com/python/cpython/commit/c05a790693b3b00ac7cb5b96ad416ca9d8ecb14a
msg397987 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2021-07-22 16:29
Closing. @StevenHsuYL: Thank you for the contribution!
History
Date User Action Args
2021-07-22 16:29:31mark.dickinsonsetstatus: open -> closed
resolution: fixed
messages: + msg397987

stage: patch review -> resolved
2021-07-22 12:18:35mark.dickinsonsetmessages: + msg397983
2021-07-18 13:55:50mark.dickinsonsetmessages: + msg397751
2021-07-18 13:05:58StevenHsuYLsetkeywords: + patch
stage: patch review
pull_requests: + pull_request25767
2021-07-18 04:10:39jack__dsetnosy: + jack__d
messages: + msg397739
2021-07-17 05:09:54StevenHsuYLsetmessages: + msg397700
2021-07-17 03:42:34terry.reedysetnosy: + terry.reedy
messages: + msg397689
2021-07-16 18:32:11mark.dickinsonsetmessages: + msg397646
2021-07-16 18:28:19mark.dickinsonsetmessages: + msg397645
2021-07-16 05:40:38serhiy.storchakasetnosy: + mark.dickinson
2021-07-16 05:11:26StevenHsuYLcreate