extra_platforms package¶

Expose package-wide elements.

extra_platforms.current_os()[source]¶

Always returns the best matching platform for the current environment.

If multiple platforms match the current environment, this function will try to select the best, informative one.

Raises an error if we can’t decide on a single, appropriate platform.

Return type:: Platform

extra_platforms.current_platforms()[source]¶

Evaluates all heuristics and returns a list of Platform matching the current environment.

Always raises an error if the current environment is not recognized.

Return type:: tuple[Platform, ...]

..attention::: At this point it is too late to worry about caching. This function has no choice but to evaluate all platforms detection heuristics.

class extra_platforms.Group(id, name, icon='❓', platforms=<factory>)[source]¶

Bases: object

A Group identify a collection of Platform.

Used to group platforms of the same family.

set-like methods are available and performed on the platform objects the group contains (in the self.platforms data field).

Todo

Replace the platforms/platform_ids combo fields with a single platforms field that is a simple dict of platform ID to platform object. But maybe that going to be too much of a hassle because a dict cannot be frozen.

copy(id=None, name=None, icon=None, platforms=None)[source]¶

Return a shallow copy of the group.

Fields can be overridden by passing new values as arguments.

Return type:: Group

difference(*others)[source]¶

Return a new Group with platforms in the group that are not in the others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

fullyintersects(other)[source]¶

Return True if the group has all platforms in common with other.

Return type:: bool

icon: str = '❓'¶: Icon of the group.

intersection(*others)[source]¶

Return a new Group with platforms common to the group and all others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

isdisjoint(other)[source]¶

Return True if the group has no platforms in common with other.

Groups are disjoint if and only if their intersection is an empty set.

other can be an arbitrarily nested Iterable of Group and Platform.

Return type:: bool

issubset(other)[source]¶

Test whether every platforms in the group is in other.

Return type:: bool

issuperset(other)[source]¶

Test whether every platform in other is in the group.

Return type:: bool

items()[source]¶

Iterate over the platforms of the group as key-value pairs.

Return type:: Iterator[tuple[str, Platform]]

property short_desc: str¶

Returns the group name with its first letter in lowercase to be used as a short description.

Mainly used to produce docstrings for function dynamically generated for each group.

symmetric_difference(other)[source]¶

Return a new Group with platforms in either the group or other but not both.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

union(*others)[source]¶

Return a new Group with platforms from the group and all others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

id: str¶: Unique ID of the group.

name: str¶: User-friendly description of a group.

platforms: tuple[Platform, ...]¶: Sorted list of platforms that belong to this group.

platform_ids: frozenset[str]¶: Set of platform IDs that belong to this group.

extra_platforms.groups_from_ids(*group_ids)[source]¶

Returns a deduplicated tuple of groups matching the provided IDs.

IDs are case-insensitive.

Return type:: tuple[Group]

..tip::: If you want to reduce the returned set and removes as much overlaps as possible, you can use the extra_platforms.reduce() function on the results.

extra_platforms.is_aix()[source]¶

Return True if current platform is AIX.

Return type:: bool

extra_platforms.is_all_platforms()¶

Returns True if the current platform is part of the group composed of all platforms, False otherwise.

Return type:: bool

extra_platforms.is_altlinux()[source]¶

Return True if current platform is ALT Linux.

Return type:: bool

extra_platforms.is_amzn()[source]¶

Return True if current platform is Amazon Linux.

Return type:: bool

extra_platforms.is_android()[source]¶

Return True if current platform is Android.

Source: https://github.com/kivy/kivy/blob/master/kivy/utils.py#L429

Return type:: bool

extra_platforms.is_any_windows()¶

Returns True if the current platform is part of the group composed of any Windows, False otherwise.

Return type:: bool

extra_platforms.is_arch()[source]¶

Return True if current platform is Arch Linux.

Return type:: bool

extra_platforms.is_bsd()¶

Returns True if the current platform is part of the group composed of any BSD, False otherwise.

Return type:: bool

extra_platforms.is_bsd_without_macos()¶

Returns True if the current platform is part of the group composed of any BSD excluding macOS, False otherwise.

Return type:: bool

extra_platforms.is_buildroot()[source]¶

Return True if current platform is Buildroot.

Return type:: bool

extra_platforms.is_centos()[source]¶

Return True if current platform is CentOS.

Return type:: bool

extra_platforms.is_cloudlinux()[source]¶

Return True if current platform is CloudLinux OS.

Return type:: bool

extra_platforms.is_cygwin()[source]¶

Return True if current platform is Cygwin.

Return type:: bool

extra_platforms.is_debian()[source]¶

Return True if current platform is Debian.

Return type:: bool

extra_platforms.is_exherbo()[source]¶

Return True if current platform is Exherbo Linux.

Return type:: bool

extra_platforms.is_fedora()[source]¶

Return True if current platform is Fedora.

Return type:: bool

extra_platforms.is_freebsd()[source]¶

Return True if current platform is FreeBSD.

Return type:: bool

extra_platforms.is_gentoo()[source]¶

Return True if current platform is GenToo Linux.

Return type:: bool

extra_platforms.is_guix()[source]¶

Return True if current platform is Guix System.

Return type:: bool

extra_platforms.is_hurd()[source]¶

Return True if current platform is GNU/Hurd.

Return type:: bool

extra_platforms.is_ibm_powerkvm()[source]¶

Return True if current platform is IBM PowerKVM.

Return type:: bool

extra_platforms.is_kvmibm()[source]¶

Return True if current platform is KVM for IBM z Systems.

Return type:: bool

extra_platforms.is_linux()¶

Returns True if the current platform is part of the group composed of any Linux distribution, False otherwise.

Return type:: bool

extra_platforms.is_linux_layers()¶

Returns True if the current platform is part of the group composed of any Linux compatibility layers, False otherwise.

Return type:: bool

extra_platforms.is_linux_like()¶

Returns True if the current platform is part of the group composed of any Linux and compatibility layers, False otherwise.

Return type:: bool

extra_platforms.is_linuxmint()[source]¶

Return True if current platform is Linux Mint.

Return type:: bool

extra_platforms.is_macos()[source]¶

Return True if current platform is macOS.

Return type:: bool

extra_platforms.is_mageia()[source]¶

Return True if current platform is Mageia.

Return type:: bool

extra_platforms.is_mandriva()[source]¶

Return True if current platform is Mandriva Linux.

Return type:: bool

extra_platforms.is_midnightbsd()[source]¶

Return True if current platform is MidnightBSD.

Return type:: bool

extra_platforms.is_netbsd()[source]¶

Return True if current platform is NetBSD.

Return type:: bool

extra_platforms.is_nobara()[source]¶

Return True if current platform is Nobara Linux.

Return type:: bool

extra_platforms.is_openbsd()[source]¶

Return True if current platform is OpenBSD.

Return type:: bool

extra_platforms.is_opensuse()[source]¶

Return True if current platform is openSUSE.

Return type:: bool

extra_platforms.is_oracle()[source]¶

Return True if current platform is Oracle Linux (and Oracle Enterprise Linux).

Return type:: bool

extra_platforms.is_other_unix()¶

Returns True if the current platform is part of the group composed of any other Unix, False otherwise.

Return type:: bool

extra_platforms.is_parallels()[source]¶

Return True if current platform is Parallels.

Return type:: bool

extra_platforms.is_pidora()[source]¶

Return True if current platform is Pidora.

Return type:: bool

extra_platforms.is_raspbian()[source]¶

Return True if current platform is Raspbian.

Return type:: bool

extra_platforms.is_rhel()[source]¶

Return True if current platform is RedHat Enterprise Linux.

Return type:: bool

extra_platforms.is_rocky()[source]¶

Return True if current platform is Rocky Linux.

Return type:: bool

extra_platforms.is_scientific()[source]¶

Return True if current platform is Scientific Linux.

Return type:: bool

extra_platforms.is_slackware()[source]¶

Return True if current platform is Slackware.

Return type:: bool

extra_platforms.is_sles()[source]¶

Return True if current platform is SUSE Linux Enterprise Server.

Return type:: bool

extra_platforms.is_solaris()[source]¶

Return True if current platform is Solaris.

Return type:: bool

extra_platforms.is_sunos()[source]¶

Return True if current platform is SunOS.

Return type:: bool

extra_platforms.is_system_v()¶

Returns True if the current platform is part of the group composed of any Unix derived from AT&T System Five, False otherwise.

Return type:: bool

extra_platforms.is_tumbleweed()[source]¶

Return True if current platform is openSUSE Tumbleweed.

Return type:: bool

extra_platforms.is_tuxedo()[source]¶

Return True if current platform is Tuxedo OS.

Return type:: bool

extra_platforms.is_ubuntu()[source]¶

Return True if current platform is Ubuntu.

Return type:: bool

extra_platforms.is_unix()¶

Returns True if the current platform is part of the group composed of any Unix, False otherwise.

Return type:: bool

extra_platforms.is_unix_layers()¶

Returns True if the current platform is part of the group composed of any Unix compatibility layers, False otherwise.

Return type:: bool

extra_platforms.is_unix_without_macos()¶

Returns True if the current platform is part of the group composed of any Unix excluding macOS, False otherwise.

Return type:: bool

extra_platforms.is_unknown_linux()[source]¶

Return True if current platform is an unknown Linux.

Return type:: bool

extra_platforms.is_windows()[source]¶

Return True if current platform is Windows.

Return type:: bool

extra_platforms.is_wsl1()[source]¶

Return True if current platform is running over Windows Subsystem for Linux v1. :rtype: bool

Caution

The only difference between WSL1 and WSL2 is the case of the kernel release version:

WSL 1:
```
$ uname -r
4.4.0-22572-Microsoft
```

WSL 2:

$ uname -r
5.10.102.1-microsoft-standard-WSL2

extra_platforms.is_wsl2()[source]¶

Return True if current platform is running over Windows Subsystem for Linux v2.

Return type:: bool

extra_platforms.is_xenserver()[source]¶

Return True if current platform is XenServer.

Return type:: bool

class extra_platforms.Platform(id, name, icon='❓', url='')[source]¶

Bases: object

A platform can identify multiple distributions or OSes with the same characteristics.

It has a unique ID, a human-readable name, and boolean to flag current platform.

property current: bool¶

Returns whether the current platform is this one.

This is a property to avoid calling all platform detection heuristics on Platform objects creation, which happens at module import time.

icon: str = '❓'¶: Icon of the platform.

info()[source]¶

Returns all platform attributes we can gather.

Return type:: dict[str, str | bool | None | dict[str, str | None]]

property short_desc: str¶

Returns a short description of the platform.

Mainly used to produce docstrings for function dynamically generated for each group.

url: str = ''¶: URL to the platform’s official website.

id: str¶: Unique ID of the platform.

name: str¶: User-friendly name of the platform.

extra_platforms.platforms_from_ids(*platform_ids)[source]¶

Returns a deduplicated tuple of platforms matching the provided IDs.

IDs are case-insensitive, and can refer to any platforms or groups. Matching groups will be expanded to the platforms they contain.

Return type:: tuple[Platform]

..tip::: If you want to reduce the returned set and removes as much overlaps as possible, you can use the extra_platforms.reduce() function on the results.

extra_platforms.reduce(items, target_pool=None)[source]¶

Reduce a collection of platforms to a minimal set.

Returns a deduplicated set of Group and Platform that covers the same exact platforms as the original input, but group as much platforms as possible, to reduce the number of items.

Only the groups defined in the target_pool are considered for the reduction. If no reference pool is provided, use all known groups. :rtype: frozenset[Group | Platform]

Hint

Maybe this could be solved with some Euler diagram algorithms, like those implemented in eule.

This is being discussed upstream at trouchet/eule#120.

Todo

Should we rename or alias this method to collapse()? Cannot decide if it is more descriptive or not…

Submodules¶

extra_platforms.detection module¶

Heuristics to detect platforms.

This collection of heuristics is designed as a set of separate function with minimal logic and dependencies.

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 distribution rely on distro to gather as much details as possible. And also because it is the recommended replacement for Python’s original platform.linux_distribution function (which was removed in Python 3.8).

For all other platforms, we either rely on: - `sys.platform

<https://docs.python.org/3/library/sys.html#sys.platform>`_

platform.platform
platform.release
environment variables

extra_platforms.docs_update module¶

Automation to keep extra-platforms documentation up-to-date.

Tip

When the module is called directly, it will update all documentation files in-place:

$ run python -m extra_platforms.docs_update

See how it is used in .github/workflows/docs.yaml workflow.

extra_platforms.docs_update.replace_content(filepath, start_tag, end_tag, new_content)[source]¶

Replace in the provided file the content surrounded by the provided tags.

Return type:: None

extra_platforms.docs_update.generate_platform_sankey()[source]¶

Produce a Sankey diagram to map all platforms to their platforms.

Return type:: str

extra_platforms.docs_update.generate_platform_hierarchy()[source]¶

Produce a mindmap hierarchy to show the non-overlapping groups.

Return type:: str

extra_platforms.docs_update.generate_platforms_graph(graph_id, description, groups)[source]¶

Generates an Euler diagram of platform and their grouping.

Euler diagrams are not supported by mermaid yet so we fallback on a flowchart without arrows.

Returns a ready to use and properly indented MyST block.

Return type:: str

extra_platforms.docs_update.update_docs()[source]¶

Update documentation with dynamic content.

Return type:: None

extra_platforms.group module¶

Group models collection of platforms. Also referred as families or categories.

class extra_platforms.group.Group(id, name, icon='❓', platforms=<factory>)[source]¶

Bases: object

A Group identify a collection of Platform.

Used to group platforms of the same family.

set-like methods are available and performed on the platform objects the group contains (in the self.platforms data field).

Todo

id: str¶: Unique ID of the group.

name: str¶: User-friendly description of a group.

icon: str = '❓'¶: Icon of the group.

platforms: tuple[Platform, ...]¶: Sorted list of platforms that belong to this group.

platform_ids: frozenset[str]¶: Set of platform IDs that belong to this group.

property short_desc: str¶

Returns the group name with its first letter in lowercase to be used as a short description.

Mainly used to produce docstrings for function dynamically generated for each group.

items()[source]¶

Iterate over the platforms of the group as key-value pairs.

Return type:: Iterator[tuple[str, Platform]]

isdisjoint(other)[source]¶

Return True if the group has no platforms in common with other.

Groups are disjoint if and only if their intersection is an empty set.

other can be an arbitrarily nested Iterable of Group and Platform.

Return type:: bool

fullyintersects(other)[source]¶

Return True if the group has all platforms in common with other.

Return type:: bool

issubset(other)[source]¶

Test whether every platforms in the group is in other.

Return type:: bool

issuperset(other)[source]¶

Test whether every platform in other is in the group.

Return type:: bool

union(*others)[source]¶

Return a new Group with platforms from the group and all others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

intersection(*others)[source]¶

Return a new Group with platforms common to the group and all others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

difference(*others)[source]¶

Return a new Group with platforms in the group that are not in the others.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

symmetric_difference(other)[source]¶

Return a new Group with platforms in either the group or other but not both.

Return type:: Group

..caution::: The new Group will inherits the metadata of the first one. All other groups’ metadata will be ignored.

copy(id=None, name=None, icon=None, platforms=None)[source]¶

Return a shallow copy of the group.

Fields can be overridden by passing new values as arguments.

Return type:: Group

extra_platforms.group_data module¶

Definitions of ready-to-use groups.

extra_platforms.group_data.ALL_PLATFORMS: Group = Group(id='all_platforms', name='All platforms', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'windows', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'}))¶: All recognized platforms.

extra_platforms.group_data.ANY_WINDOWS = Group(id='any_windows', name='Any Windows', platform_ids=frozenset({'windows'}))¶: All Windows operating systems.

extra_platforms.group_data.UNIX = Group(id='unix', name='Any Unix', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'}))¶: All Unix-like operating systems and compatibility layers.

extra_platforms.group_data.UNIX_WITHOUT_MACOS = Group(id='unix_without_macos', name='Any Unix excluding macOS', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'}))¶

All Unix platforms, without macOS.

This is useful to avoid macOS-specific workarounds on Unix platforms.

extra_platforms.group_data.BSD = Group(id='bsd', name='Any BSD', platform_ids=frozenset({'freebsd', 'midnightbsd', 'macos', 'sunos', 'openbsd', 'netbsd'}))¶

All BSD platforms.

Note

Are considered of this family (according Wikipedia):

386BSD (FreeBSD, NetBSD, OpenBSD, DragonFly BSD)
NeXTSTEP
Darwin (macOS, iOS, audioOS, iPadOS, tvOS, watchOS, bridgeOS)
SunOS
Ultrix

extra_platforms.group_data.BSD_WITHOUT_MACOS = Group(id='bsd_without_macos', name='Any BSD excluding macOS', platform_ids=frozenset({'freebsd', 'midnightbsd', 'sunos', 'openbsd', 'netbsd'}))¶

All BSD platforms, without macOS.

This is useful to avoid macOS-specific workarounds on BSD platforms.

extra_platforms.group_data.LINUX = Group(id='linux', name='Any Linux distribution', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'altlinux', 'tuxedo'}))¶

All distributions based on a Linux kernel.

Note

Are considered of this family (according Wikipedia):

Android
ChromeOS
any other distribution

extra_platforms.group_data.LINUX_LAYERS = Group(id='linux_layers', name='Any Linux compatibility layers', platform_ids=frozenset({'wsl2', 'wsl1'}))¶

Interfaces that allows Linux binaries to run on a different host system.

Note

Are considered of this family (according Wikipedia):

Windows Subsystem for Linux

extra_platforms.group_data.LINUX_LIKE = Group(id='linux_like', name='Any Linux and compatibility layers', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'tuxedo'}))¶: Sum of all Linux distributions and Linux compatibility layers.

extra_platforms.group_data.SYSTEM_V = Group(id='system_v', name='Any Unix derived from AT&T System Five', platform_ids=frozenset({'aix', 'solaris'}))¶

All Unix platforms derived from AT&T System Five.

Note

Are considered of this family (according Wikipedia):

A/UX
AIX
HP-UX
IRIX
OpenServer
Solaris
OpenSolaris
Illumos
Tru64
UNIX
UnixWare

extra_platforms.group_data.UNIX_LAYERS = Group(id='unix_layers', name='Any Unix compatibility layers', platform_ids=frozenset({'cygwin'}))¶

Interfaces that allows Unix binaries to run on a different host system.

Note

Are considered of this family (according Wikipedia):

Cygwin
Darling
Eunice
GNV
Interix
MachTen
Microsoft POSIX subsystem
MKS Toolkit
PASE
P.I.P.S.
PWS/VSE-AF
UNIX System Services
UserLAnd Technologies
Windows Services for UNIX

extra_platforms.group_data.OTHER_UNIX = Group(id='other_unix', name='Any other Unix', platform_ids=frozenset({'hurd'}))¶

All other Unix platforms.

Note

Are considered of this family (according Wikipedia):

Coherent
GNU/Hurd
HarmonyOS
LiteOS
LynxOS
Minix
MOS
OSF/1
QNX
BlackBerry 10
Research Unix
SerenityOS

extra_platforms.group_data.NON_OVERLAPPING_GROUPS: frozenset[Group] = frozenset({Group(id='any_windows', name='Any Windows', platform_ids=frozenset({'windows'})), Group(id='other_unix', name='Any other Unix', platform_ids=frozenset({'hurd'})), Group(id='system_v', name='Any Unix derived from AT&T System Five', platform_ids=frozenset({'aix', 'solaris'})), Group(id='unix_layers', name='Any Unix compatibility layers', platform_ids=frozenset({'cygwin'})), Group(id='linux', name='Any Linux distribution', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'altlinux', 'tuxedo'})), Group(id='bsd', name='Any BSD', platform_ids=frozenset({'freebsd', 'midnightbsd', 'macos', 'sunos', 'openbsd', 'netbsd'})), Group(id='linux_layers', name='Any Linux compatibility layers', platform_ids=frozenset({'wsl2', 'wsl1'}))})¶: Non-overlapping groups.

extra_platforms.group_data.EXTRA_GROUPS: frozenset[Group] = frozenset({Group(id='bsd_without_macos', name='Any BSD excluding macOS', platform_ids=frozenset({'freebsd', 'midnightbsd', 'sunos', 'openbsd', 'netbsd'})), Group(id='linux_like', name='Any Linux and compatibility layers', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'tuxedo'})), Group(id='unix_without_macos', name='Any Unix excluding macOS', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'})), Group(id='unix', name='Any Unix', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'})), Group(id='all_platforms', name='All platforms', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'windows', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'}))})¶: Overlapping groups, defined for convenience.

extra_platforms.group_data.ALL_GROUPS: frozenset[Group] = frozenset({Group(id='unix_without_macos', name='Any Unix excluding macOS', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'})), Group(id='unix', name='Any Unix', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'})), Group(id='any_windows', name='Any Windows', platform_ids=frozenset({'windows'})), Group(id='other_unix', name='Any other Unix', platform_ids=frozenset({'hurd'})), Group(id='system_v', name='Any Unix derived from AT&T System Five', platform_ids=frozenset({'aix', 'solaris'})), Group(id='unix_layers', name='Any Unix compatibility layers', platform_ids=frozenset({'cygwin'})), Group(id='linux', name='Any Linux distribution', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'altlinux', 'tuxedo'})), Group(id='bsd_without_macos', name='Any BSD excluding macOS', platform_ids=frozenset({'freebsd', 'midnightbsd', 'sunos', 'openbsd', 'netbsd'})), Group(id='bsd', name='Any BSD', platform_ids=frozenset({'freebsd', 'midnightbsd', 'macos', 'sunos', 'openbsd', 'netbsd'})), Group(id='linux_layers', name='Any Linux compatibility layers', platform_ids=frozenset({'wsl2', 'wsl1'})), Group(id='linux_like', name='Any Linux and compatibility layers', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'sles', 'debian', 'ubuntu', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'kvmibm', 'rocky', 'arch', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'tuxedo'})), Group(id='all_platforms', name='All platforms', platform_ids=frozenset({'buildroot', 'oracle', 'opensuse', 'rhel', 'macos', 'wsl2', 'centos', 'slackware', 'ibm_powerkvm', 'nobara', 'openbsd', 'hurd', 'solaris', 'android', 'exherbo', 'amzn', 'linuxmint', 'parallels', 'mageia', 'pidora', 'scientific', 'tumbleweed', 'gentoo', 'raspbian', 'midnightbsd', 'sles', 'debian', 'ubuntu', 'windows', 'fedora', 'xenserver', 'cloudlinux', 'guix', 'freebsd', 'kvmibm', 'rocky', 'arch', 'cygwin', 'mandriva', 'unknown_linux', 'wsl1', 'altlinux', 'sunos', 'tuxedo', 'netbsd', 'aix'}))})¶: All groups.

extra_platforms.operations module¶

Operations on a mix of Groups and Platforms.

extra_platforms.operations.ALL_PLATFORM_IDS: FrozenSet[str] = frozenset({'aix', 'altlinux', 'amzn', 'android', 'arch', 'buildroot', 'centos', 'cloudlinux', 'cygwin', 'debian', 'exherbo', 'fedora', 'freebsd', 'gentoo', 'guix', 'hurd', 'ibm_powerkvm', 'kvmibm', 'linuxmint', 'macos', 'mageia', 'mandriva', 'midnightbsd', 'netbsd', 'nobara', 'openbsd', 'opensuse', 'oracle', 'parallels', 'pidora', 'raspbian', 'rhel', 'rocky', 'scientific', 'slackware', 'sles', 'solaris', 'sunos', 'tumbleweed', 'tuxedo', 'ubuntu', 'unknown_linux', 'windows', 'wsl1', 'wsl2', 'xenserver'})¶: Set of all recognized platform IDs.

extra_platforms.operations.ALL_GROUP_IDS: FrozenSet[str] = frozenset({'all_platforms', 'any_windows', 'bsd', 'bsd_without_macos', 'linux', 'linux_layers', 'linux_like', 'other_unix', 'system_v', 'unix', 'unix_layers', 'unix_without_macos'})¶: Set of all recognized group IDs.

extra_platforms.operations.ALL_IDS: FrozenSet[str] = frozenset({'aix', 'all_platforms', 'altlinux', 'amzn', 'android', 'any_windows', 'arch', 'bsd', 'bsd_without_macos', 'buildroot', 'centos', 'cloudlinux', 'cygwin', 'debian', 'exherbo', 'fedora', 'freebsd', 'gentoo', 'guix', 'hurd', 'ibm_powerkvm', 'kvmibm', 'linux', 'linux_layers', 'linux_like', 'linuxmint', 'macos', 'mageia', 'mandriva', 'midnightbsd', 'netbsd', 'nobara', 'openbsd', 'opensuse', 'oracle', 'other_unix', 'parallels', 'pidora', 'raspbian', 'rhel', 'rocky', 'scientific', 'slackware', 'sles', 'solaris', 'sunos', 'system_v', 'tumbleweed', 'tuxedo', 'ubuntu', 'unix', 'unix_layers', 'unix_without_macos', 'unknown_linux', 'windows', 'wsl1', 'wsl2', 'xenserver'})¶: Set of all recognized platform and group IDs.

extra_platforms.operations.platforms_from_ids(*platform_ids)[source]¶

Returns a deduplicated tuple of platforms matching the provided IDs.

IDs are case-insensitive, and can refer to any platforms or groups. Matching groups will be expanded to the platforms they contain.

Return type:: tuple[Platform]

..tip::: If you want to reduce the returned set and removes as much overlaps as possible, you can use the extra_platforms.reduce() function on the results.

extra_platforms.operations.groups_from_ids(*group_ids)[source]¶

Returns a deduplicated tuple of groups matching the provided IDs.

IDs are case-insensitive.

Return type:: tuple[Group]

..tip::: If you want to reduce the returned set and removes as much overlaps as possible, you can use the extra_platforms.reduce() function on the results.

extra_platforms.operations.reduce(items, target_pool=None)[source]¶

Reduce a collection of platforms to a minimal set.

Returns a deduplicated set of Group and Platform that covers the same exact platforms as the original input, but group as much platforms as possible, to reduce the number of items.

Only the groups defined in the target_pool are considered for the reduction. If no reference pool is provided, use all known groups. :rtype: frozenset[Group | Platform]

Hint

Maybe this could be solved with some Euler diagram algorithms, like those implemented in eule.

This is being discussed upstream at trouchet/eule#120.

Todo

Should we rename or alias this method to collapse()? Cannot decide if it is more descriptive or not…

extra_platforms.platform module¶

Platforms, also known as Operating Systems.

Everything here can be aggressively cached and frozen, as it’s only compute platform-dependent values.

class extra_platforms.platform.Platform(id, name, icon='❓', url='')[source]¶

Bases: object

A platform can identify multiple distributions or OSes with the same characteristics.

It has a unique ID, a human-readable name, and boolean to flag current platform.

id: str¶: Unique ID of the platform.

name: str¶: User-friendly name of the platform.

icon: str = '❓'¶: Icon of the platform.

url: str = ''¶: URL to the platform’s official website.

property short_desc: str¶

Returns a short description of the platform.

Mainly used to produce docstrings for function dynamically generated for each group.

property current: bool¶

Returns whether the current platform is this one.

This is a property to avoid calling all platform detection heuristics on Platform objects creation, which happens at module import time.

info()[source]¶

Returns all platform attributes we can gather.

Return type:: dict[str, str | bool | None | dict[str, str | None]]

extra_platforms.platform_data module¶

Platform definitions and metadata.

Note

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

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

extra_platforms.platform_data.NOBARA = Platform(id='nobara', name='Nobara')¶: Note

Instead of using a loose Unicode icon for the Nobara OS, or just not adding any, we are using a NerdFont icon instead:  (i.e. nf-linux-nobara / f380).

The side-effect of using a NerdFont character is it will only display correctly when using a supported font. Otherwise, it will appear as an unknown or invisible character depending on the fonts.

Todo

In the future, we may want to have two icons for each platform, one that is Unicode-based, the other that is NerdFont-based.

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.