pdstools.utils.number_format¶

Number formatting utilities inspired by great_tables fmt_number.

This module provides a NumberFormat class that defines how numbers should be formatted, with a subset of parameters from great_tables’ fmt_number. Formats can be translated to different output targets (great_tables, pandas Styler, Polars expressions).

See: https://posit-dev.github.io/great-tables/reference/vals.fmt_number.html

Classes¶

NumberFormat

Specification for formatting numeric values.

Module Contents¶

class NumberFormat¶

Specification for formatting numeric values.

Inspired by great_tables’ fmt_number, this immutable class defines formatting options that translate to multiple output targets.

Parameters:

decimals (int, default 0) – Number of decimal places.
scale_by (float, default 1.0) – Multiplier applied before formatting (use 100 for percentages).
compact (bool, default False) – Use compact notation (K, M, B, T).
locale (str, default "en_US") – Locale for separators. Supports “en_US” and “de_DE”.
suffix (str, default "") – String appended after the number (e.g., “%”).

Examples

>>> NumberFormat(decimals=2).format_value(1234.567)
'1,234.57'

>>> NumberFormat(decimals=1, scale_by=100, suffix="%").format_value(0.1234)
'12.3%'

>>> NumberFormat(compact=True).format_value(1234567)
'1M'

decimals: int = 0¶

scale_by: float = 1.0¶

compact: bool = False¶

locale: str = 'en_US'¶

suffix: str = ''¶

format_value(value: NumericValue) → str¶

Format a single numeric value.

Parameters:: value (NumericValue) – The value to format. Returns “” for None or NaN.
Returns:: Formatted string representation.
Return type:: str

_format_standard(num: float) → str¶

Format with locale-aware thousand/decimal separators.

Parameters:: num (float)
Return type:: str

_format_compact(num: float) → str¶

Format in compact notation (K/M/B/T).

Parameters:: num (float)
Return type:: str

to_pandas_format() → str | Callable[[NumericValue], str]¶

Convert to pandas Styler format specification.

Returns:: Format string or callable for pandas.Styler.format().
Return type:: str or callable

apply_to_gt(gt: great_tables.GT, columns: list[str]) → great_tables.GT¶

Apply formatting to a great_tables GT object.

Parameters:

gt (great_tables.GT) – The GT object to format.
columns (list[str]) – Column names to apply formatting to.

Returns:

The GT object with formatting applied.

Return type:

to_polars_expr(column: str) → polars.Expr¶

Create a Polars expression that formats a column as strings.

Parameters:: column (str) – Column name to format.
Returns:: Expression producing formatted string values.
Return type:: pl.Expr

format_polars_column(df: polars.DataFrame, column: str, output_column: str | None = None) → polars.DataFrame¶

Add a formatted string column to a DataFrame.

Parameters:

df (polars.DataFrame) – Source DataFrame.
column (str) – Column to format.
output_column (Optional[str]) – Name for the formatted column. Defaults to “{column}_formatted”.

Returns:

DataFrame with the formatted column added.

Return type:

pl.DataFrame