cs-units 20250915

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 20250915: Drop slots=True from dataclass, too new.

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

Short summary:

• decimal: Decompose a nonnegative integer n into human decimal counts (kilo etc).
• decompose: Decompose a nonnegative integer n into counts by unit from scale. Returns a Decomposed list of (modulus,UnitStep) in order from smallest unit upward.
• decompose_time: OBSOLETE version of human_time, suggestion: human_time(n).
• Decomposed: A list of (modulus,UnitStep) 2-tuples representing a decomposed value.
• geek: Decompose a nonnegative integer n into geek bytes sizes (kibibytes etc).
• geek_bytes: Decompose a nonnegative integer n into geek bytes sizes (kibibytes etc).
• human: Decompose a nonnegative integer n into human decimal counts (kilo etc).
• human_bytes: Decompose a nonnegative integer n into human bytes sizes (kilobytes etc).
• human_time: Decompose a nonnegative integer n into human time (hours etc).
• multiparse: Parse an integer followed by an optional scale and return computed value. Returns the parsed value and the new offset.
• parse: Parse an integer followed by an optional scale and return computed value. Returns the parsed value and the new offset. This is a shim for UnitScale.get_term(s,offset).
• transcribe: Transcribe a nonnegative integer n against scale. This is just a shim for UnitScale.transcribe, itself a shim for Decomposed.__str__.
• transcribe_bytes_decompose: OBSOLETE version of transcribe_bytes_decompose, suggestion: transcribe(n,'decimal') or str(human(n)).
• transcribe_bytes_geek: OBSOLETE version of transcribe_bytes_geek, suggestion: transcribe(n,'geek_bytes',1) or str(geek_bytes(n)).
• transcribe_time: OBSOLETE version of transcribe_time, suggestion: transcribe(n,'human_time',3) or str(human_time(n)).
• UnitScale: A representation of a unit scale as a list of unit terms and scale factors.
• UnitStep: A scale step for a unit scale. The last UnitStep in a scale should have factor=0.

Module contents:

• decimal(n): Decompose a nonnegative integer n into human decimal counts (kilo etc).

• decompose(n, scale: cs.units.UnitScale) -> cs.units.Decomposed: Decompose a nonnegative integer n into counts by unit from scale. Returns a Decomposed list of (modulus,UnitStep) in order from smallest unit upward.

  Parameters:

  • n: a nonnegative integer.
  • scale: a UnitScale (or promotable)

• decompose_time(n): OBSOLETE version of human_time, suggestion: human_time(n)

  Decompose a nonnegative integer n into human time (hours etc).

• class Decomposed(builtins.list): A list of (modulus,UnitStep) 2-tuples representing a decomposed value.

Decomposed.__float__(self) -> float: The total value as a float.

Decomposed.__int__(self) -> int: The total value as an int.

Decomposed.__str__(self, max_parts=None, *, skip_zero=False, sep='', no_pad=False) -> str: Transcribe a nonnegative integer n against scale.

Parameters:

• max_parts: the maximum number of components to transcribe.
• skip_zero: omit components of value 0.
• sep: separator between words, default: ''.

Decomposed.sum(self): Return the total value represented by this Decomposed.

• geek(n): Decompose a nonnegative integer n into geek bytes sizes (kibibytes etc).

• geek_bytes(n): Decompose a nonnegative integer n into geek bytes sizes (kibibytes etc).

• human(n): Decompose a nonnegative integer n into human decimal counts (kilo etc).

• human_bytes(n): Decompose a nonnegative integer n into human bytes sizes (kilobytes etc).

• human_time(n): Decompose a nonnegative integer n into human time (hours etc).

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

• parse(s: str, scale: cs.units.UnitScale, offset=0): Parse an integer followed by an optional scale and return computed value. Returns the parsed value and the new offset. This is a shim for UnitScale.get_term(s,offset).

  Parameters:

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

• transcribe(n, scale: cs.units.UnitScale, max_parts=None, *, skip_zero=False, sep='', no_pad=False): Transcribe a nonnegative integer n against scale. This is just a shim for UnitScale.transcribe, itself a shim for Decomposed.__str__.

  Parameters:

  • n: a nonnegative integer.
  • scale: a UnitScale (or promotable)
  • max_parts: the maximum number of components to transcribe.
  • skip_zero: omit components of value 0.
  • sep: separator between words, default: ''.

• transcribe_bytes_decompose(n, max_parts=1, **kw): OBSOLETE version of transcribe_bytes_decompose, suggestion: transcribe(n,'decimal') or str(human(n))

  Transcribe a nonnegative integer n against DECIMAL_BYTES_SCALE.

• transcribe_bytes_geek(n, max_parts=1, **kw): OBSOLETE version of transcribe_bytes_geek, suggestion: transcribe(n,'geek_bytes',1) or str(geek_bytes(n))

  Transcribe a nonnegative integer n against BINARY_BYTES_SCALE.

• transcribe_time(n, max_parts=3, **kw): OBSOLETE version of transcribe_time, suggestion: transcribe(n,'human_time',3) or str(human_time(n))

  Transcribe a nonnegative integer n against TIME_SCALE.

• class UnitScale(cs.deco.Promotable): A representation of a unit scale as a list of unit terms and scale factors.

UnitScale.decompose(self, n) -> cs.units.Decomposed: Decompose a nonnegative integer n into counts by unit. Returns a Decomposed 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.

UnitScale.from_str(scale_name: str): Return a UnitScale from its name.

UnitScale.get_term(self, s: str, offset=0) -> Tuple[int, int]: Parse a decimal values possibly followed by a unit name from s at offset. Return a (value,offset) 2-tuple.

Parameters:

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

UnitScale.transcribe(self, n, max_parts=None, *, skip_zero=False, sep='', no_pad=False): Transcribe n according to this scale. Parameters are passed to Decomposed.__str__.

• class UnitStep: A scale step for a unit scale. The last UnitStep in a scale should have factor=0.

UnitStep.__iter__(self): for unpacking assignment

Release Log

Release 20250915: Drop slots=True from dataclass, too new.

Release 20250601: Fix @OBSOLETE definition of decompose_time.

Release 20250528:

• Big refactor so that we can just str() the result of a decompose.
• New Decomposed, UnitStep, UnitScale classes.

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.