Unit conversion methods and their names

[andrewgsavage]

There's discussion starting #9 (comment) about unit conversion and the methods.

in short:
What should the name of a unit conversion function that returns a quantity be?
Potential names:

• asquantity(quantity, new_unit) could be used but would combine initialising and conversion in the same function.
• asunit could be expected to return a unit.
• convert has debateable concerns over name collision.
• uconvert isn't a nice name
• convert_quantity is my suggestion, including the return type in the name.

Should a unit conversion function that returns the value exist, and what should it be named?

• The aforementioned function could be used, and then use Quantity.value, so this doesn't need to exist in the initial release.
  Potential names:
• uconvert_value
• convert_value is my suggestion

Should a general function exist for converting between units? ie convert(unit1, unit2, value)

[nstarman]

My current thoughts:

• asquantity: IMO its fine for the function to be flexible and call the official unit conversion function, like numpy.asarray can internally call numpy.astype for dtype conversion.
• asunit 👎
• convert 👎 Explicit is better than implicit. We're doing unit conversion, this name is for any conversion.
• uconvert 👍. Explicit is better than implicit. Readability counts.
• convert_quantity 🤷 it's ambiguous IMO. What on quantities are we converting — the class type, the unit, the dtype? This name works equally well for inter-library quantity type conversion, unit conversion, and dtype conversion. Yes the context of other functions is important, but also each function name should stand on its own.
• convert_unit_on_quantity: 👎 0 ambiguity, but not concise. Straw man counterexample to all the concise names above 😆

Should a unit conversion function that returns the value exist, and what should it be named?

Yes.
The same thoughts about name ambiguity apply.

[andrewgsavage]

• uconvert 👍. Explicit is better than implicit. Readability counts.

so make it units_convert!

[nstarman]

Then does it convert unit (e.g. km to kpc) or units on quantity?
Funnily enough this is similar to uconvert, however the fact that it's "more" explicit also makes it more ambiguous.