Format¶

detroit.format(specifier: str) → Callable[[int | float], str]¶

Returns a new format function for the given string specifier. The returned function takes a number as the only argument, and returns a string representing the formatted number. The general form of a specifier is:

[[fill]align][sign][symbol][0][width][,][.precision][~][type]

The fill can be any character. The presence of a fill character is signaled by the align character following it, which must be one of the following:

> - Forces the field to be right-aligned within the available space. (Default behavior).
< - Forces the field to be left-aligned within the available space.
^ - Forces the field to be centered within the available space.
= - like >, but with any sign and symbol to the left of any padding.

The sign can be:

- - nothing for zero or positive and a minus sign for negative. (Default behavior.)
+ - a plus sign for zero or positive and a minus sign for negative.
( - nothing for zero or positive and parentheses for negative.
(space) - a space for zero or positive and a minus sign for negative.

The symbol can be:

$ - apply currency symbols per the locale definition.
# - for binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.

The zero (0) option enables zero-padding; this implicitly sets fill to 0 and align to =. The width defines the minimum field width; if not specified, then the width will be determined by the content. The comma (,) option enables the use of a group separator, such as a comma for thousands.

The available type values are:

e - exponent notation.
f - fixed point notation.
g - either decimal or exponent notation, rounded to significant digits.
r - decimal notation, rounded to significant digits.
s - decimal notation with an SI prefix, rounded to significant digits.
% - multiply by 100, and then decimal notation with a percent sign.
p - multiply by 100, round to significant digits, and then decimal notation with a percent sign.
b - binary notation, rounded to integer.
o - octal notation, rounded to integer.
d - decimal notation, rounded to integer.
x - hexadecimal notation, using lower-case letters, rounded to integer.
X - hexadecimal notation, using upper-case letters, rounded to integer.
c - character data, for a string of text.

Depending on the type, the precision either indicates the number of digits that follow the decimal point (types f and %), or the number of significant digits (types (space), e, g, r, s and p). If the precision is not specified, it defaults to 6 for all types except (space) (none), which defaults to 12. Precision is ignored for integer formats (types b, o, d, x, and X) and character data (type c)

The ~ option trims insignificant trailing zeros across all format types. This is most commonly used in conjunction with types r, e, s and %.

Parameters:: specifier (str) – Specifier
Returns:: Format function
Return type:: Callable[[int | float], str]

Examples

>>> d3.format(".0%")(0.123) # rounded percentage
'12%'
>>> d3.format("+20")(42) # space-filled and signed
'                 +42'
>>> d3.format(".^20")(42) # dot-filled and centered
'.........42.........'
>>> d3.format(".2s")(42e6) # SI-prefix with two significant digits
'42M'
>>> d3.format("#x")(48879) # prefixed lowercase hexadecimal
'0xbeef'
>>> d3.format(",.2r")(4223) # grouped thousands with two significant digits
'4,200'
>>> d3.format("s")(1500)
'1.50000k'
>>> d3.format("~s")(1500)
'1.5k'
>>> d3.format(".2")(42)
'42'
>>> d3.format(".2")(4.2)
'4.2'
>>> d3.format(".1")(42)
'4e+01'
>>> d3.format(".1")(4.2)
'4'

detroit.format_default_locale(definition: dict) → Locale¶

Equivalent to d3.format, except it returns a new Locale with locale.format and locale.format_prefix

Parameters:: definition (dict) – Definition (todo : add more explanations)
Returns:: Locale with definition parameters
Return type:: Locale

detroit.format_prefix(specifier: str, value: int | float) → Callable[[int | float], str]¶

Equivalent to d3.format, except the returned function will convert values to the units of the appropriate SI prefix for the specified numeric reference value before formatting in fixed point notation. The following prefixes are supported:

y - yocto, $10^{-24}$
z - zepto, $10^{-21}$
a - atto, $10^{-18}$
f - femto, $10^{-15}$
p - pico, $10^{-12}$
n - nano, $10^{-9}$
µ - micro, $10^{-6}$
m - milli, $10^{-3}$
(none) - $1$
k - kilo, $10^{3}$
M - mega, $10^{6}$
G - giga, $10^{9}$
T - tera, $10^{12}$
P - peta, $10^{15}$
E - exa, $10^{18}$
Z - zetta, $10^{21}$
Y - yotta, $10^{24}$

Parameters:

specifier (str) – Specifier
value (int | float) – Numeric reference

Returns:

Format function

Return type:

Callable[[int | float], str]

Examples

>>> f = d3.format_prefix(",.0", 1e-6)
>>> f(0.00042)
'420µ'
>>> f(0.0042)
'4,200µ'

detroit.precision_fixed(step: int | float) → int¶

Returns a suggested decimal precision for fixed point notation given the specified numeric step value. The step represents the minimum absolute difference between values that will be formatted.

Parameters:: step (int | float)
Returns:: Decimal precision
Return type:: int

Examples

>>> p = d3.precision_fixed(0.5)
>>> f = d3.format(f".{p}f")
>>> f(1)
'1.0'
>>> f(1.5)
'1.5'
>>> f(2)
'2.0'

detroit.precision_prefix(step: int | float, value: int | float) → int¶

Returns a suggested decimal precision for use with d3.format_prefix given the specified numeric step and reference value. The step represents the minimum absolute difference between values that will be formatted, and value determines which SI prefix will be used.

Parameters:

step (int | float) – Specific numeric value
value (int | float) – Reference value

Returns:

Decimal precision

Return type:

int

Examples

>>> p = d3.precision_prefix(1e5, 1.3e6)
>>> f = d3.format_prefix(f".{p}", 1.3e6)
>>> f(1.1e6)
'1.1M'
>>> f(1.2e6)
'1.2M'
>>> f(1.3e6)
'1.3M'

detroit.precision_round(step: int | float, max_val: int | float) → int¶

Returns a suggested decimal precision for format types that round to significant digits given the specified numeric step and max values. The step represents the minimum absolute difference between values that will be formatted, and the max represents the largest absolute value that will be formatted.

Parameters:

step (int | float) – Specific numeric value
max_val (int | float) – The largest absolute value that will be formatted

Returns:

Decimal precision

Return type:

int

Examples

>>> p = d3.precision_round(0.01, 1.01)
>>> f = d3.format(f".{p}r")
>>> f(0.99)
'0.990'
>>> f(1.0)
'1.00'
>>> f(1.01)
'1.01'