Metadata-Version: 2.1
Name: cs.units
Version: 20220311
Summary: Functions for decomposing nonnegative integers according to various unit scales and also parsing support for values written in scales.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: GNU General Public License v3 or later (GPLv3+)
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Description-Content-Type: text/markdown

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.

