parmoji 2.0.7

Pillow-based emoji rendering with HTTP and local sources

Parmoji

Description

Parmoji is a Pillow-based emoji rendering library (unicode + Discord custom emoji) with pluggable image sources (HTTP CDN and local font), LRU in-memory caching, and optional on-disk caching using XDG locations. It’s extracted from the par-term-emu project and packaged as a standalone library for reuse.

Technology

• Python 3.11+
• Pillow
• httpx / requests (optional fallback)

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended)

Features

• Unicode and Discord emoji
• Multi-line rendering with alignment and anchors
• Fine control over emoji size/position per draw call
• Multiple built-in emoji sources (Twemoji, Apple, Google, etc.)
• LRU in-memory cache and optional disk cache (XDG)

Installation

uv add parmoji

Update

uv add parmoji -U

Quickstart

from parmoji import Parmoji
from parmoji.source import TwitterEmojiSource
from PIL import Image, ImageFont

text = "Hello 👋  from Parmoji 😎"

img = Image.new("RGBA", (480, 120), (255, 255, 255, 255))
font = ImageFont.load_default()

with Parmoji(img, source=TwitterEmojiSource, cache=True) as p:
    p.text((10, 20), text, fill=(0, 0, 0), font=font)

img.save("parmoji_example.png")

Emoji Sources and Caching

• Default source is Twemoji (Twitter-style). Swap via Parmoji(image, source=AppleEmojiSource).
• Disk cache: construct sources with disk_cache=True to persist assets.
• Cache location: $XDG_CACHE_HOME/par-term/parmoji/<SourceClass>/ (or ~/.cache/par-term/parmoji/<SourceClass>/).
• Clear failed CDN retries: source.clear_failed_cache().

Tight Cropping (remove Twemoji safe-zone)

Some emoji sets (notably Twemoji) include transparent padding around glyphs. To have the visible emoji fill the cell area (useful for multi-cell flags), request a tightly cropped asset directly from the source:

from parmoji.source import TwitterEmojiSource

src = TwitterEmojiSource(disk_cache=True)
stream = src.get_emoji("🇺🇸", tight=True, margin=1)  # crop to alpha bbox + 1px margin

• Cropped variants are cached on disk with a derived key, so subsequent calls don’t repeat work.
• You can enable tight cropping by default via environment:
  • PARMOJI_TIGHT=1 to enable
  • PARMOJI_TIGHT_MARGIN=2 to set a default margin

Architecture

For a high-level system design, components, rendering flow, and caching details, see the Architecture overview:

• docs/ARCHITECTURE.md

Development

make setup          # uv lock + uv sync
make checkall       # format + lint + typecheck + test
make test           # run tests
make package-all    # build wheel + sdist

• Pre-commit: pre-commit install (then pre-commit run --all-files)
• Type checking: uv run pyright
• Lint/format: uv run ruff check --fix src/ tests and uv run ruff format src/ tests

CI / Releases

• Build & test on push: .github/workflows/build.yml
• Publish to TestPyPI (manual): .github/workflows/publish-dev.yml
• Publish to PyPI (manual): .github/workflows/publish.yml (trusted publishing)
• GitHub Release (manual): .github/workflows/release.yml

What’s New

• 2.0.7 — Tight-cropping support for CDN sources (Twemoji, etc.):
  • get_emoji(..., tight=True, margin=1) trims Twemoji’s transparent safe‑zone.
  • Cropped variants are cached with a derived key.
  • Env toggles: PARMOJI_TIGHT=1, PARMOJI_TIGHT_MARGIN=2.

License

MIT — see LICENSE.

Acknowledgements

Originally based on the Pilmoji project by jay3332; heavily refactored and optimized.