Image format plugins

Extensions that enable Toga to understand additional image formats.

Usage

Toga can be extended, via plugins, to understand externally defined image types, gaining the ability to convert them to and from its own toga.Image class. Toga's Pillow support is, in fact, implemented as a plugin that's included as part of the core Toga package.

An image format plugin consists of two things:

• a converter class conforming to the ImageConverter protocol, with methods defining how to convert to and from your image class
• an entry point in the toga.image_formats group telling Toga the path to your converter class.

Let's say you want to tell Toga how to handle an image class called MyImage, and you're publishing your plugin as a package named togax-myimage (see package prefixes) that contains a plugins.py module that defines your MyImageConverter plugin class. Your pyproject.toml might include something like the following:

[project.entry-points."toga.image_formats"]
myimage = "togax_myimage.plugins.MyImageConverter"

The variable name being assigned to (myimage in this case) can be whatever you like (although it should probably have some relationship to the image format name) What matters is the string assigned to it, which represents where Toga can find (and import) your ImageConverter class.

Package prefixes

An image plugin can be registered from any Python module. If you maintain a package defining an image format, you could include a Toga converter plugin along with it. If you're publishing a plugin as a standalone package, you should title it with a togax- prefix, to indicate that it's an unofficial extension for Toga. Do not use the toga- prefix, as the BeeWare Project wishes to reserve that package prefix for "official" packages.

Reference

Any class that represents an image.

Bases: Protocol

A class to convert between an externally defined image type and toga.Image.

Source code in core/src/toga/images.py

class ImageConverter(Protocol):
    """A class to convert between an externally defined image type and
    [`toga.Image`][].
    """

    image_class: type[ExternalImageT]
    """The base image class this plugin can interpret."""

    @staticmethod
    def convert_from_format(image_in_format: ExternalImageT) -> BytesLikeT:
        """Convert from [`image_class`][toga.images.ImageConverter.image_class] to
        data in a [known image format][known-image-formats].

        Will accept an instance of
        [`image_class`][toga.images.ImageConverter.image_class],
        or subclass of that class.

        :param image_in_format: An instance of
            [`image_class`][toga.images.ImageConverter.image_class] (or a subclass).
        :returns: The image data, in a [known image format][known-image-formats].
        """

    @staticmethod
    def convert_to_format(
        data: BytesLikeT,
        image_class: type[ExternalImageT],
    ) -> ExternalImageT:
        """Convert from data to [`image_class`][toga.images.ImageConverter.image_class]
        or specified subclass.

        Accepts a bytes-like object representing the image in a
        [known image format][known-image-formats], and returns an instance of the
        image class specified. This image class is guaranteed to be either the
        [`image_class`][toga.images.ImageConverter.image_class] registered by the
        plugin, or a subclass of that class.

        :param data: Image data in a [known image format][known-image-formats].
        :param image_class: The class of image to return.
        :returns: The image, as an instance of the image class specified.
        """

image_class instance-attribute

The base image class this plugin can interpret.

convert_from_format(image_in_format) staticmethod

Convert from image_class to data in a known image format.

Will accept an instance of image_class, or subclass of that class.

:param image_in_format: An instance of image_class (or a subclass). :returns: The image data, in a known image format.

Source code in core/src/toga/images.py

@staticmethod
def convert_from_format(image_in_format: ExternalImageT) -> BytesLikeT:
    """Convert from [`image_class`][toga.images.ImageConverter.image_class] to
    data in a [known image format][known-image-formats].

    Will accept an instance of
    [`image_class`][toga.images.ImageConverter.image_class],
    or subclass of that class.

    :param image_in_format: An instance of
        [`image_class`][toga.images.ImageConverter.image_class] (or a subclass).
    :returns: The image data, in a [known image format][known-image-formats].
    """

convert_to_format(data, image_class) staticmethod

Convert from data to image_class or specified subclass.

Accepts a bytes-like object representing the image in a known image format, and returns an instance of the image class specified. This image class is guaranteed to be either the image_class registered by the plugin, or a subclass of that class.

:param data: Image data in a known image format. :param image_class: The class of image to return. :returns: The image, as an instance of the image class specified.

Source code in core/src/toga/images.py

@staticmethod
def convert_to_format(
    data: BytesLikeT,
    image_class: type[ExternalImageT],
) -> ExternalImageT:
    """Convert from data to [`image_class`][toga.images.ImageConverter.image_class]
    or specified subclass.

    Accepts a bytes-like object representing the image in a
    [known image format][known-image-formats], and returns an instance of the
    image class specified. This image class is guaranteed to be either the
    [`image_class`][toga.images.ImageConverter.image_class] registered by the
    plugin, or a subclass of that class.

    :param data: Image data in a [known image format][known-image-formats].
    :param image_class: The class of image to return.
    :returns: The image, as an instance of the image class specified.
    """