Use a documented TypeAlias for image source data.

core/pyproject.toml

@@ -73,6 +73,8 @@ dev = [
     "pytest-freezer == 0.4.8",
     "setuptools-scm == 8.0.4",
     "tox == 4.11.4",
+    # typing-extensions needed for TypeAlias added in Py 3.10
+    "typing-extensions == 4.9.0 ; python_version < '3.10'"
 ]
 docs = [
     "furo == 2023.9.10",

core/src/toga/images.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+import sys
 import warnings
 from io import BytesIO
 from pathlib import Path
-from typing import Any, TypeVar
+from typing import TYPE_CHECKING, Any
 from warnings import warn
 
 try:
@@ -19,25 +20,34 @@
 # Make sure deprecation warnings are shown by default
 warnings.filterwarnings("default", category=DeprecationWarning)
 
-# Define a type variable for generics where an Image type is required.
-ImageT = TypeVar("ImageT")
+if TYPE_CHECKING:
+    if sys.version_info < (3, 10):
+        from typing_extensions import TypeAlias, TypeVar
+    else:
+        from typing import TypeAlias, TypeVar
+
+    # Define a type variable for generics where an Image type is required.
+    ImageT = TypeVar("ImageT")
+
+    # Define the types that can be used as Image content
+    PathLike: TypeAlias = str | Path
+    BytesLike: TypeAlias = bytes | bytearray | memoryview
+    ImageLike: TypeAlias = Any
+    ImageContent: TypeAlias = PathLike | BytesLike | ImageLike
 
 
 class Image:
     def __init__(
         self,
-        src: str | Path | bytes | bytearray | memoryview | Any | None = None,
+        src: ImageContent | None = None,
         *,
         path=None,  # DEPRECATED
         data=None,  # DEPRECATED
     ):
         """Create a new image.
 
-        :param src: The source from which to load the image. Can be a file path
-            (relative or absolute, as a string or :any:`pathlib.Path`), raw binary data
-            in any supported image format, or another Toga image. Can also accept the
-            platform's native image format; if Pillow is installed,
-            :any:`PIL.Image.Image` can be used.
+        :param src: The source from which to load the image. Can be any valid
+            :any:`image content <ImageContent>` type.
         :param path: **DEPRECATED** - Use ``src``.
         :param data: **DEPRECATED** - Use ``src``.
         :raises FileNotFoundError: If a path is provided, but that path does not exist.

core/src/toga/widgets/imageview.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from travertino.size import at_least
 
@@ -9,9 +9,7 @@
 from toga.widgets.base import Widget
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
-    from toga.images import ImageT
+    from toga.images import ImageContent, ImageT
 
 
 def rehint_imageview(image, style, scale=1):
@@ -70,17 +68,15 @@ def rehint_imageview(image, style, scale=1):
 class ImageView(Widget):
     def __init__(
         self,
-        image: str | Path | bytes | bytearray | memoryview | Any | None = None,
+        image: ImageContent | None = None,
         id=None,
         style=None,
     ):
         """
         Create a new image view.
 
-        :param image: The image to display. This can take all the same formats as the
-            `src` parameter to :class:`toga.Image` -- namely, a file path (as string or
-            :any:`pathlib.Path`), bytes data in a supported image format, an instance of
-            the platform's native image type, or :any:`PIL.Image.Image`.
+        :param image: The image to display. Can be any valid :any:`image content
+            <ImageContent>` type; or :any:`None` to display no image.
         :param id: The ID for the widget.
         :param style: A style object. If no style is provided, a default style will be
             applied to the widget.
@@ -112,14 +108,8 @@ def focus(self):
     def image(self) -> toga.Image | None:
         """The image to display.
 
-        When setting an image, you can provide:
-
-        * An :class:`~toga.images.Image` instance; or
-
-        * Any value that would be a valid path specifier when creating a new
-          :class:`~toga.images.Image` instance; or
-
-        * :any:`None` to clear the image view.
+        When setting an image, you can provide any valid :any:`image content
+        <ImageContent>` type; or :any:`None` to clear the image view.
         """
         return self._image
 

docs/conf.py

@@ -30,7 +30,6 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
-    "sphinx_autodoc_typehints",
     "sphinx_tabs.tabs",
     "crate.sphinx.csv",
     "sphinx_copybutton",
@@ -72,6 +71,7 @@
     "members": True,
     "undoc-members": True,
 }
+autodoc_typehints = "description"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/reference/api/resources/images.rst

@@ -13,14 +13,7 @@ Graphical content of arbitrary size.
 Usage
 -----
 
-An image can be constructed from:
-
-* A path to a file on disk;
-* A blob of bytes containing image data in a known image format;
-* A :any:`PIL.Image` object;
-* Another :any:`toga.Image`; or
-* The native platform representation of an image (see the :ref:`Notes
-  <native-image-rep>` section below for details).
+An image can be constructed from a :any:`wide range of sources <ImageContent>`:
 
 .. code-block:: python
 
@@ -45,6 +38,8 @@ An image can be constructed from:
 Notes
 -----
 
+.. _known-image-formats:
+
 * PNG and JPEG formats are guaranteed to be supported.
   Other formats are available on some platforms:
 
@@ -65,4 +60,22 @@ Notes
 Reference
 ---------
 
+.. c:type:: ImageContent
+
+    When specifying content for an :any:`Image`, you can provide:
+
+    * a string specifying an absolute or relative path to a file in a :ref:`known image
+      format <known-image-formats>`;
+    * an absolute or relative :any:`pathlib.Path` object describing a file in a
+      :ref:`known image format <known-image-formats>`;
+    * a "blob of bytes" data type (:any:`bytes`, :any:`bytearray`, or :any:`memoryview`)
+      containing raw image data in a :ref:`known image format <known-image-formats>`;
+    * an instance of :any:`toga.Image`; or
+    * if `Pillow <https://pillow.readthedocs.io/>`__ is installed, an instance of
+      :any:`PIL.Image.Image`; or
+    * an instance of the :ref:`native platform image representation <native-image-rep>`.
+
+    If a relative path is provided, it will be anchored relative to the module that
+    defines your Toga application class.
+
 .. autoclass:: toga.Image