pyxpo-device

Facts about the device a pyxpo app runs on, written in Python: brand, model, OS and version, memory, CPU architectures, phone or tablet, uptime and Android system features. The names follow expo-device, in Python style.

import pyxpo_device as Device

print(Device.brand, Device.model_name, Device.os_name, Device.os_version)   # "Google", "sdk_gphone64_arm64", "Android", "15"
if Device.device_type == Device.DeviceType.TABLET:
    ...
uptime_ms = await Device.get_uptime_async()

Features

• Constants with no bridge call: brand, model, OS, memory and the rest are read once at startup and are plain attributes of the module.
• Phone, tablet, TV or desktop: Device.device_type is a DeviceType enum, worked out from the platform's own idiom and the screen size.
• Runs on the desktop too: the web page and the desktop window fill the same fields from Python's platform module, so layout code can run the same everywhere.
• Android extras: the runtime memory limit, the list of system features, a feature check (android.hardware.camera) and whether the app may install other apps.
• Honest values: a value a platform does not have is None, not a guess. The rooted check is documented as easy to fool.
• No permissions: nothing here needs a prompt, an entitlement or a manifest entry.
• Typed: ships py.typed. Every name also has its expo-device spelling (Device.modelName, Device.getUptimeAsync).

Contents

Platform support

Requires Python 3.9+ and pyxpo>=0.1.0a2.

Install

pip install pyxpo-device

Add the module to your app's pyproject.toml:

[tool.pyxpo]
modules = ["device"]

The module has native code, so rebuild the app after adding it (pyxpo run android or pyxpo run ios).

Quick start

import pyxpo_device as Device
from pyxpo import Text, View, component, use_async


@component
def DeviceInfo():
    uptime = use_async(Device.get_uptime_async, [])     # (loading, value, error)
    hours = (uptime.value or 0) / 3_600_000
    return View(
        Text("%s %s" % (Device.brand or "", Device.model_name or "")),
        Text("%s %s" % (Device.os_name, Device.os_version)),
        Text("Up for %.1f hours" % hours),
        Text("Tablet" if Device.device_type == Device.DeviceType.TABLET else "Phone"),
    )

Tip: the constants resolve when you read them, not when the module is imported, because the startup environment is not there yet at import time. Read them inside a component or a function. Do not copy them into module-level variables at import.

Constants

Read once at app start. None where a platform has no value.

is_device and emulators

is_device is False on the iOS Simulator and, on a best-effort basis, on the Android emulator. Use it to skip features that need real hardware (haptics, camera). Do not use it for security.

Device type

if Device.device_type == Device.DeviceType.TABLET:
    columns = 3

await Device.get_device_type_async() returns the same value as the constant.

Memory and uptime

total = Device.total_memory                       # bytes of RAM
limit = await Device.get_max_memory_async()       # Android: the runtime limit; elsewhere MAX_SAFE_INTEGER
ms = await Device.get_uptime_async()              # milliseconds since boot, not counting deep sleep

MAX_SAFE_INTEGER (2 ** 53 - 1) is what expo-device returns when memory has no inherent limit, which is the case on iOS and the desktop.

Android system features

if await Device.has_platform_feature_async("android.hardware.camera"):
    show_camera_button()
names = await Device.get_platform_features_async()        # every feature the device reports

has_platform_feature_async(feature) takes a non-empty string and raises ValueError otherwise. On iOS and the desktop it returns False, and get_platform_features_async() returns [].

is_side_loading_enabled_async() tells whether this app may install other apps. It needs the REQUEST_INSTALL_PACKAGES permission on Android 8 and later, and is always False on iOS and the desktop.

is_rooted_experimental_async() is a best-effort jailbreak or root check. It is easy to fool, so never use it as a security decision.

Errors

Config

There are no module options and no config plugin. The only native setup is the modules entry.

Web and desktop

The same names work. Values come from Python's platform module (uname()), total_memory from sysconf where available, device_type is DESKTOP, brand and model are None, and get_uptime_async() uses the monotonic clock. is_rooted_experimental_async(), is_side_loading_enabled_async() and has_platform_feature_async() return False.

Recipe: a diagnostics line for support

One line the user can paste into a support email.

import pyxpo_application as Application
import pyxpo_device as Device


def diagnostics() -> str:
    gb = (Device.total_memory or 0) / 1024 ** 3
    parts = [
        "%s %s" % (Device.brand or "?", Device.model_name or "?"),
        "%s %s" % (Device.os_name, Device.os_version),
        "%.1f GB" % gb,
        "app %s" % (Application.native_application_version or "dev"),
    ]
    if Device.platform_api_level:
        parts.append("API %s" % Device.platform_api_level)
    if not Device.is_device:
        parts.append("emulator")
    return " | ".join(parts)

Production checklist

• No decision about security or licensing depends on is_rooted_experimental_async() or is_device.
• Layouts do not assume a phone: DeviceType.TABLET and DESKTOP are handled.
• Android-only values (platform_api_level, model_id on iOS) are None-checked.
• A feature that needs hardware checks has_platform_feature_async before showing its button.
• Device names (device_name) are not sent to your server without the user knowing.

Testing

Constants are read through pyxpo.module_api. Patch _all to control them:

import pyxpo_device as Device


def test_tablet_layout(monkeypatch):
    monkeypatch.setattr(Device, "_all", lambda: {**{k: None for k in Device._FIELDS}, "deviceType": 2})
    assert Device.device_type == Device.DeviceType.TABLET

On the desktop test host the values come from Python's platform module, and device_type is DESKTOP.

Troubleshooting

FAQ

Is device_name the user's name? It is the name in the device settings. On iOS 16 and later Apple returns a generic name such as "iPhone" unless the app has a special entitlement.

Does it need any permission? No.

Is the tablet check reliable? On iOS it follows the interface idiom (iPad is a tablet). On Android it follows TV mode and a 600dp screen width.

Why total_memory and not free memory? It is the installed RAM. Free memory changes every second and is not something the system promises to report.

API reference

Constants

is_device, brand, manufacturer, model_name, model_id, design_name, product_name, device_year_class, total_memory, supported_cpu_architectures, os_name, os_version, os_build_id, os_internal_build_id, os_build_fingerprint, platform_api_level, device_name, device_type. Each has a camelCase twin.

Functions

Types

License

MIT