cs.units 20220311

Functions for decomposing nonnegative integers according to various unit scales and also parsing support for values written in scales.

Functions for decomposing nonnegative integers according to various unit scales and also parsing support for values written in scales.

Latest release 20220311: Naming update: rename human* to decompose* to clarify that these decompose a number into a sequence of values on a scale.

Presupplied scales:

• BINARY_BYTES_SCALE: Binary units of (B)ytes, KiB, MiB, GiB etc.
• DECIMAL_BYTES_SCALE: Decimal units of (B)ytes, KB, MB, GB etc.
• DECIMAL_SCALE: Unit suffixes K, M, G etc.
• TIME_SCALE: Units of (s)econds, (m)inutes, (h)ours, (d)ays and (w)eeks.
• UNSCALED_SCALE: no units

Function combine(components, scale)

Combine a sequence of value components as from decompose() into an integer.

Function decompose(n, scale)

Decompose a nonnegative integer n into counts by unit from scale. Returns a list of (modulus,UnitStep) in order from smallest unit upward.

Parameters:

• n: a nonnegative integer.
• scale: a sequence of UnitStep or (factor,unit[,max_width]) where factor is the size factor to the following scale item and unit is the designator of the unit.

Function decompose_bytes(n)

Decompose a nonnegative integer n into counts by unit from DECIMAL_BYTES_SCALE.

Function decompose_time(n, scale=None)

Decompose a nonnegative integer n into counts by unit from TIME_SCALE.

Function geek_bytes(n)

Decompose a nonnegative integer n into counts by unit from BINARY_BYTES_SCALE.

Function human(*args, **kwargs)

Obsolete shim for decompose().

Function human_bytes(*args, **kwargs)

Obsolete shim for decompose_bytes().

Function human_time(*args, **kwargs)

Obsolete shim for decompose_time().

Function multiparse(s, scales, offset=0)

Parse an integer followed by an optional scale and return computed value. Returns the parsed value and the new offset.

Parameters:

• s: the string to parse.
• scales: an iterable of scale arrays of (factor, unit_name).
• offset: starting position for parse.

Function parse(s, scale, offset=0)

Parse an integer followed by an optional scale and return computed value. Returns the parsed value and the new offset.

Parameters:

• s: the string to parse.
• scale: a scale array of (factor, unit_name).
• offset: starting position for parse.

Function transcribe(n, scale, max_parts=None, skip_zero=False, sep='', no_pad=False)

Transcribe a nonnegative integer n against scale.

Parameters:

• n: a nonnegative integer.
• scale: a sequence of (factor, unit) where factor is the size factor to the follow scale and unit is the designator of the unit.
• max_parts: the maximum number of components to transcribe.
• skip_zero: omit components of value 0.
• sep: separator between words, default: ''.

Function transcribe_bytes_decompose(n, max_parts=1, **kw)

Transcribe a nonnegative integer n against DECIMAL_BYTES_SCALE.

Function transcribe_bytes_geek(n, max_parts=1, **kw)

Transcribe a nonnegative integer n against BINARY_BYTES_SCALE.

Function transcribe_time(n, max_parts=3, **kw)

Transcribe a nonnegative integer n against TIME_SCALE.

Class UnitStep(UnitStep, builtins.tuple)

A namedtuple expressing a scale step for a unit scale. The last tuple in a scale should have factor=0.

Attributes:

• factor: the scale factor for the unit in terms of the following unit. For example, 60 for seconds because there are 60 in the next unit, minutes.
• unit: the textual abbreviation for the unit. For example, 's' for seconds.
• max_width: the maximum width for a modulus of this unit. For example, 2 for seconds because the maximum value is less than 100.

Release Log

Release 20220311: Naming update: rename human* to decompose* to clarify that these decompose a number into a sequence of values on a scale.

Release 20210809: Update parse() for new structure in the scale definitions.

Release 20210717: transcribe: pad units by default, produces less jitter in dynamic displays like progress bars.

Release 20201025: transcribe: use str(count_i), not str(count) if count == count_i.

Release 20200718: Use str.isalpha to recognise "unit" words instead of string.ascii_letters (uses new cs.lex.get_chars "callable gochars" mode).

Release 20200626: transcribe: use "%.1f" to format the count if it is not == int(count) ==> a float-with-fraction.

Release 20200613: New UNSCALED_SCALE for no units.

Release 20190220: Dependency fix.

Release 20181228: Initial PyPI release.