fontfyi 0.2.0

Pure Python Google Fonts toolkit -- 50 fonts metadata, CSS generation, font stacks, pairings, and design systems. Zero dependencies.

fontfyi

Pure Python Google Fonts toolkit. Access 50 popular fonts metadata, generate CSS import URLs, browse 10 web-safe font stacks, and 15 curated font pairings -- all with zero dependencies.

Explore all fonts at fontfyi.com -- font explorer, font pairings, font stacks, and developer API.

Install

pip install fontfyi                # Core engine (zero deps)
pip install "fontfyi[cli]"         # + Command-line interface
pip install "fontfyi[mcp]"         # + MCP server for AI assistants
pip install "fontfyi[api]"         # + HTTP client for fontfyi.com API
pip install "fontfyi[all]"         # Everything

Quick Start

from fontfyi import get_font, css_family, google_fonts_url, parse_variants

# Look up a font
font = get_font("inter")
print(font["family"])       # Inter
print(font["category"])     # sans-serif
print(font["designer"])     # Rasmus Andersson

# Parse weight variants
weights, italic = parse_variants(font["variants"])
print(weights)              # [100, 200, 300, 400, 500, 600, 700, 800, 900]
print(italic)               # True

# Generate CSS
print(css_family("Inter", "sans-serif"))
# 'Inter', sans-serif
print(google_fonts_url("Inter", [400, 700]))
# https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap

Font Pairings & Stacks

from fontfyi import (
    search, popular, by_category, get_stack,
    get_pairings_for, featured_pairings, FONT_STACKS,
)

# Search fonts
results = search("mono")
for f in results:
    print(f"{f['family']} ({f['category']})")

# Top 10 most popular fonts
for f in popular(10):
    print(f"{f['popularity_rank']}. {f['family']}")

# Font stacks (CSS-ready)
stack = get_stack("system-ui")
print(stack.stack)
# system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, ...

# Font pairings with rationale
for p in get_pairings_for("inter"):
    print(f"{p.heading} + {p.body} (score: {p.score})")
    print(f"  {p.rationale}")
    print(f"  Mood: {p.mood}")

Command-Line Interface

pip install "fontfyi[cli]"

fontfyi info inter                     # Font metadata table
fontfyi search mono                    # Search fonts by name
fontfyi css inter                      # CSS import snippet
fontfyi pair inter                     # Font pairing suggestions
fontfyi popular                        # Top fonts by popularity
fontfyi stacks                         # Font stack presets

MCP Server (Claude, Cursor, Windsurf)

Add font tools to any AI assistant that supports Model Context Protocol.

pip install "fontfyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "fontfyi": {
            "command": "python",
            "args": ["-m", "fontfyi.mcp_server"]
        }
    }
}

Available tools: font_info, font_search, font_css, font_pairings, font_stacks, popular_fonts

REST API Client

pip install "fontfyi[api]"

from fontfyi.api import FontFYI

with FontFYI() as api:
    info = api.font("inter")           # GET /api/font/inter/
    css = api.css("inter")             # GET /api/font/inter/css/
    results = api.search("mono")       # GET /api/search/?q=mono
    pairings = api.pairings("inter")   # GET /api/pairings/inter/
    stacks = api.stacks()              # GET /api/font-stacks/

Full API documentation with OpenAPI spec at fontfyi.com/api/openapi.json.

API Reference

Font Data

Function	Description
get_font(slug) -> dict | None	Look up font by slug
search(query, limit=20) -> list[dict]	Search fonts by name
by_category(category) -> list[dict]	Filter by category
popular(limit=20) -> list[dict]	Top fonts by popularity
all_fonts() -> list[dict]	All 50 fonts
font_count() -> int	Total font count

CSS Utilities

Function	Description
css_family(family, category) -> str	'Inter', sans-serif
google_fonts_url(family, weights?) -> str	Google Fonts CSS URL
google_fonts_link(family, weights?) -> str	HTML <link> tag
google_download_url(family) -> str	Direct download URL
homebrew_install_cmd(family) -> str	brew install --cask font-inter
parse_variants(variants) -> (weights, italic)	Parse variant strings
weight_name(weight) -> str	400 -> "Regular"

Font Stacks

Function	Description
get_stack(slug) -> FontStack | None	Get a font stack by slug
FONT_STACKS	All 10 curated font stacks

Available stacks: system-ui, transitional, old-style, humanist, geometric-humanist, neo-grotesque, monospace-slab, monospace-code, industrial, rounded

Font Pairings

Function	Description
get_pairings_for(slug) -> list[FontPairing]	Pairings containing a font
featured_pairings() -> list[FontPairing]	Score >= 8 pairings
PAIRINGS	All 15 curated pairings

Data Types

• FontStack -- NamedTuple: slug, name, description, stack
• FontPairing -- NamedTuple: heading, body, rationale, score, use_cases, mood

Features

• 50 Google Fonts: family, category, variants, subsets, designer, popularity rank
• CSS generation: font-family declarations, Google Fonts URLs, HTML link tags
• Weight parsing: variant strings to numeric weights with italic detection
• 10 font stacks: system-ui, transitional, humanist, neo-grotesque, monospace, and more
• 15 font pairings: Curated heading + body combinations with rationale and scores
• Homebrew commands: brew install --cask font-{name} generator
• CLI: Rich terminal output with font info, search, CSS snippets
• MCP server: 6 tools for AI assistants (Claude, Cursor, Windsurf)
• REST API client: httpx-based client for fontfyi.com API
• Zero dependencies: Core engine uses only json and pathlib from stdlib
• Type-safe: Full type annotations, py.typed marker (PEP 561)

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem:

Package	Description
colorfyi	Hex to RGB converter, WCAG contrast checker, color harmonies
emojifyi	Emoji encoding & metadata for 3,781 Unicode emojis
symbolfyi	Symbol encoder -- 11 encoding formats for any character
unicodefyi	Unicode character lookup -- 17 encodings + character search
fontfyi	Google Fonts explorer -- metadata, CSS helpers, font pairings
distancefyi	Haversine distance, bearing, travel times -- distancefyi.com
timefyi	Timezone operations, time differences -- timefyi.com
namefyi	Korean romanization, Five Elements -- namefyi.com
unitfyi	Unit conversion, 200 units, 20 categories -- unitfyi.com
holidayfyi	Holiday dates, Easter calculation -- holidayfyi.com

Links

• Font Explorer -- Browse all Google Fonts
• Font Pairings -- Curated heading + body combinations
• Font Stacks -- CSS-ready font stack presets
• REST API Documentation -- Free API with OpenAPI spec
• Source Code -- MIT licensed

License

MIT