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

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.

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.

OK with me.

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.

@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.

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.

New changeset c05a790 by Steven Hsu in branch 'main':
bpo-44651: delete entry of "coercion" in Doc/glossary.rst (GH-27226)
c05a790

Closing. @StevenHsuYL: Thank you for the contribution!