pdstools.utils.number_format
============================

.. py:module:: pdstools.utils.number_format

.. autoapi-nested-parse::

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

.. autoapisummary::

   pdstools.utils.number_format.NumberFormat


Module Contents
---------------

.. py: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.

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

   .. rubric:: 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'


   .. py:attribute:: decimals
      :type:  int
      :value: 0



   .. py:attribute:: scale_by
      :type:  float
      :value: 1.0



   .. py:attribute:: compact
      :type:  bool
      :value: False



   .. py:attribute:: locale
      :type:  str
      :value: 'en_US'



   .. py:attribute:: suffix
      :type:  str
      :value: ''



   .. py:method:: format_value(value: NumericValue) -> str

      Format a single numeric value.

      :param value: The value to format. Returns "" for None or NaN.

      :returns: Formatted string representation.
      :rtype: str



   .. py:method:: _format_standard(num: float) -> str

      Format with locale-aware thousand/decimal separators.



   .. py:method:: _format_compact(num: float) -> str

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



   .. py:method:: to_pandas_format() -> Union[str, Callable[[NumericValue], str]]

      Convert to pandas Styler format specification.

      :returns: Format string or callable for `pandas.Styler.format()`.
      :rtype: str or callable



   .. py:method:: apply_to_gt(gt: great_tables.GT, columns: list[str]) -> great_tables.GT

      Apply formatting to a great_tables GT object.

      :param gt: The GT object to format.
      :param columns: Column names to apply formatting to.

      :returns: The GT object with formatting applied.
      :rtype: GT



   .. py:method:: to_polars_expr(column: str) -> polars.Expr

      Create a Polars expression that formats a column as strings.

      :param column: Column name to format.

      :returns: Expression producing formatted string values.
      :rtype: pl.Expr



   .. py:method:: format_polars_column(df: polars.DataFrame, column: str, output_column: Optional[str] = None) -> polars.DataFrame

      Add a formatted string column to a DataFrame.

      :param df: Source DataFrame.
      :param column: Column to format.
      :param output_column: Name for the formatted column. Defaults to "{column}_formatted".

      :returns: DataFrame with the formatted column added.
      :rtype: pl.DataFrame