# python-humanize/humanize architecture

> Architecture diagram of the GitHub repository python-humanize/humanize, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/python-humanize/humanize
- Repository: https://github.com/python-humanize/humanize

## Overview

#### 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: [`src/humanize/__init__.py`](https://github.com/python-humanize/humanize/blob/main/src/humanize/__init__.py) (humanize package facade), [`src/humanize/locale`](https://github.com/python-humanize/humanize/tree/main/src/humanize/locale) (Locale catalogs), [`src/humanize/i18n.py`](https://github.com/python-humanize/humanize/blob/main/src/humanize/i18n.py) (Localization runtime), [`pyproject.toml`](https://github.com/python-humanize/humanize/blob/main/pyproject.toml) (Package definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Python Library"]
  node_facade["humanize package facade<br/>public API<br/>[__init__.py]"]
  node_number["Number formatting<br/>formatting domain<br/>[number.py]"]
  node_filesize["File-size formatting<br/>formatting domain<br/>[filesize.py]"]
  node_time["Date and time formatting<br/>formatting domain<br/>[time.py]"]
  node_lists["List formatting<br/>formatting domain<br/>[lists.py]"]
end

subgraph group_localization["Localization"]
  node_i18n{{"Localization runtime<br/>gettext boundary<br/>[i18n.py]"}}
  node_catalogs["Locale catalogs<br/>package data"]
  node_po_ru["Russian catalog<br/>translation asset<br/>[humanize.po]"]
  node_po_zh["Chinese catalog<br/>translation asset<br/>[humanize.po]"]
  node_translation_scripts["Translation maintenance<br/>development scripts"]
end

subgraph group_delivery["Packaging &amp; Delivery"]
  node_package["Package definition<br/>Python packaging<br/>[pyproject.toml]"]
  node_typed_marker["Typing marker<br/>package metadata<br/>[py.typed]"]
  node_docs["Documentation build<br/>MkDocs configuration<br/>[mkdocs.yml]"]
  node_release["Release workflow<br/>GitHub Actions<br/>[release.yml]"]
end

node_callers(("Library consumers<br/>Python callers"))
node_pypi[("PyPI distribution<br/>package registry")]

node_callers -->|"import and call"| node_facade
node_facade -->|"re-exports"| node_number
node_facade -->|"re-exports"| node_filesize
node_facade -->|"re-exports"| node_time
node_facade -->|"re-exports"| node_lists
node_number -->|"translated wording"| node_i18n
node_filesize -->|"translated units"| node_i18n
node_time -->|"translated phrases"| node_i18n
node_lists -->|"translated joining"| node_i18n
node_i18n -->|"loads active locale"| node_catalogs
node_catalogs -->|"contains"| node_po_ru
node_catalogs -->|"contains"| node_po_zh
node_translation_scripts -.->|"updates and compiles"| node_catalogs
node_package -->|"packages"| node_facade
node_package -->|"includes as package data"| node_catalogs
node_package -->|"ships typing metadata"| node_typed_marker
node_docs -.->|"documents API"| node_facade
node_release -->|"builds and releases"| node_package
node_release -.->|"builds documentation"| node_docs
node_release -->|"publishes"| node_pypi

click node_facade "https://github.com/python-humanize/humanize/blob/main/src/humanize/__init__.py"
click node_number "https://github.com/python-humanize/humanize/blob/main/src/humanize/number.py"
click node_filesize "https://github.com/python-humanize/humanize/blob/main/src/humanize/filesize.py"
click node_time "https://github.com/python-humanize/humanize/blob/main/src/humanize/time.py"
click node_lists "https://github.com/python-humanize/humanize/blob/main/src/humanize/lists.py"
click node_i18n "https://github.com/python-humanize/humanize/blob/main/src/humanize/i18n.py"
click node_catalogs "https://github.com/python-humanize/humanize/tree/main/src/humanize/locale"
click node_po_ru "https://github.com/python-humanize/humanize/blob/main/src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po"
click node_po_zh "https://github.com/python-humanize/humanize/blob/main/src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po"
click node_translation_scripts "https://github.com/python-humanize/humanize/blob/main/scripts/update-translations.sh"
click node_package "https://github.com/python-humanize/humanize/blob/main/pyproject.toml"
click node_typed_marker "https://github.com/python-humanize/humanize/blob/main/src/humanize/py.typed"
click node_docs "https://github.com/python-humanize/humanize/blob/main/mkdocs.yml"
click node_release "https://github.com/python-humanize/humanize/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_facade,node_number,node_filesize,node_time,node_lists toneBlue
class node_i18n,node_catalogs,node_po_ru,node_po_zh,node_translation_scripts toneAmber
class node_package,node_typed_marker,node_docs,node_release toneMint
class node_callers,node_pypi toneNeutral
```

## Components

### Python Library

Synchronous formatting APIs packaged from src/.

- [humanize package facade](https://github.com/python-humanize/humanize/blob/main/src/humanize/__init__.py): public API · Re-exports the library's public formatting APIs. · `src/humanize/__init__.py`
- [Number formatting](https://github.com/python-humanize/humanize/blob/main/src/humanize/number.py): formatting domain · Words, grouping, fractions, scientific notation, and ordinals. · `src/humanize/number.py`
- [File-size formatting](https://github.com/python-humanize/humanize/blob/main/src/humanize/filesize.py): formatting domain · Decimal, binary, GNU, and throughput unit formatting. · `src/humanize/filesize.py`
- [Date and time formatting](https://github.com/python-humanize/humanize/blob/main/src/humanize/time.py): formatting domain · Natural dates, relative time, and precise durations. · `src/humanize/time.py`
- [List formatting](https://github.com/python-humanize/humanize/blob/main/src/humanize/lists.py): formatting domain · Natural-language iterable joining. · `src/humanize/lists.py`

### Localization

Gettext runtime context and bundled language catalogs.

- [Localization runtime](https://github.com/python-humanize/humanize/blob/main/src/humanize/i18n.py): gettext boundary · Activates, deactivates, and supplies translation context. · `src/humanize/i18n.py`
- [Locale catalogs](https://github.com/python-humanize/humanize/tree/main/src/humanize/locale): package data · Per-locale gettext phrases and plural rules. · `src/humanize/locale`
- [Russian catalog](https://github.com/python-humanize/humanize/blob/main/src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po): translation asset · `src/humanize/locale/ru_RU/LC_MESSAGES/humanize.po`
- [Chinese catalog](https://github.com/python-humanize/humanize/blob/main/src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po): translation asset · `src/humanize/locale/zh_CN/LC_MESSAGES/humanize.po`
- [Translation maintenance](https://github.com/python-humanize/humanize/blob/main/scripts/update-translations.sh): development scripts · Refreshes catalogs and generates translation binaries. · `scripts/update-translations.sh`

### Packaging & Delivery

Distribution, documentation, and release automation.

- [Package definition](https://github.com/python-humanize/humanize/blob/main/pyproject.toml): Python packaging · Defines src-layout distribution and package data. · `pyproject.toml`
- [Typing marker](https://github.com/python-humanize/humanize/blob/main/src/humanize/py.typed): package metadata · `src/humanize/py.typed`
- [Documentation build](https://github.com/python-humanize/humanize/blob/main/mkdocs.yml): MkDocs configuration · `mkdocs.yml`
- [Release workflow](https://github.com/python-humanize/humanize/blob/main/.github/workflows/release.yml): GitHub Actions · Runs delivery automation for the distributable library. · `.github/workflows/release.yml`

### Other components

- **Library consumers**: Python callers · Provide primitive values and receive display strings.
- **PyPI distribution**: package registry

## Connections

- 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
