How python-humanize/humanize works
Purpose and Public Entry Point
humanize is a distributable Python library that converts numeric, file-size, date/time, and list values into human-readable strings. Consumers primarily import humanize; the package facade re-exports public APIs from domain modules.
• src/humanize/__init__.py
• pyproject.toml
Formatting Domains
The library is organized as independent, importable formatting domains rather than a service or application runtime:
• Number wording, grouping, fractions, scientific notation, and ordinal-like formatting: src/humanize/number.py
• File-size and throughput unit formatting, including decimal, binary, and GNU styles: src/humanize/filesize.py
• Natural dates, relative time, and precise durations: src/humanize/time.py
• Natural-language list joining: src/humanize/lists.py
Core Formatting Flow
Callers provide Python primitives (int, float, strings where supported, date/datetime/timedelta, or iterables). Domain functions normalize and classify the value, select units/word forms and formatting rules, then return a localized display string. There is no persistence, request lifecycle, or network boundary; outputs are synchronous Python strings.
• src/humanize/number.py
• src/humanize/time.py
• src/humanize/filesize.py
Localization Boundary
Gettext-based runtime localization is centralized in i18n. Applications explicitly activate a locale (optionally from a caller-provided translation path); formatting modules consume translated singular/plural/contextual phrases. Deactivation restores the default translation context.
• src/humanize/i18n.py
• src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po
• src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po
Translation Assets and Maintenance
Bundled per-locale .po catalogs are package data and define language-specific phrasing/pluralization. Translation updates may be generated or refreshed through scripts, making gettext tooling a development/maintenance dependency rather than a runtime external service.
• src/humanize/locale
• scripts/generate-translation-binaries.sh
• scripts/update-translations.sh
Runtime, Packaging, and Delivery
The material runtime is Python, packaged with a src/ layout and typed-package marker. Distribution is through PyPI; documentation is built with MkDocs/Read the Docs, while GitHub Actions runs tests, linting, benchmarks, documentation, and releases. No database, web server, or external API is part of the library architecture.
• pyproject.toml
• src/humanize/py.typed
• .github/workflows/release.yml
• mkdocs.yml
Main entry points: __init__.py humanize package facade · locale Locale catalogs · i18n.py Localization runtime · pyproject.toml Package definition
Components 16
Python Library
Synchronous formatting APIs packaged from src/.
- humanize package facade · Re-exports the library's public formatting APIs.
src/humanize/__init__.py - Number formatting · Words, grouping, fractions, scientific notation, and ordinals.
src/humanize/number.py - File-size formatting · Decimal, binary, GNU, and throughput unit formatting.
src/humanize/filesize.py - Date and time formatting · Natural dates, relative time, and precise durations.
src/humanize/time.py - List formatting · Natural-language iterable joining.
src/humanize/lists.py
Localization
Gettext runtime context and bundled language catalogs.
- Localization runtime · Activates, deactivates, and supplies translation context.
src/humanize/i18n.py - Locale catalogs · Per-locale gettext phrases and plural rules.
src/humanize/locale - Russian catalog
src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po - Chinese catalog
src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po - Translation maintenance · Refreshes catalogs and generates translation binaries.
scripts/update-translations.sh
Packaging & Delivery
Distribution, documentation, and release automation.
- Package definition · Defines src-layout distribution and package data.
pyproject.toml - Typing marker
src/humanize/py.typed - Documentation build
mkdocs.yml - Release workflow · Runs delivery automation for the distributable library.
.github/workflows/release.yml
Other components
- Library consumers · Provide primitive values and receive display strings.
- PyPI distribution
Connections 20
- Library consumers → humanize package facade: import and call
- humanize package facade → Number formatting: re-exports
- humanize package facade → File-size formatting: re-exports
- humanize package facade → Date and time formatting: re-exports
- humanize package facade → List formatting: re-exports
- Number formatting → Localization runtime: translated wording
- File-size formatting → Localization runtime: translated units
- Date and time formatting → Localization runtime: translated phrases
- List formatting → Localization runtime: translated joining
- Localization runtime → Locale catalogs: loads active locale
- Locale catalogs → Russian catalog: contains
- Locale catalogs → Chinese catalog: contains
- Translation maintenance → Locale catalogs: updates and compiles
- Package definition → humanize package facade: packages
- Package definition → Locale catalogs: includes as package data
- Package definition → Typing marker: ships typing metadata
- Documentation build → humanize package facade: documents API
- Release workflow → Package definition: builds and releases
- Release workflow → Documentation build: builds documentation
- Release workflow → PyPI distribution: publishes