extra_platforms package¶

Expose package-wide elements.

Important

Exposing everything at package level here motivates platforms and groups to have a unique and unambiguous ID. This constraint is enforced at the data-level and checked in unittests.

Hint

The content of pytest.py file is not imported here to make dependency on Pytest optional.

Todo

In 16.0.0, remove the deprecated aliases that extra_platforms/_deprecated.py registers, the _types._TNestedReferences alias, and their tests.

Submodules¶

extra_platforms.agent_data module¶

Agent definitions and metadata.

extra_platforms.architecture_data module¶

Architecture definitions and metadata.

Hint

Architecture’s canonical IDs are inspired by those used in auditwheel project to encode the manylinux policies.

See also

Architecture variants from Rust’s target-lexicon.

extra_platforms.ci_data module¶

CI definitions and metadata.

extra_platforms.detection module¶

Heuristics to detect all traits of the current environment.

This collection of heuristics is designed as a set of separate function with minimal logic and dependencies. They’re the building blocks to evaluate the current environment.

All these heuristics can be hard-cached as the underlying system is not changing between code execution. They are still allowed to depends on each others, as long as you’re careful of not implementing circular dependencies.

Warning

Even if highly unlikely, it is possible to have multiple platforms detected for the same environment.

Typical example is Ubuntu WSL, which will make both the is_wsl2() and is_ubuntu() functions return True at the same time.

That’s because of the environment metadata, where:

$ uname -a
Linux 5.15.167.4-microsoft-standard-WSL2

$ cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04.5 LTS"

That way we have the possibility elsewhere in extra-platforms to either decide if we only allow one, and only one, heuristic to match the current system, or allow for considering multiple systems at the same time.

Detection of Linux distributions relies on /etc/os-release, as specified by the os-release specification. Every modern Linux distribution (since 2012) ships this file. A system hiding both copies of it is identified through systemd-hostnamed instead, as implemented in platform_info.

For all other traits, we either rely on:

See also

Other source of inspiration for platform detection:

extra_platforms.group module¶

Group a collection of traits. Also referred as families.

extra_platforms.group_data module¶

Definitions of ready-to-use groups.

This module contains all predefined Group instances and frozenset collections that organize traits into logical categories.

extra_platforms.platform_data module¶

Platform definitions and metadata.

Important

Not every distribution gets a dedicated entry. The granularity policy is:

  • Independent derivative distributions each get their own platform, even when they build on a parent distribution. Ubuntu, Kali Linux, Linux Mint, Raspbian and PikaOS are all Debian derivatives, but each is managed by its own organization, with its own identity, release cadence and package repositories.

  • Release channels, variants and flavors of a single distribution, managed by the same organization as the parent, are folded into the parent’s platform. Every openSUSE channel (Tumbleweed, Leap, Slowroll, MicroOS, …) is detected as OPENSUSE by its is_opensuse() detection function, while the raw channel ID remains available through Platform.info().

Note

Default icons are inspired from Starship project: - https://starship.rs/config/#os - https://github.com/starship/starship/blob/master/.github/config-schema.json

Some icons, especially Linux distributions, have their own dedicated codepoints in NerdFonts.

extra_platforms.platform_info module¶

Platform-specific information gathering.

This module provides utilities to fetch detailed version and codename information for all platforms: Linux distributions (via /etc/os-release), webOS TV (via /etc/starfish-release too), macOS and Windows.

Linux reads /etc/os-release, then /usr/lib/os-release. When neither file is readable, _hostnamectl_os_release() asks systemd-hostnamed for the same identity over D-Bus and rebuilds the os-release fields from its answer.

See also

The os-release specification defines the format and fields of /etc/os-release.

extra_platforms.shell_data module¶

Shell definitions and metadata.

extra_platforms.terminal_data module¶

Terminal definitions and metadata.

extra_platforms.pytest module¶

Pytest decorators to skip tests depending on the platform they’re run on.

Generates a pair of ready-to-use @skip_<id> and @unless_<id> decorators for each platform and group.

Note

Type checkers like mypy do not run module code, so they cannot see the decorators generated at import time. The MarkDecorator declarations under TYPE_CHECKING at the end of this module make them visible.

extra_platforms.trait module¶

Trait base class for architectures, platforms, shells, terminals, and more.

A trait represents a distinguishing characteristic of a runtime environment. Each trait has a unique ID, a human-readable name, an icon, and the ability to detect if it matches the current environment.

Data associated with traits can be aggressively cached and frozen, as they’re only computed based on environment-dependent values.

Note

No annotation in this module reads typing.ClassVar. A dataclass recognizes a ClassVar field only once typing is imported, and nothing else in the package needs typing at runtime. The class-level metadata lives on _ClassMetadata instead, a plain class no dataclass reads fields from.