Type error in the section on type hints

[patrick-nicodemus]

Documentation

https://docs.python.org/3/library/typing.html

"This module provides runtime support for type hints.

Consider the function below:"

def moon_weight(earth_weight: float) -> str:
    return f'On the moon, you would weigh {earth_weight * 0.166} kilograms.'

This is technically incorrect. Kilograms are not a measure of weight, they are a measure of mass. If you are 60 kilograms on earth, you are 60 kilograms on the moon, not 10 kilograms. You weigh six times less on the moon because the moon has six times less mass than the Earth, not because you have six times less mass on the moon.

On Earth, "kilogram" is a common shorthand for "the weight, on Earth, of a kilogram." On Earth, it is fine to drop the phrase "on Earth" because everybody understands we are talking about the weight of a kilogram on Earth. Once we are planet hopping, it no longer makes sense to use "kilogram" as shorthand for "weight of a kilogram" because the weight of a kilogram changes everywhere we go.

This is the kind of type error that some languages use type systems to prevent (https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/units-of-measure) so it makes sense to be careful about types here.

Linked PRs

• gh-120661: improve example for basic type hints #120934
• [3.13] gh-120661: improve example for basic type hints (GH-120934) #120987
• [3.12] gh-120661: improve example for basic type hints (GH-120934) #120988

[nascheme]

The simple fix, IMHO, is to replace kilograms with newtons. That's the correct SI base unit for force. You could use "pounds" or "lbs" but there are two problems with that. One, pounds is either a unit of force or unit of mass, depending on who you ask. Second, it's part of an obsolete unit system. ;-)

[terryjreedy]

The float typing has nothing to do with kilograms versus newtons. The sentence is an example of something many would actually write. This should be closed.

[nineteendo]

Do we close this?

[JelleZijlstra]

I agree with changing this to avoid distracting readers who notice that the example is technically incorrect. The focus should be on the typing concepts, not the physics.

I'd rather not use newtons as @nascheme suggests; far fewer readers will be familiar with the concept.

Maybe instead use kilometer/miles conversion:

def distance(kilometers: float) -> str:
    return f"The distance is {kilometers} kilometers ({kilometers / 1.60934} miles)."

[AlexWaygood]

Thanks for the fix @picnixz! Hopefully our code examples are now type-safe from wherever you are in the solar system 🤞