Improve ImageFont error messages

Tests/test_imagefont.py

@@ -5,6 +5,7 @@
 import re
 import shutil
 import sys
+import tempfile
 from io import BytesIO
 from pathlib import Path
 from typing import Any, BinaryIO
@@ -460,17 +461,43 @@ def test_free_type_font_get_mask(font: ImageFont.FreeTypeFont) -> None:
     assert mask.size == (108, 13)
 
 
+def test_load_when_image_not_found() -> None:
+    with tempfile.NamedTemporaryFile(delete=False) as tmp:
+        pass
+    with pytest.raises(OSError) as e:
+        ImageFont.load(tmp.name)
+
+    os.unlink(tmp.name)
+
+    root = os.path.splitext(tmp.name)[0]
+    assert str(e.value) == f"cannot find glyph data file {root}.{{gif|pbm|png}}"
+
+
 def test_load_path_not_found() -> None:
     # Arrange
     filename = "somefilenamethatdoesntexist.ttf"
 
     # Act/Assert
-    with pytest.raises(OSError):
+    with pytest.raises(OSError) as e:
         ImageFont.load_path(filename)
+
+    # The file doesn't exist, so don't suggest `load`
+    assert filename in str(e.value)
+    assert "did you mean" not in str(e.value)
     with pytest.raises(OSError):
         ImageFont.truetype(filename)
 
 
+def test_load_path_existing_path() -> None:
+    with tempfile.NamedTemporaryFile() as tmp:
+        with pytest.raises(OSError) as e:
+            ImageFont.load_path(tmp.name)
+
+    # The file exists, so the error message suggests to use `load` instead
+    assert tmp.name in str(e.value)
+    assert " did you mean" in str(e.value)
+
+
 def test_load_non_font_bytes() -> None:
     with open("Tests/images/hopper.jpg", "rb") as f:
         with pytest.raises(OSError):

src/PIL/ImageFont.py

@@ -98,11 +98,13 @@ class ImageFont:
     def _load_pilfont(self, filename: str) -> None:
         with open(filename, "rb") as fp:
             image: ImageFile.ImageFile | None = None
+            root = os.path.splitext(filename)[0]
+
             for ext in (".png", ".gif", ".pbm"):
                 if image:
                     image.close()
                 try:
-                    fullname = os.path.splitext(filename)[0] + ext
+                    fullname = root + ext
                     image = Image.open(fullname)
                 except Exception:
                     pass
@@ -112,7 +114,8 @@ def _load_pilfont(self, filename: str) -> None:
             else:
                 if image:
                     image.close()
-                msg = "cannot find glyph data file"
+
+                msg = f"cannot find glyph data file {root}.{{gif|pbm|png}}"
                 raise OSError(msg)
 
             self.file = fullname
@@ -224,7 +227,7 @@ def __init__(
             raise core.ex
 
         if size <= 0:
-            msg = "font size must be greater than 0"
+            msg = f"font size must be greater than 0, not {size}"
             raise ValueError(msg)
 
         self.path = font
@@ -768,8 +771,9 @@ def getlength(self, text: str | bytes, *args: Any, **kwargs: Any) -> float:
 
 def load(filename: str) -> ImageFont:
     """
-    Load a font file.  This function loads a font object from the given
-    bitmap font file, and returns the corresponding font object.
+    Load a font file. This function loads a font object from the given
+    bitmap font file, and returns the corresponding font object. For loading TrueType
+    or OpenType fonts instead, see :py:func:`~PIL.ImageFont.truetype`.
 
     :param filename: Name of font file.
     :return: A font object.
@@ -789,7 +793,8 @@ def truetype(
 ) -> FreeTypeFont:
     """
     Load a TrueType or OpenType font from a file or file-like object,
-    and create a font object.
+    and create a font object. For loading bitmap fonts instead,
+    see :py:func:`~PIL.ImageFont.load` and :py:func:`~PIL.ImageFont.load_path`.
     This function loads a font object from the given file or file-like
     object, and creates a font object for a font of the given size.
 
@@ -927,7 +932,10 @@ def load_path(filename: str | bytes) -> ImageFont:
             return load(os.path.join(directory, filename))
         except OSError:
             pass
-    msg = "cannot find font file"
+    msg = f"cannot find font file '{filename}' in sys.path"
+    if os.path.exists(filename):
+        msg += f', did you mean ImageFont.load("{filename}") instead?'
+
     raise OSError(msg)