Humanize time output

[andrewgsavage]

• Closes Create option to humanize time output  #2080
• Executed pre-commit run --all-files with no errors
• The change is fully covered by automated unit tests
• Documented in docs/ as appropriate
• Added an entry to the CHANGES file

@mmarras

I've made this it's own function as:

• the logic is different to to_compact
• there are instances where you may wish to use to_compact and to_human, or to_human alone

I'm open to other names than to_human!

[codspeed-hq]

CodSpeed Performance Report

Merging #2094 will not alter performance

_{Comparing andrewgsavage:human (ac21dc7) with master (861953e)}

Summary

✅ 437 untouched benchmarks

[mmarras]

Thanks for picking this up!

I've made this it's own function as:
the logic is different to to_compact
there are instances where you may wish to use to_compact and to_human, or to_human alone

I don’t fully understand how it’s fundamentally different from to_compact

to_compact() works by changing the SI prefix

to_human() works by changing the unit itself

so why not a merged signature? Can you explain what you mean with the logic is different? In my mind the intention is the same: get a compact magnitude (and there are two options to do that, si prefix scaling or base-unit scaling).

Hence why not as originally proposed integration with to_compact?

to_compact(mode=“prefix”) original behavior and default mode for backwards compatibility
to_compact(mode=“units”, unitcandidates=[])

would make conceptually sense to me. Also I see no reason why chaining those two variants wouldn’t work like below:

pseudocode:
Q(7300,”h”).to_compact(unitcand=[Q(1,“month”).u, Q(1,”d”).u]).to_compact()= 1 deci month

[andrewgsavage]

thanks for looking,

to_compact() works by changing the SI prefix
to_human() works by changing the unit itself

To me this is the key difference between the to_... functions. Though I don't think this is explained well at the moment. I added a page here comparing them https://pint--2289.org.readthedocs.build/en/2289/user/quantity-to.html#to-preferred-section

The logic difference is internal to the function. to_compact deals with SI prefixes so relies on them being powers of 1000 and deals with the unit to apply the unit having an exponent (eg m^3 -> mm^3) to find the best SI prefix. Whereas in to_human I've converted and picked the most suitable - so its more expenmsive to run.