dollarfmt 0.1.0

A focused, dependency-light Python library for U.S. dollar currency formatting

dollarfmt

A focused, dependency-light Python library for U.S. dollar currency formatting.

Provides standard formatting ($1,234.56), compact notation with automatic unit scaling ($1.2K, $3.4M, $2.1B, $1.0T), and generation of matching Excel and PowerPoint-compatible format strings.

Features

• 🎯 Simple & Focused: Only USD formatting, no locale complexity
• 📊 Excel Integration: Generate format strings for Excel/PowerPoint
• 🔢 Precise: Uses Decimal for accurate financial calculations
• 🎨 Flexible: Standard and compact notation with customizable decimals
• 🚀 Zero Dependencies: Only uses Python standard library
• ✅ Well Tested: 100% test coverage

Installation

pip install dollarfmt

Quick Start

import dollarfmt

# Standard formatting
dollarfmt.fmt(1234.56)           # '$1,234.56'
dollarfmt.fmt(-1234.56)          # '-$1,234.56'
dollarfmt.fmt(1000, decimals=0)  # '$1,000'

# Compact notation with automatic units
dollarfmt.fmt_short(1200)           # '$1.2K'
dollarfmt.fmt_short(3400000)       # '$3.4M'
dollarfmt.fmt_short(2100000000)   # '$2.1B'
dollarfmt.fmt_short(1500000000000)  # '$1.5T'

# Get unit and scaled value
value, unit = dollarfmt.auto_unit(3400000)  # (Decimal('3.4'), 'M')

# Excel format strings
dollarfmt.excel_fmt()                    # '"$"#,##0.00'
dollarfmt.excel_fmt_short(unit="M")      # '"$"#,##0.0,,"M"'

API Reference

Core Functions

fmt(amount, decimals=2, strip_trailing_zeros=False)

Format a dollar amount with standard notation.

Parameters:

• amount (float | int | Decimal): The dollar amount to format
• decimals (int): Number of decimal places (default: 2)
• strip_trailing_zeros (bool): Remove trailing zeros after decimal point

Returns: Formatted string like $1,234.56

Examples:

dollarfmt.fmt(1234.56)                        # '$1,234.56'
dollarfmt.fmt(-1234.56)                       # '-$1,234.56'
dollarfmt.fmt(1000.00, strip_trailing_zeros=True)  # '$1,000'
dollarfmt.fmt(1234.567, decimals=3)           # '$1,234.567'

fmt_short(amount, decimals=1, strip_trailing_zeros=True)

Format a dollar amount with compact notation using K/M/B/T units.

Automatically chooses the appropriate unit based on magnitude:

• < 1,000: $950
• < 1,000,000: $1.2K
• < 1,000,000,000: $3.4M
• < 1,000,000,000,000: $2.1B
• >= 1,000,000,000,000: $1.0T

Parameters:

• amount (float | int | Decimal): The dollar amount to format
• decimals (int): Number of decimal places for scaled values (default: 1)
• strip_trailing_zeros (bool): Remove trailing zeros after decimal point (default: True)

Returns: Formatted string with compact notation

Examples:

dollarfmt.fmt_short(950)                      # '$950'
dollarfmt.fmt_short(1200)                     # '$1.2K'
dollarfmt.fmt_short(1000, strip_trailing_zeros=False)  # '$1.0K'
dollarfmt.fmt_short(-3400000)               # '-$3.4M'
dollarfmt.fmt_short(2100000000)            # '$2.1B'

auto_unit(amount)

Determine the appropriate unit and scaled value for compact formatting.

Parameters:

• amount (float | int | Decimal): The dollar amount to analyze

Returns: Tuple of (scaled_value, unit) where unit is "", "K", "M", "B", or "T"

Examples:

dollarfmt.auto_unit(950)           # (Decimal('950'), '')
dollarfmt.auto_unit(1200)          # (Decimal('1.2'), 'K')
dollarfmt.auto_unit(3400000)     # (Decimal('3.4'), 'M')
dollarfmt.auto_unit(2100000000) # (Decimal('2.1'), 'B')

Excel Integration Functions

excel_fmt(decimals=2)

Generate an Excel format string for standard dollar notation.

Parameters:

• decimals (int): Number of decimal places (default: 2)

Returns: Excel format string

Examples:

dollarfmt.excel_fmt()           # '"$"#,##0.00'
dollarfmt.excel_fmt(decimals=0) # '"$"#,##0'
dollarfmt.excel_fmt(decimals=3) # '"$"#,##0.000'

excel_fmt_short(decimals=1, unit="auto")

Generate Excel format strings for compact dollar notation with K/M/B/T units.

Parameters:

• decimals (int): Number of decimal places (default: 1)
• unit (str): Specific unit ("K", "M", "B", "T") or "auto" for all formats

Returns:

• If unit is specified: Single format string
• If unit="auto": Dictionary with all format strings

Examples:

dollarfmt.excel_fmt_short(unit="K")  # '"$"#,##0.0,"K"'
dollarfmt.excel_fmt_short(unit="M")  # '"$"#,##0.0,,"M"'
dollarfmt.excel_fmt_short(unit="B")  # '"$"#,##0.0,,,"B"'

# Get all formats
formats = dollarfmt.excel_fmt_short(unit="auto")
# {
#     "K": '"$"#,##0.0,"K"',
#     "M": '"$"#,##0.0,,"M"',
#     "B": '"$"#,##0.0,,,"B"',
#     "T": '"$"#,##0.0,,,,"T"'
# }

Excel Format String Reference

Unit	Divisor	Excel Format String	Example Value	Displays As
(none)	1	"$"#,##0.00	1234.56	$1,234.56
K	1,000	"$"#,##0.0,"K"	1234567	$1,234.6K
M	1,000,000	"$"#,##0.0,,"M"	1234567890	$1,234.6M
B	1,000,000,000	"$"#,##0.0,,,"B"	1234567890123	$1,234.6B
T	1,000,000,000,000	"$"#,##0.0,,,,"T"	1234567890123456	$1,234.6T

Note: In Excel format strings, each comma (,) after the number format divides the value by 1,000.

Using with Excel/PowerPoint

Python-PPTX Example

from pptx import Presentation
from pptx.util import Inches
import dollarfmt

# Create presentation
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[5])

# Add text with formatted dollar amount
textbox = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(3), Inches(1))
text_frame = textbox.text_frame
text_frame.text = f"Revenue: {dollarfmt.fmt_short(3400000)}"

prs.save('presentation.pptx')

OpenPyXL Example

from openpyxl import Workbook
import dollarfmt

wb = Workbook()
ws = wb.active

# Write value and apply format
ws['A1'] = 1234567
ws['A1'].number_format = dollarfmt.excel_fmt_short(unit="K")

# Value displays as: $1,234.6K
wb.save('workbook.xlsx')

Technical Details

Rounding

All functions use banker's rounding (round half to even) via Decimal.quantize() with ROUND_HALF_EVEN. This is the standard rounding method for financial calculations.

dollarfmt.fmt(1.125, decimals=2)  # '$1.12' (rounds to even)
dollarfmt.fmt(1.135, decimals=2)  # '$1.14' (rounds to even)

Precision

All calculations use Python's Decimal type for precise financial arithmetic, avoiding floating-point errors.

Negative Values

Negative values are formatted with the minus sign before the dollar sign:

dollarfmt.fmt(-1234.56)        # '-$1,234.56'
dollarfmt.fmt_short(-3400000) # '-$3.4M'

Requirements

• Python 3.10+
• No external dependencies (uses only standard library)

Development

Setup

# Clone repository
git clone https://github.com/danjellesma/dollarfmt.git
cd dollarfmt

# Create virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
uv pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=dollarfmt --cov-report=html

# Run specific test file
pytest dollarfmt/tests/test_core.py

Code Quality

# Format code
ruff format

# Lint code
ruff check

# Type checking
mypy dollarfmt

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Dan Jellesma

Changelog

0.1.0 (2024)

• Initial release
• Core formatting functions (fmt, fmt_short, auto_unit)
• Excel integration functions (excel_fmt, excel_fmt_short)
• Comprehensive test suite
• Full documentation