Groups

Group usage

Todo

Explain high-level usage of groups here. Including membership testing and set operations. And how to create custom groups (from scratch or by combining existing groups).

All groups

All recognized groups and their properties:

Icon

Symbol

Description

Detection

Canonical

🏛️

ALL_ARCHITECTURES

All architectures

is_any_architecture()

📱

ALL_ARM

ARM architectures

is_any_arm()

⬥

♺

ALL_CI

CI systems

is_any_ci()

⬥

🔲

ALL_MIPS

MIPS architectures

is_any_mips()

⬥

⚙️

ALL_PLATFORMS

All platforms

is_any_platform()

☀️

ALL_SPARC

SPARC architectures

is_any_sparc()

⬥

⁕

ALL_TRAITS

All architectures, platforms and CI systems

is_any_trait()

🪟

ALL_WINDOWS

All Windows

is_any_windows()

⬥

³²

ARCH_32_BIT

32-bit architectures

is_arch_32_bit()

⁶⁴

ARCH_64_BIT

64-bit architectures

is_arch_64_bit()

🅱️+

BSD

All BSD

is_bsd()

⬥

🅱️

BSD_WITHOUT_MACOS

All BSD excluding macOS

is_bsd_not_macos()

🏢

IBM_MAINFRAME

IBM mainframe

is_ibm_mainframe()

⬥

🐧

LINUX

Linux distributions

is_linux()

⬥

≚

LINUX_LAYERS

Linux compatibility layers

is_linux_layers()

⬥

🐧+

LINUX_LIKE

All Linux & compatibility layers

is_linux_like()

🐉

LOONGARCH

LoongArch

is_loongarch()

⬥

🅟

OTHER_POSIX

Other POSIX-compliant platforms

is_other_posix()

⬥

⚡

POWERPC

PowerPC family

is_powerpc()

⬥

Ⅴ

RISCV

RISC-V family

is_riscv()

⬥

𝐕

SYSTEM_V

AT&T System Five

is_system_v()

⬥

⨷

UNIX

All Unix

is_unix()

≛

UNIX_LAYERS

Unix compatibility layers

is_unix_layers()

⬥

⨂

UNIX_WITHOUT_MACOS

All Unix excluding macOS

is_unix_not_macos()

❓

UNKNOWN

Unknown

is_unknown()

⬥

🌐

WEBASSEMBLY

WebAssembly

is_webassembly()

⬥

𝘅

X86

x86 family

is_x86()

⬥

Hint

Canonical groups are non-overlapping groups that together cover all recognized traits. They are marked with a ⬥ icon in the table above.

Other groups are provided for convenience, but overlap with each other or with canonical groups.

Predefined groups

extra_platforms.ALL_ARCHITECTURES = Group(id='all_architectures', name='All architectures')

A Group identifies a collection of Trait members.

Additionally of the common fields inherited from _Identifiable, each group provides:

extra_platforms.ALL_ARM = Group(id='all_arm', name='ARM architectures')

All ARM-based architectures.

extra_platforms.ALL_CI = Group(id='all_ci', name='CI systems')

All recognized Continuous Integration systems.

Caution

This group does not contain the UNKNOWN_CI trait.

See also

List of known CI systems.

extra_platforms.ALL_MIPS = Group(id='all_mips', name='MIPS architectures')

All MIPS-based architectures.

extra_platforms.ALL_PLATFORMS = Group(id='all_platforms', name='All platforms')

A Group identifies a collection of Trait members.

Additionally of the common fields inherited from _Identifiable, each group provides:

extra_platforms.ALL_SPARC = Group(id='all_sparc', name='SPARC architectures')

All SPARC-based architectures.

extra_platforms.ALL_TRAITS = Group(id='all_traits', name='All architectures, platforms and CI systems')

All predefined architectures, platforms and CI systems.

Hint

This group includes all UNKNOWN_* traits.

extra_platforms.ALL_WINDOWS = Group(id='all_windows', name='All Windows')

All Windows operating systems.

extra_platforms.ARCH_32_BIT = Group(id='arch_32_bit', name='32-bit architectures')

All 32-bit architectures.

extra_platforms.ARCH_64_BIT = Group(id='arch_64_bit', name='64-bit architectures')

All 64-bit architectures.

extra_platforms.BSD = Group(id='bsd', name='All BSD')

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.BSD_WITHOUT_MACOS = Group(id='bsd_without_macos', name='All BSD excluding macOS')

All BSD platforms, without macOS.

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

extra_platforms.IBM_MAINFRAME = Group(id='ibm_mainframe', name='IBM mainframe')

IBM mainframe architectures.

extra_platforms.LINUX = Group(id='linux', name='Linux distributions')

All distributions based on a Linux kernel.

Note

Are considered of this family (according Wikipedia):

  • Android

  • ChromeOS

  • any other distribution

extra_platforms.LINUX_LAYERS = Group(id='linux_layers', name='Linux compatibility layers')

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.LINUX_LIKE = Group(id='linux_like', name='All Linux & compatibility layers')

Sum of all Linux distributions and Linux compatibility layers.

extra_platforms.LOONGARCH = Group(id='loongarch', name='LoongArch')

LoongArch architecture.

extra_platforms.OTHER_POSIX = Group(id='other_posix', name='Other POSIX-compliant platforms')

All other UNIX-like or POSIX-compliant 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.POWERPC = Group(id='powerpc', name='PowerPC family')

All PowerPC-based architectures.

extra_platforms.RISCV = Group(id='riscv', name='RISC-V family')

All RISC-V-based architectures.

extra_platforms.SYSTEM_V = Group(id='system_v', name='AT&T System Five')

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.UNIX = Group(id='unix', name='All Unix')

All Unix-like operating systems and compatibility layers.

extra_platforms.UNIX_LAYERS = Group(id='unix_layers', name='Unix compatibility layers')

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.UNIX_WITHOUT_MACOS = Group(id='unix_without_macos', name='All Unix excluding macOS')

All Unix platforms, without macOS.

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

extra_platforms.UNKNOWN = Group(id='unknown', name='Unknown')

Unknown or unrecognized traits.

extra_platforms.WEBASSEMBLY = Group(id='webassembly', name='WebAssembly')

WebAssembly architectures.

extra_platforms.X86 = Group(id='x86', name='x86 family')

All x86-based architectures (Intel-compatible).

Todo

List and document group collections: ALL_GROUP_IDS, ALL_TRAIT_IDS, ALL_IDS, …

Group implementation

        classDiagram
  _Identifiable <|-- Group

Group a collection of traits. Also referred as families.

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

Bases: _Identifiable

A Group identifies a collection of Trait members.

Additionally of the common fields inherited from _Identifiable, each group provides:

  • members: An iterable of Trait instances that belong to this group.

  • member_ids: A frozenset of member IDs for quick lookup.

  • canonical: A bool indicating if the group is canonical (non-overlapping).

  • various set-like operations (union, intersection, difference, etc.).

unknown_symbol: ClassVar[str] = 'UNKNOWN'

Groups use UNKNOWN instead of UNKNOWN_GROUP.

members: Iterable[Trait]

Traits in this group.

Normalized to MappingProxyType[str, Trait] at init, providing O(1) lookup by ID.

property member_ids: frozenset[str]

Set of member IDs that belong to this group.

property canonical: bool

Returns True if the group is canonical (non-overlapping), False otherwise.

A canonical group is one that does not share any members with other canonical groups. All canonical groups are non-overlapping.

Non-canonical groups are provided for convenience, but overlap with each other or with canonical groups.

Hint

Canonical groups are denoted with a ⬥ symbol in the documentation and tables.

items()[source]

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

Return type:

Iterator[tuple[str, Trait]]

isdisjoint(other)[source]

Return True if the group has no members 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 Trait.

Return type:

bool

fullyintersects(other)[source]

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

Return type:

bool

issubset(other)[source]

Test whether every member in the group is in other.

Return type:

bool

issuperset(other)[source]

Test whether every member in other is in the group.

Return type:

bool

union(*others)[source]

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

Caution

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

Return type:

Group

intersection(*others)[source]

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

Caution

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

Return type:

Group

difference(*others)[source]

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

Caution

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

Return type:

Group

symmetric_difference(other)[source]

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

Caution

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

Return type:

Group

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

Return a shallow copy of the group.

Fields can be overridden by passing new values as arguments.

Return type:

Group

add(member)[source]

Return a new Group with the specified trait added.

If the trait is already in the group, returns a copy unchanged.

Return type:

Group

Args:

member: A Trait object or trait ID string to add.

Returns:

A new Group instance with the trait added.

Raises:

ValueError: If the trait ID is not recognized.

remove(member)[source]

Return a new Group with the specified trait removed.

Raises KeyError if the trait is not in the group.

Return type:

Group

Args:

member: A Trait object or trait ID string to remove.

Returns:

A new Group instance with the trait removed.

Raises:

KeyError: If the trait is not in the group.

discard(member)[source]

Return a new Group with the specified trait removed if present.

Unlike remove(), this does not raise an error if the trait is not found.

Return type:

Group

Args:

member: A Trait object or trait ID string to remove.

Returns:

A new Group instance with the trait removed, or a copy if not present.

all_group: ClassVar[str] = 'ALL_GROUPS'

The symbol name for the group containing all instances of this type.

data_module_id: ClassVar[str] = 'group_data'

The module name where instances of this type are defined.

doc_page: ClassVar[str] = 'groups.md'

The documentation page filename.

pop(member_id=None)[source]

Remove and return a trait from the group.

Return type:

tuple[Trait, Group]

Args:
member_id: Optional trait ID to remove. If not provided, removes an arbitrary

trait (specifically, the first one in iteration order).

Returns:

A tuple of (removed_trait, new_group).

Raises:

KeyError: If member_id is provided but not found in the group. KeyError: If the group is empty.

type_id: ClassVar[str] = 'group'

Machine-readable type identifier used to derive module and symbol names.

type_name: ClassVar[str] = 'group'

Human-readable type name for documentation.

id: str

Unique ID of the object.

symbol_id: str

Symbolic identifier.

This is the variable name under which the instance can be accessed at the root of the extra_platforms module.

Mainly useful for documentation generation.

detection_func_id: str

ID of the detection function for this object.

The detection function is expected to be named is_<id>() and available at the root of the extra_platforms module.

skip_decorator_id: str

ID of the Pytest skip decorator for this object.

The decorator is expected to be named @skip_<id> and available from the extra_platforms.pytest module.

unless_decorator_id: str

ID of the Pytest unless decorator for this object.

The decorator is expected to be named @unless_<id> and available from the extra_platforms.pytest module.

name: str

User-friendly name of the object.

clear()[source]

Return a new empty Group with the same metadata.

Return type:

Group

Returns:

A new Group instance with no members but same id, name, and icon.

Definitions of ready-to-use groups.