Allow creating images from raw image sources

android/src/toga_android/images.py

@@ -5,17 +5,21 @@
 
 
 class Image:
-    def __init__(self, interface, path=None, data=None):
+    RAW_TYPE = Bitmap
+
+    def __init__(self, interface, path=None, data=None, raw=None):
         self.interface = interface
 
         if path:
             self.native = BitmapFactory.decodeFile(str(path))
             if self.native is None:
                 raise ValueError(f"Unable to load image from {path}")
-        else:
+        elif data:
             self.native = BitmapFactory.decodeByteArray(data, 0, len(data))
             if self.native is None:
                 raise ValueError("Unable to load image from data")
+        else:
+            self.native = raw
 
     def get_width(self):
         return self.native.getWidth()

changes/2263.feature.rst

@@ -0,0 +1 @@
+Images can now be created from the native platform representation of an image, without needing to be transformed to bytes.

cocoa/src/toga_cocoa/images.py

@@ -19,7 +19,9 @@ def nsdata_to_bytes(data: NSData) -> bytes:
 
 
 class Image:
-    def __init__(self, interface, path=None, data=None):
+    RAW_TYPE = NSImage
+
+    def __init__(self, interface, path=None, data=None, raw=None):
         self.interface = interface
 
         try:
@@ -36,11 +38,13 @@ def __init__(self, interface, path=None, data=None):
                 self.native = image.initWithContentsOfFile(str(path))
                 if self.native is None:
                     raise ValueError(f"Unable to load image from {path}")
-            else:
+            elif data:
                 nsdata = NSData.dataWithBytes(data, length=len(data))
                 self.native = image.initWithData(nsdata)
                 if self.native is None:
                     raise ValueError("Unable to load image from data")
+            else:
+                self.native = raw
         finally:
             image.release()
 

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 TypeVar
+from typing import TYPE_CHECKING, Any
 from warnings import warn
 
 try:
@@ -19,32 +20,34 @@
 # Make sure deprecation warnings are shown by default
 warnings.filterwarnings("default", category=DeprecationWarning)
 
-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
 
 
-# Note: remove PIL type annotation when plugin system is implemented for image format
-# registration; replace with ImageT?
 class Image:
     def __init__(
         self,
-        src: str
-        | Path
-        | bytes
-        | bytearray
-        | memoryview
-        | Image
-        | PIL.Image.Image
-        | 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 a :any:`PIL.Image.Image` if Pillow is installed.
+        :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.
@@ -99,6 +102,9 @@ def __init__(
             src.save(buffer, format="png", compress_level=0)
             self._impl = self.factory.Image(interface=self, data=buffer.getvalue())
 
+        elif isinstance(src, self.factory.Image.RAW_TYPE):
+            self._impl = self.factory.Image(interface=self, raw=src)
+
         else:
             raise TypeError("Unsupported source type for Image")
 

core/src/toga/widgets/imageview.py

@@ -9,11 +9,7 @@
 from toga.widgets.base import Widget
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
-    import PIL.Image
-
-    from toga.images import ImageT
+    from toga.images import ImageContent, ImageT
 
 
 def rehint_imageview(image, style, scale=1):
@@ -24,9 +20,9 @@ def rehint_imageview(image, style, scale=1):
     :param image: The image being displayed.
     :param style: The style object for the imageview.
     :param scale: The scale factor (if any) to apply to native pixel sizes.
-    :returns: A triple containing the intrinsic width hint, intrinsic height
-        hint, and the aspect ratio to preserve (or None if the aspect ratio
-        should not be preserved).
+    :returns: A triple containing the intrinsic width hint, intrinsic height hint, and
+        the aspect ratio to preserve (or None if the aspect ratio should not be
+        preserved).
     """
     if image:
         if style.width != NONE and style.height != NONE:
@@ -72,23 +68,15 @@ def rehint_imageview(image, style, scale=1):
 class ImageView(Widget):
     def __init__(
         self,
-        image: str
-        | Path
-        | bytes
-        | bytearray
-        | memoryview
-        | PIL.Image.Image
-        | 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,
-            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.
@@ -120,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
 

core/tests/conftest.py

@@ -22,6 +22,10 @@ def clear_sys_modules(monkeypatch):
         pass
 
 
+class TestApp(toga.App):
+    pass
+
+
 @pytest.fixture
 def app(event_loop):
-    return toga.App(formal_name="Test App", app_id="org.beeware.toga.test-app")
+    return TestApp(formal_name="Test App", app_id="org.beeware.toga.test-app")

core/tests/test_images.py

@@ -6,8 +6,8 @@
 import toga
 from toga_dummy.utils import assert_action_performed_with
 
-RELATIVE_FILE_PATH = Path("resources/toga.png")
-ABSOLUTE_FILE_PATH = Path(toga.__file__).parent / "resources/toga.png"
+RELATIVE_FILE_PATH = Path("resources/sample.png")
+ABSOLUTE_FILE_PATH = Path(__file__).parent / "resources/sample.png"
 
 
 @pytest.mark.filterwarnings("ignore::DeprecationWarning")
@@ -108,6 +108,20 @@ def test_create_from_bytes(args, kwargs):
     assert_action_performed_with(image, "load image data", data=BYTES)
 
 
+def test_create_from_raw():
+    """An image can be created from a raw data source"""
+    orig = toga.Image(BYTES)
+
+    copy = toga.Image(orig._impl.native)
+    # Image is bound
+    assert copy._impl is not None
+    # impl/interface round trips
+    assert copy._impl.interface == copy
+
+    # Image was constructed from raw data
+    assert_action_performed_with(copy, "load image from raw")
+
+
 def test_not_enough_arguments():
     with pytest.raises(
         TypeError,
@@ -132,7 +146,7 @@ def test_create_from_pil(app):
     toga_image = toga.Image(pil_image)
 
     assert isinstance(toga_image, toga.Image)
-    assert toga_image.size == (32, 32)
+    assert toga_image.size == (144, 72)
 
 
 def test_create_from_toga_image(app):
@@ -141,7 +155,7 @@ def test_create_from_toga_image(app):
     toga_image_2 = toga.Image(toga_image)
 
     assert isinstance(toga_image_2, toga.Image)
-    assert toga_image_2.size == (32, 32)
+    assert toga_image_2.size == (144, 72)
 
 
 @pytest.mark.parametrize("kwargs", [{"data": BYTES}, {"path": ABSOLUTE_FILE_PATH}])
@@ -176,14 +190,23 @@ def test_dimensions(app):
     """The dimensions of the image can be retrieved"""
     image = toga.Image(RELATIVE_FILE_PATH)
 
-    assert image.size == (32, 32)
-    assert image.width == image.height == 32
+    assert image.size == (144, 72)
+    assert image.width == 144
+    assert image.height == 72
 
 
 def test_data(app):
     """The raw data of the image can be retrieved."""
     image = toga.Image(ABSOLUTE_FILE_PATH)
-    assert image.data == ABSOLUTE_FILE_PATH.read_bytes()
+
+    # We can't guarantee the round-trip of image data,
+    # but the data starts with a PNG header
+    assert image.data.startswith(b"\x89PNG\r\n\x1a\n")
+
+    # If we build a new image from the data, it has the same properties.
+    from_data = toga.Image(image.data)
+    assert from_data.width == image.width
+    assert from_data.height == image.height
 
 
 def test_image_save(tmp_path):
@@ -214,15 +237,15 @@ def test_as_format_toga(app, Class_1, Class_2):
     image_2 = image_1.as_format(Class_2)
 
     assert isinstance(image_2, Class_2)
-    assert image_2.size == (32, 32)
+    assert image_2.size == (144, 72)
 
 
 def test_as_format_pil(app):
     """as_format can successfully return a PIL image"""
     toga_image = toga.Image(ABSOLUTE_FILE_PATH)
     pil_image = toga_image.as_format(PIL.Image.Image)
     assert isinstance(pil_image, PIL.Image.Image)
-    assert pil_image.size == (32, 32)
+    assert pil_image.size == (144, 72)
 
 
 # None is same as supplying nothing; also test a random unrecognized class

core/tests/test_window.py

@@ -4,7 +4,6 @@
 import pytest
 
 import toga
-import toga_dummy
 from toga_dummy.utils import (
     assert_action_not_performed,
     assert_action_performed,
@@ -351,8 +350,8 @@ def test_as_image(window):
     """A window can be captured as an image"""
     image = window.as_image()
     assert_action_performed(window, "get image data")
-    path = Path(toga_dummy.__file__).parent / "resources/screenshot.png"
-    assert image.data == path.read_bytes()
+    # Don't need to check the raw data; just check it's the right size.
+    assert image.size == (318, 346)
 
 
 def test_info_dialog(window, app):

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.