fontimize.py

#!/bin/env python3

# Fontimize
# 
# A library to optimise font files for web use, by only including the characters used in the text.
# Author: David Millington, github.com/vintagedave
# License: GPLv3
#
# Converts font files to subsetted WOFF2 containing only the characters actually used.
# Accepts HTML files and automatically extracts the characters from the HTML, plus user-visible
# characters in CSS files used by those HTML files (such as :before and :after pseudo-elements),
# and then converts/subsets the fonts specified by those CSS files. Can optionally rewrite CSS
# to reference the generated WOFF2 files.
# 
# Originally written as part of a private static site generator. Fontimizer is run as the final step
# of the build process, to optimise the fonts used by the site. It's now been extracted into a  
# separate library, and is available on GitHub at github.com/vintagedave/fontimize

import os
import re
import sys
import logging
import warnings
from bs4 import BeautifulSoup
from fontTools.ttLib import TTFont
from fontTools.subset import Subsetter
from os import path
import cssutils
import pathlib
from pathvalidate import ValidationError, validate_filename
from typing import TypedDict
from collections.abc import Callable, Collection
from beartype import beartype

cssutils.log.setLevel(logging.CRITICAL)

_SUPPORTED_FONT_EXTENSIONS: set[str] = {'.ttf', '.otf', '.woff', '.woff2'}


class FontFileStats(TypedDict):
    """Size statistics for a single font file."""
    original: str
    generated: str
    original_size: int
    generated_size: int

class FontimizeStats(TypedDict):
    """Aggregate statistics about the font subsetting operation."""
    fonts_processed: int
    files: list[FontFileStats]
    total_original_size: int
    total_generated_size: int
    savings_bytes: int
    savings_percent: float

@beartype
def _empty_stats() -> FontimizeStats:
    """Return a FontimizeStats with all fields zeroed out."""
    return {"fonts_processed": 0, "files": [], "total_original_size": 0,
            "total_generated_size": 0, "savings_bytes": 0, "savings_percent": 0.0}

class FontimizeResult(TypedDict):
    """Result dictionary returned by all optimise_fonts* functions."""
    css: set[str]
    fonts: dict[str, str]
    chars: set[str]
    uranges: str
    rewritten_css: dict[str, str]
    stats: FontimizeStats

@beartype
def _get_unicode_string(char : str, withU : bool = True) -> str:
    return ('U+' if withU else '') + hex(ord(char))[2:].upper().zfill(4) # eg U+1234

@beartype
def get_used_characters_in_str(s : str) -> set[str]:
    res: set[str] = { " " } # Always contain space, otherwise no font file generated by TTF2Web 
    for c in s:
        res.add(c)

    # Check for some special characters and add extra variants
    if res.intersection(set("\"")):
        res.add('“')
        res.add('”')
    if res.intersection(set("\'")):
        res.add('‘')
        res.add('’')
    if res.intersection(set("-")):
        res.add('–') # en-dash
        res.add('—') # em-dash

    return res

@beartype
def get_used_characters_in_html(html : str) -> set[str]:
    soup: BeautifulSoup = BeautifulSoup(html, 'html.parser')
    text: str = soup.get_text()
    return get_used_characters_in_str(text)

@beartype
class charPair:
    def __init__(self, first : str, second : str) -> None:
        self.first: str = first
        self.second: str = second

    def __str__(self) -> str:
        return "[" + self.first + "-" + self.second + "]" # Pairs are inclusive

    # For print()-ing
    def __repr__(self) -> str:
        return self.__str__()

    def __eq__(self, other : object) -> bool:
        if isinstance(other, charPair):
            return self.first == other.first and self.second == other.second
        return False

    def get_range(self) -> str:
        if self.first == self.second:
            return _get_unicode_string(self.first)
        else:
            return _get_unicode_string(self.first) + '-' + _get_unicode_string(self.second, False) # Eg "U+0061-0071"


# Taking a sorted list of characters, find the sequential subsets and return pairs of the start and end
# of each sequential subset
@beartype
def _get_char_ranges(chars : list[str]) -> list[charPair]:
    chars.sort()
    if not chars:
        return []
    res: list[charPair] = []
    first: str = chars[0]
    prev_seen: str = first
    for c in chars[1:]:
        expected_next_char: str = chr(ord(prev_seen) + 1)
        if c != expected_next_char:
            # non-sequential, so time to start a new set
            pair: charPair = charPair(first, prev_seen)
            res.append(pair)
            first = c
        prev_seen = c
    # add final set if it hasn't been added yet
    if (not res) or (res[-1].second != prev_seen):
        pair = charPair(first, prev_seen)
        res.append(pair)

    return res

# Convert to human-readable size in MB or KB
@beartype
def _file_size_to_readable(size : int) -> str:
    return str(round(size / 1024)) + "KB" if size < 1024 * 1024 else str(round(size / (1024 * 1024), 1)) + "MB" # nKB or n.nMB

# Takes the input text, and the fonts, and generates new font files
# Other methods (eg taking HTML files, or multiple pieces of text) all end up here
@beartype
def optimise_fonts(text : str, fonts : Collection[str] | str, fontpath : str = "", subsetname : str = "FontimizeSubset", verbose : bool = False, print_stats : bool = True) -> FontimizeResult:
    unique_fonts: set[str] = {fonts} if isinstance(fonts, str) else set(fonts)  # Deduplicate; accept single string

    res: FontimizeResult = {
        "css": set(),  # at this level there are no CSS files, include to prevent errors for API consumer
        "fonts": {},
        "chars": set(),
        "uranges": "",
        "rewritten_css": {},
        "stats": _empty_stats(),
    }

    characters: set[str] = get_used_characters_in_str(text)

    char_list: list[str] = list(characters)
    if verbose:
        print("Characters:")
        print("  " + str(char_list))
    res["chars"] = characters # set of characters used in the input text

    char_ranges: list[charPair] = _get_char_ranges(char_list)
    if verbose:
        print("Character ranges:")
        print("  " + str(char_ranges))

    uranges_str: str = ', '.join(r.get_range() for r in char_ranges)
    if verbose:
        print("Unicode ranges:")
        print("  " + uranges_str)
    res["uranges"] = uranges_str # unicode ranges matching the characters used in the input text

    # For each font, generate a subset WOFF2 containing only the used characters.
    # By default, place it in the same folder as the respective font, unless fontpath is specified.
    # fontTools' subsetter preserves ligatures, contextual alternates, kerning and other
    # OpenType layout features by default (layout_closure=True), so the subset font
    # will still render correctly for the included characters.
    for font in unique_fonts:
        font_ext: str = pathlib.Path(font).suffix.lower()
        if font_ext not in _SUPPORTED_FONT_EXTENSIONS:
            warnings.warn(f"Unrecognised font format '{font_ext}' for {font}, "
                          f"supported formats: {', '.join(sorted(_SUPPORTED_FONT_EXTENSIONS))}")

        assetdir: str = fontpath or path.dirname(font) or "."
        os.makedirs(assetdir, exist_ok=True)

        if verbose:
            print(f"Processing {font}")

        tt_font: TTFont = TTFont(font)
        subsetter: Subsetter = Subsetter()
        subsetter.populate(unicodes=[ord(c) for c in characters])
        subsetter.subset(tt_font)

        basename: str = os.path.splitext(os.path.basename(font))[0]
        outfile: str = os.path.join(assetdir, f"{basename}.{subsetname}.woff2")

        if os.path.exists(outfile):
            warnings.warn(f"Output font file already exists and will be overwritten: {outfile}")

        tt_font.flavor = 'woff2'
        tt_font.save(outfile)
        tt_font.close()

        res["fonts"][font] = outfile

        if verbose:
            print(f"  Generated {outfile}")

    # Build structured stats
    file_stats: list[FontFileStats] = []
    for original, generated in res["fonts"].items():
        file_stats.append({
            "original": original,
            "generated": generated,
            "original_size": path.getsize(original),
            "generated_size": path.getsize(generated),
        })
    sum_orig: int = sum(fs["original_size"] for fs in file_stats)
    sum_new: int = sum(fs["generated_size"] for fs in file_stats)
    savings: int = sum_orig - sum_new
    savings_percent: float = (savings / sum_orig * 100) if sum_orig > 0 else 0.0
    res["stats"] = {
        "fonts_processed": len(res["fonts"]),
        "files": file_stats,
        "total_original_size": sum_orig,
        "total_generated_size": sum_new,
        "savings_bytes": savings,
        "savings_percent": round(savings_percent, 1),
    }

    if verbose or print_stats:
        print("Results:")
        print("  Fonts processed: " + str(res["stats"]["fonts_processed"]))
        if not verbose: # If verbose, already printed per-font above
            print("  Generated (use verbose output for input -> generated map):")
            for fs in file_stats:
                print("    " + fs["generated"])
        else:
            print("  Generated the following fonts from the originals:")
            for fs in file_stats:
                print("    " + fs["original"] + " -> " + fs["generated"])
        print("  Total original font size: " + _file_size_to_readable(sum_orig))
        print("  Total optimised font size: " + _file_size_to_readable(sum_new))
        print("  Savings: " +  _file_size_to_readable(savings) + " less, which is " + str(round(savings_percent, 1)) + "%!")
        print("Thankyou for using Fontimize!") # A play on Font and Optimise, haha, so good pun clever. But seriously - hopefully a memorable name!

    return res

# Takes a list of strings, and otherwise does the same as optimise_fonts
@beartype
def optimise_fonts_for_multiple_text(texts : Collection[str] | str, fonts : Collection[str] | str, fontpath : str = "", subsetname : str = "FontimizeSubset", verbose : bool = False, print_stats : bool = True) -> FontimizeResult:
    text: str = texts if isinstance(texts, str) else "".join(texts)
    return optimise_fonts(text, fonts, fontpath, verbose=verbose, print_stats=print_stats)

# Takes a list of HTML strings, and parses those to get the used text (ie ignoring HTML tags);
# then uses that to do the same as optimise_fonts
@beartype
def optimise_fonts_for_html_contents(html_contents : Collection[str] | str, fonts : Collection[str] | str, fontpath : str = "", subsetname : str = "FontimizeSubset", verbose : bool = False, print_stats : bool = True) -> FontimizeResult:
    if isinstance(html_contents, str):
        html_contents = [html_contents]
    texts: list[str] = [BeautifulSoup(html, 'html.parser').get_text() for html in html_contents]
    return optimise_fonts("".join(texts), fonts, fontpath, verbose=verbose, print_stats=print_stats)

@beartype
def _find_font_face_urls(css_contents: str) -> list[str]:
    """Extract all font file URLs from @font-face src declarations.

    Parses each @font-face rule's src property and collects URIs (the url() values).
    local() font names are skipped — they reference system-installed fonts by name,
    not file paths, so they can't be subset.
    """
    sheet: cssutils.css.CSSStyleSheet = cssutils.parseString(css_contents)

    urls: list[str] = []

    for rule in sheet:
        if rule.type == rule.FONT_FACE_RULE:
            # cssutils splits src into typed items: URIValue for url(), CSSFunction for local()/format()
            css_value: cssutils.css.value.PropertyValue | None = rule.style.getPropertyCSSValue('src')
            if css_value is None:
                warnings.warn("@font-face rule has no parseable src property")
                continue
            for item in css_value:
                # URIValue items have a .uri attribute; local() and format() do not
                if hasattr(item, 'uri'):
                    urls.append(item.uri)

    return urls

@beartype
def _get_path(known_file_path: str, relative_path: str) -> str:
    base_dir: str = path.dirname(known_file_path)

    # Join the base directory with the relative path
    full_path: str = path.join(base_dir, relative_path)

    return path.normpath(full_path)

# Characters that counter()/counters() may generate, keyed by list-style-type.
# When the style is known we include only the relevant characters; when unknown
# we include all of them as a generous fallback.
_COUNTER_CHARS_BY_STYLE: dict[str, str] = {
    "decimal":          "0123456789",
    "decimal-leading-zero": "0123456789",
    "lower-alpha":      "abcdefghijklmnopqrstuvwxyz",
    "lower-latin":      "abcdefghijklmnopqrstuvwxyz",
    "upper-alpha":      "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "upper-latin":      "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "lower-roman":      "ivxlcdm",
    "upper-roman":      "IVXLCDM",
    "lower-greek":      "αβγδεζηθικλμνξοπρστυφχψω",
    "georgian":         "ანბგდევზთიკლმნოპჟრსტუფქღყშჩცძწჭხჯჰ",
    "armenian":         "ԱԲԳԴԵԶԷԸԹԺԻԼԽԾԿՀՁՂՃՄՅՆՇՈՉՊՋՌՍՏՐՑՒՓՔՕՖ",
    "hiragana":         "あいうえおかきくけこさしすせそたちつてとなにぬねのはひふへほまみむめもやゆよらりるれろわゐゑをん",
    "hiragana-iroha":   "いろはにほへとちりぬるをわかよたれそつねならむうゐのおくやまけふこえてあさきゆめみしゑひもせす",
    "katakana":         "アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヰヱヲン",
    "katakana-iroha":   "イロハニホヘトチリヌルヲワカヨタレソツネナラムウヰノオクヤマケフコエテアサキユメミシヱヒモセス",
    "cjk-decimal":      "〇一二三四五六七八九",
    "cjk-earthly-branch": "子丑寅卯辰巳午未申酉戌亥",
    "cjk-heavenly-stem": "甲乙丙丁戊己庚辛壬癸",
    "hebrew":           "אבגדהוזחטיכלמנסעפצקרשת",
    "disc":             "•",
    "circle":           "◦",
    "square":           "▪",
}

# All counter characters combined, used as fallback when style is unknown
_ALL_COUNTER_CHARS: str = "".join(set("".join(_COUNTER_CHARS_BY_STYLE.values())))

# All quote characters used across locales: curly double/single, guillemets,
# German/Polish low-high, CJK corner brackets, plus straight quotes as fallback
_ALL_QUOTE_CHARS: str = (
    "\u201c\u201d"  # "" left/right double curly
    "\u2018\u2019"  # '' left/right single curly
    "\u00ab\u00bb"  # «» guillemets
    "\u2039\u203a"  # ‹› single guillemets
    "\u201e\u201f"  # „‟ German/Polish double low-high
    "\u201a\u201b"  # ‚‛ single low-high
    "\u300c\u300d"  # 「」 CJK corner brackets
    "\u300e\u300f"  # 『』 CJK white corner brackets
    "\"'"           # straight quotes as fallback
)


@beartype
def _counter_style_from_css_text(css_text: str) -> str | None:
    """Extract the list-style-type from a counter() or counters() CSS function.

    Returns the style name (eg 'lower-greek') or None if not specified,
    which means the CSS default of 'decimal'.

    counter(name) -> None (decimal)
    counter(name, lower-greek) -> 'lower-greek'
    counters(name, ".", upper-roman) -> 'upper-roman'
    """
    # Strip the function wrapper: "counter(...)" or "counters(...)"
    inner: str = css_text.split("(", 1)[1].rsplit(")", 1)[0].strip()
    # Split on commas, respecting quoted strings (the separator in counters())
    parts: list[str] = []
    current: str = ""
    in_quotes: bool = False
    quote_char: str = ""
    for ch in inner:
        if ch in ('"', "'") and not in_quotes:
            in_quotes = True
            quote_char = ch
            current += ch
        elif ch == quote_char and in_quotes:
            in_quotes = False
            current += ch
        elif ch == "," and not in_quotes:
            parts.append(current.strip())
            current = ""
        else:
            current += ch
    parts.append(current.strip())

    # counter(name) has 1 part, counter(name, style) has 2
    # counters(name, separator) has 2, counters(name, separator, style) has 3
    is_counters: bool = css_text.startswith("counters(")
    style_index: int = 2 if is_counters else 1
    if len(parts) > style_index:
        return parts[style_index].strip()
    return None


@beartype
def _extract_pseudo_elements_content(css_contents: str) -> list[str]:
    """Extract content characters from :before and :after pseudo-elements.

    Handles several types of CSS content value:
    - Quoted strings: characters extracted directly (eg '▸', '✻')
    - counter()/counters(): adds the numeral characters that the counter style
      would generate (eg digits for decimal, Roman numerals for upper-roman).
      If the style is unrecognised, all numeral character sets are included.
    - open-quote/close-quote: adds all locale quote mark characters
    - attr(): emits a warning since the value depends on HTML attributes and
      cannot be determined from CSS alone
    """
    sheet: cssutils.css.CSSStyleSheet = cssutils.parseString(css_contents)

    contents: list[str] = []

    for rule in sheet:
        if rule.type == rule.STYLE_RULE:
            selector: str = rule.selectorText
            if ':before' in selector or ':after' in selector: # this is something like cite:before, for example
                css_value: cssutils.css.value.PropertyValue | None = rule.style.getPropertyCSSValue('content')
                if css_value is None:
                    continue
                for item in css_value:
                    if isinstance(item, cssutils.css.value.CSSFunction):
                        css_text: str = item.cssText
                        if css_text.startswith("counter(") or css_text.startswith("counters("):
                            style: str | None = _counter_style_from_css_text(css_text)
                            if style is None:
                                style = "decimal"
                            chars: str = _COUNTER_CHARS_BY_STYLE.get(style, _ALL_COUNTER_CHARS)
                            contents.append(chars)
                        elif css_text.startswith("attr("):
                            warnings.warn(
                                f"CSS content uses attr() in '{selector}' — the characters "
                                f"it generates depend on HTML attribute values and cannot be "
                                f"determined from CSS alone. You may need to include additional "
                                f"characters via the addtl_text parameter."
                            )
                        continue
                    value: str = item.value
                    if value in ("open-quote", "close-quote",
                                 "no-open-quote", "no-close-quote"):
                        contents.append(_ALL_QUOTE_CHARS)
                    elif value and value not in ("none", "normal"):
                        contents.append(value)

    return contents


@beartype
def _rewrite_css(css_path: str, css_contents: str, font_mapping: dict[str, str],
                 output_dir: str) -> tuple[str, str]:
    """Rewrite @font-face src URLs in CSS to point to generated .woff2 fonts.

    This works in two phases:
    1. Parse with cssutils and modify the src property of @font-face rules whose
       font URLs appear in font_mapping. cssutils gives us a proper DOM so we can
       identify url() vs local() vs format() items reliably.
    2. Splice only the modified @font-face blocks back into the original CSS string,
       so everything else (comments, non-standard properties, formatting) is preserved
       byte-for-byte. We can't round-trip the whole file through cssutils because it
       may silently drop properties it considers invalid.

    Returns (output_path, rewritten_css_content).
    """
    sheet: cssutils.css.CSSStyleSheet = cssutils.parseString(css_contents)

    # Phase 1: modify @font-face rules via cssutils DOM.
    # We track which rules (by index) were modified so we know which source blocks
    # to splice in phase 2.
    parsed_font_faces: list[cssutils.css.CSSFontFaceRule] = []
    modified_indices: set[int] = set()

    for rule in sheet:
        if rule.type != rule.FONT_FACE_RULE:
            continue
        idx: int = len(parsed_font_faces)
        parsed_font_faces.append(rule)

        css_value: cssutils.css.value.PropertyValue | None = rule.style.getPropertyCSSValue('src')
        if css_value is None:
            continue

        # Rebuild the src value, replacing mapped font URLs with their woff2 equivalents.
        # cssutils splits src into typed items, eg for:
        #   src: url('font.ttf') format('truetype'), url('other.woff2') format('woff2')
        # we get: URIValue, CSSFunction(format), URIValue, CSSFunction(format)
        # We need to replace url+format pairs together when the url is mapped.
        new_src_parts: list[str] = []
        changed: bool = False
        replaced_prev_url: bool = False
        for item in css_value:
            if hasattr(item, 'uri'):
                resolved: str = _get_path(css_path, item.uri)
                if resolved in font_mapping:
                    new_font_path: str = font_mapping[resolved]
                    rel_path: str = os.path.relpath(new_font_path, output_dir)
                    new_src_parts.append(f"url('{rel_path}') format('woff2')")
                    changed = True
                    replaced_prev_url = True
                else:
                    new_src_parts.append(item.cssText)
                    replaced_prev_url = False
            elif isinstance(item, cssutils.css.value.CSSFunction) and item.cssText.startswith('format('):
                # Skip format() only when the preceding url() was replaced — it's
                # already included in the replacement string above. Unmapped URLs
                # keep their original format().
                if replaced_prev_url:
                    replaced_prev_url = False
                    continue
                new_src_parts.append(item.cssText)
            else:
                new_src_parts.append(item.cssText)
                replaced_prev_url = False

        if changed:
            rule.style.setProperty('src', ', '.join(new_src_parts))
            modified_indices.add(idx)

    if not modified_indices:
        output_path: str = os.path.join(output_dir, os.path.basename(css_path))
        return (output_path, css_contents)

    # Phase 2: splice modified @font-face blocks into the original CSS string.
    # We find @font-face blocks in the source text via regex — this is safe because
    # @font-face rules cannot contain nested braces. The blocks appear in the same
    # order as the parsed rules, so we match them by index.
    source_blocks: list[re.Match[str]] = list(re.finditer(r'@font-face\s*\{[^}]*\}', css_contents))

    new_css: str = css_contents
    # Replace in reverse order so earlier string positions stay valid
    for i in reversed(range(len(source_blocks))):
        if i in modified_indices and i < len(parsed_font_faces):
            match: re.Match[str] = source_blocks[i]
            serialized: str = parsed_font_faces[i].cssText
            if isinstance(serialized, bytes):
                serialized = serialized.decode('utf-8')
            new_css = new_css[:match.start()] + serialized + new_css[match.end():]

    output_path = os.path.join(output_dir, os.path.basename(css_path))
    return (output_path, new_css)


# Takes a list of files on disk
# HTML files are parsed; all others are treated as text
# First, collect all strings from those files.
# Then, also parse to get all the CSS files they use. From those CSS files, collect all the fonts they use in @font-face src,
# plus look for any additional characters that will be reflected in rendered webpage output, such as :before and :after pseudo-elements.
@beartype
def optimise_fonts_for_files(files : list[str], font_output_dir : str = "", subsetname : str = "FontimizeSubset", verbose : bool = False, print_stats : bool = True, fonts : Collection[str] | str | None = None, addtl_text : str = "", css_rewriter : Callable[[str, str], None] | None = None) -> FontimizeResult:
    if fonts is None:
        fonts = []
    elif isinstance(fonts, str):
        fonts = [fonts]

    if (len(files) == 0) and len(addtl_text) == 0: # If you specify any text, input files are optional -- note, not documented, used for cmd line app
        print("Error: No input files. Exiting.")
        return {
            "css": set(),
            "fonts": {},
            "chars": set(),
            "uranges": "",
            "rewritten_css": {},
            "stats": _empty_stats(),
        }

    text: str = addtl_text
    css_files: set[str] = set()
    font_files: set[str] = set()
    for f in fonts: # user-specified input font files
        font_files.add(f)

    for f in files:
        file_ext: str = pathlib.Path(f).suffix.lower()
        with open(f, 'r') as file:
            if file_ext == '.html' or file_ext == '.htm':
                html = file.read()
                soup = BeautifulSoup(html, 'html.parser')

                # Extract used text
                text += soup.get_text()

                # Extract CSS files the HTML references
                for link in soup.find_all('link', href=True):
                    href = link['href']
                    if isinstance(href, list):  # BS4 can return a list for multi-valued attributes
                        href = href[0]
                    # Strip query strings and fragments before checking extension
                    clean_href: str = href.split('?')[0].split('#')[0]
                    rel_attr = link.get('rel')  # BS4 returns a list for rel
                    rel: list[str] = list(rel_attr) if isinstance(rel_attr, list) else []
                    if clean_href.endswith('.css') or 'stylesheet' in rel:
                        adjusted_css_path = _get_path(f, clean_href) # It'll be relative, so relative to the HTML file
                        css_files.add(adjusted_css_path)
            else: # not HTML, treat as text
                text += file.read()

    # Sanity check that there is any text to process
    if len(text) == 0:
        print("Error: No text found in the input files or additional text. Exiting.")
        return {
            "css": set(),
            "fonts": {},
            "chars": set(),
            "uranges": "",
            "rewritten_css": {},
            "stats": _empty_stats(),
        }

    # Extract fonts from CSS files
    for css_file in css_files:
        with open(css_file, 'r') as file:
            css = file.read()

        # Extract the contents of all :before and :after CSS pseudo-elements; add these to the text
        pseudo_elements = _extract_pseudo_elements_content(css)
        for pe in pseudo_elements:
            text += pe

        # List of all fonts from @font-face src url: statements. This assumes they're all local files
        font_urls = _find_font_face_urls(css)
        for font_url in font_urls:
            # Only handle local files -- this does not support remote files
            adjusted_font_path = _get_path(css_file, font_url) # Relative to the CSS file
            if path.isfile(adjusted_font_path):
                font_files.add(adjusted_font_path)
            else:
                warnings.warn(f"Font file not found (may be remote not local?); skipping: {font_url} (resolved to {adjusted_font_path})")

    if verbose:
        print("Found the following CSS files:")
        for css_file in css_files:
            print("  " + css_file)

        print("Found the following fonts:")
        for font_file in font_files:
            print("  " + font_file)

    # print("Found the following text:")
    # print(text)
    
    if len(font_files) == 0:
        print("Error: No fonts found in the input files. Exiting.")
        return {
            "css": css_files,
            "fonts": {},
            "chars": set(),
            "uranges": "",
            "rewritten_css": {},
            "stats": _empty_stats(),
        }

    res: FontimizeResult = optimise_fonts(text, font_files, fontpath=font_output_dir, subsetname=subsetname, verbose=verbose, print_stats=print_stats)
    res["css"] = css_files

    # Rewrite CSS files to reference the generated .woff2 fonts
    if font_output_dir and css_files:
        for css_file in css_files:
            with open(css_file, 'r') as file:
                css = file.read()

            output_path, rewritten = _rewrite_css(css_file, css, res["fonts"], font_output_dir)

            if css_rewriter is not None:
                css_rewriter(output_path, rewritten)
            else:
                with open(output_path, 'w') as file:
                    file.write(rewritten)

            res["rewritten_css"][css_file] = output_path

    return res


# Note that unit tests for this file are in tests.py; run that file to run the tests
if __name__ == '__main__':
    import argparse
    import json

    parser = argparse.ArgumentParser(description="Optimize fonts to only the specific glyphs needed for your text or HTML files",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
    fontimize.py 1.html 2.txt
    fontimize.py --outputdir output --subsetname MySubset --verbose 1.html 2.txt
    fontimize.py --text "The fonts will contain only the glyphs in this string" --fonts "Arial.ttf" "Times New Roman.ttf"
    fontimize.py --json --outputdir output 1.html 2.txt
                """)

    parser.add_argument('inputfiles', default=[], nargs='*', help='Input files to parse: .htm and .html are parsed as HTML to extract used text, all other files are treated as text')
    parser.add_argument('-t', '--text', type=str, help='Input text to parse, specified directly on the command line')
    parser.add_argument('-f', '--fonts', default=[], nargs='*', help='Input font files')

    group_output = parser.add_argument_group('Output', 'Specify font output directory and font subset phrase in the generated filenames')
    group_output.add_argument("-o", "--outputdir", type=str,
                        help="Directory in which to place the generated font files (default is the same directory as the original font files)",
                        default="")
    group_output.add_argument("-s", "--subsetname", type=str,
                        help="Phrase used in the output font filenames, eg 'Arial.SubsetName.woff2'",
                        default="FontimizeSubset")

    group_verb = parser.add_argument_group('Verbosity', 'Control how much Fontimize prints to the console')
    group_verb.add_argument("-v", "--verbose", help="Output significant / diagnostic info about discovered files and fonts, and generated fonts and their glyphs",
                    action="store_true")
    group_verb.add_argument("-n", "--nostats", help="Do not output info about the sizes of the original and generated fonts and the amount of space saved (shown by default)",
                    action="store_true")
    group_verb.add_argument("--json", help="Print results as JSON to stdout, including any warnings; suppresses all other output",
                    action="store_true", dest="json_output")

    args = parser.parse_args()

    # --json captures warnings into the result and suppresses human-readable output
    _captured_warnings: list[str] = []
    if args.json_output:
        args.nostats = True
        args.verbose = False
        # Capture warnings into a list instead of printing to stderr
        def _warning_handler(message : Warning | str, category : type[Warning], filename : str, lineno : int, file : object = None, line : str | None = None) -> None:
            _captured_warnings.append(str(message))
        warnings.showwarning = _warning_handler

    # If both --text and inputfiles are specified, give an error
    if args.text and args.inputfiles:
        print("Error: Both --text and input files cannot be specified at the same time.")
        sys.exit(1)

    # If neither --text nor inputfiles are specified, give an error
    if not args.text and not args.inputfiles:
        print("Error: Either --text or input files must be specified.")
        sys.exit(1)

    _addtl_text: str = ""
    if args.text:
        _addtl_text = args.text

    # If inputfiles are specified, test they exist
    _inputfiles: list[str] = []
    if args.inputfiles:
        for file in args.inputfiles:
            if not os.path.exists(file):
                print(f"Error: Input file '{file}' does not exist.")
                sys.exit(1)
        _inputfiles = args.inputfiles

    # If fonts are specified, test they exist
    _fonts: list[str] = []
    if args.fonts:
        for file in args.fonts:
            if not os.path.exists(file):
                print(f"Error: Font file '{file}' does not exist.")
                sys.exit(1)
        _fonts = args.fonts

    # If outputdir is specified, test it exists
    _outputdir: str = ""
    if args.outputdir:
        if not os.path.exists(args.outputdir):
            print(f"Error: Output directory '{args.outputdir}' does not exist.")
            sys.exit(1)
        _outputdir = args.outputdir

    # If subsetname is specified, test it's valid
    _subsetname: str = ""
    if args.subsetname:
        try:
            validate_filename(args.subsetname)
        except ValidationError as e:
            print(f"Error: Subset name '{args.subsetname}' is not valid: {e}")
            sys.exit(1)
        _subsetname = args.subsetname

    _verbose = False
    if args.verbose:
        _verbose = args.verbose;

    _printstats = True
    if args.nostats:
        _printstats = not args.nostats

    res: FontimizeResult = optimise_fonts_for_files(
        _inputfiles,
        font_output_dir=_outputdir,
        subsetname=_subsetname,
        verbose=_verbose,
        print_stats=_printstats,
        fonts=_fonts,
        addtl_text=_addtl_text,
        css_rewriter=None,  # CSS rewriting uses the default file-writing behaviour, not a callback
    )

    if args.json_output:
        json_result: dict[str, object] = {
            "css": sorted(res["css"]),
            "fonts": res["fonts"],
            "chars": sorted(res["chars"]),
            "uranges": res["uranges"],
            "rewritten_css": res["rewritten_css"],
            "stats": res["stats"],
            "warnings": _captured_warnings,
        }
        print(json.dumps(json_result, indent=2))

    if _verbose:
        print("Done.")