Platform

Usage

Although Toga is a cross-platform framework, and in theory shouldn't require any special platform-specific handling, in practice you will. If you wish to apply platform-specific modifications to your user interface, or modify business logic on a per-platform basis, you may need to know the currently active backend, or the platform on which your application is running. This can be achieved by using toga.backend and toga.platform.current_platform.

For example:

import toga

if toga.backend == `toga_gtk`:
    # ... perform GTK-specific logic

if toga.platform.current_platform == 'android':
    # ... perform Android-specific business logic

Selecting a specific backend

In general, a Python environment should only have a single Toga backend installed. However, if you need to install multiple backends, you can tell Toga which backend to use by setting the TOGA_BACKEND environment variable to match the name of the Python module for the backend you wish to use (e.g., toga_gtk).

Getting an implementation factory

Developers who want to implement new platform-dependent functionality, or produce a new backend, need a way to access the implementation classes for the current backend. The get_factory function provides a standard way to do this, returning an object whose attributes are lazily-loaded implementation classes.

See the topic guide on Extending Toga for more information.

Reference

The name of the backend that is being used by Toga to implement platform-specific capabilities (e.g., toga_cocoa, toga_gtk).

A string identifier of the platform on which the application is currently running. One of:

• android
• macOS
• iOS
• linux
• freeBSD
• web
• windows

DEPRECATED: This property exists for historical reasons. On Python 3.13 and later, you can use the Python standard library property [sys.platform][].

It is required on Python 3.12 and earlier because Android historically returned sys.platform == "linux" until the android value was formalied by PEP 783. The names used by current_platform do not exactly match the names returned by [sys.platform][].

Return the implementation factory for an interface group.

The object that is returned is a namespace whose attributes are the implementation classes for the current backend contributed by the appropriate entry points.

:param interface: the name of the interface group for the factory, or None for the default "toga_core" interface. Third-party interface group names should start with "togax_". :returns: The factory namespace object.

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

@cache
def get_factory(interface: str | None = None) -> Factory | ModuleType:
    """Return the implementation factory for an interface group.

    The object that is returned is a namespace whose attributes are the
    implementation classes for the current backend contributed by the
    appropriate entry points.

    :param interface: the name of the interface group for the factory, or None
        for the default `"toga_core"` interface.  Third-party interface group
        names should start with `"togax_"`.
    :returns: The factory namespace object.
    """
    factory = Factory(interface)
    # -------------------------------------------------------------------------
    # 2026-02: Backwards compatibility for version <= 0.5.3
    # -------------------------------------------------------------------------
    # If we can't find the entrypoint group we expect, drop back to the old
    # system using a factory module
    if interface is None and len(entry_points(group=factory.group)) == 0:
        backend = get_backend()
        try:
            factory = importlib.import_module(f"{backend}.factory")
        except ModuleNotFoundError as exc:
            toga_backends_values = ", ".join([f"{b.value!r}" for b in find_backends()])
            # Android doesn't report Python exception chains in crashes
            # (https://github.com/chaquo/chaquopy/issues/890), so include the original
            # exception message in case the backend does exist but throws a
            # ModuleNotFoundError from one of its internal imports.
            raise RuntimeError(
                f"The backend specified by TOGA_BACKEND ({backend!r}) could "
                f"not be loaded ({exc}). It should be one of: {toga_backends_values}."
            ) from exc
    # -------------------------------------------------------------------------
    # End backwards compatibility
    # -------------------------------------------------------------------------
    return factory