Groups¶

Group usage¶

A Group is a collection of Trait instances (platforms, architectures, or CI systems). Groups support membership testing, iteration, and set-like operations.

Membership testing¶

Check whether the current environment matches any member of a group:

>>> from extra_platforms import is_linux
>>> is_linux()
True

Test if a specific trait belongs to a group. You can you both Trait instances and their string IDs:

>>> from extra_platforms import LINUX, UBUNTU, MACOS
>>> UBUNTU in LINUX
True
>>> MACOS in LINUX
False
>>> "ubuntu" in LINUX
True

Iteration¶

Groups are iterable and sized:

>>> from extra_platforms import BSD
>>> len(BSD)
7
>>> for platform in BSD:
...     print(platform.id)
dragonfly_bsd
freebsd
macos
midnightbsd
netbsd
openbsd
sunos

Set operations¶

Groups support standard set operations, returning new Group instances:

>>> from extra_platforms import BSD, BSD_WITHOUT_MACOS, LINUX, MACOS
>>> only_macos = BSD.difference(BSD_WITHOUT_MACOS)
>>> only_macos.member_ids
frozenset({'macos'})
>>> combined = BSD.union(LINUX)
>>> MACOS in combined
True

Set operations also have operator overloads for more concise syntax:

>>> from extra_platforms import BSD, BSD_WITHOUT_MACOS, LINUX, MACOS
>>> only_macos = BSD - BSD_WITHOUT_MACOS
>>> only_macos.member_ids
frozenset({'macos'})
>>> combined = BSD | LINUX
>>> MACOS in combined
True

Available operations: union() (|), intersection() (&), difference() (-), symmetric_difference() (^), issubset(), issuperset(), and isdisjoint().

Mutating-style operations¶

Groups are immutable (frozen dataclasses), but provide methods that return new instances:

>>> from extra_platforms import BSD, AIX
>>> extended = BSD.add(AIX)
>>> AIX in extended
True
>>> AIX in BSD
False
>>> shrunk = BSD.remove("macos")
>>> "macos" in shrunk
False

See also: discard(), pop(), clear(), and copy().

Creating custom groups¶

Build new groups from scratch or by combining existing ones:

>>> from extra_platforms import Group, UBUNTU, DEBIAN, MACOS
>>> my_targets = Group("my_targets", "My Targets", "🎯", (UBUNTU, DEBIAN, MACOS))
>>> len(my_targets)
3

Hint

You can check my other Meta Package Manager project for a real life example, where I use Group to manage families of target platforms for software packaging.

Reducing traits to groups¶

The reduce() function finds the minimal set of groups and traits that covers a given collection:

>>> from extra_platforms import reduce, FREEBSD, NETBSD, OPENBSD, MACOS
>>> reduce([FREEBSD, NETBSD, OPENBSD, MACOS])
frozenset({BSD})

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()`
⬆️	`BIG_ENDIAN`	Big-endian architectures	`is_big_endian()`
🅱️+	`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()`
⬇️	`LITTLE_ENDIAN`	Little-endian architectures	`is_little_endian()`
🐉	`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')¶

All recognized architectures.

Caution

This group does not contain the UNKNOWN_ARCHITECTURE trait.

ID: all_architectures
Name: All architectures
Icon: 🏛️
Canonical: False
Detection function: is_any_architecture()
Pytest decorators: @skip_all_architectures / @unless_any_architecture
Members (25 Architecture): AARCH64, ARM, ARMV5TEL, ARMV6L, ARMV7L, ARMV8L, I386, I586, I686, LOONGARCH64, MIPS, MIPS64, MIPS64EL, MIPSEL, PPC, PPC64, PPC64LE, RISCV32, RISCV64, S390X, SPARC, SPARC64, WASM32, WASM64, X86_64

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

All ARM-based architectures.

ID: all_arm
Name: ARM architectures
Icon: 📱
Canonical: True ⬥
Detection function: is_any_arm()
Pytest decorators: @skip_all_arm / @unless_any_arm
Members (6 Architecture): AARCH64, ARM, ARMV5TEL, ARMV6L, ARMV7L, ARMV8L

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.

Group collections¶

extra_platforms.group_data.ALL_ARCHITECTURE_GROUPS: frozenset[Group] = frozenset({Group(id='big_endian', name='Big-endian architectures'), Group(id='arch_32_bit', name='32-bit architectures'), Group(id='ibm_mainframe', name='IBM mainframe'), Group(id='webassembly', name='WebAssembly'), Group(id='arch_64_bit', name='64-bit architectures'), Group(id='x86', name='x86 family'), Group(id='all_arm', name='ARM architectures'), Group(id='all_sparc', name='SPARC architectures'), Group(id='powerpc', name='PowerPC family'), Group(id='riscv', name='RISC-V family'), Group(id='loongarch', name='LoongArch'), Group(id='all_mips', name='MIPS architectures'), Group(id='little_endian', name='Little-endian architectures'), Group(id='all_architectures', name='All architectures')})¶: All groups whose members are Architecture.

extra_platforms.group_data.ALL_CI_GROUPS: frozenset[Group] = frozenset({Group(id='all_ci', name='CI systems')})¶: All groups whose members are CI.

Note

Not that useful as there is only one CI group, but provided for symmetry with ALL_ARCHITECTURE_GROUPS and ALL_PLATFORM_GROUPS.

extra_platforms.group_data.ALL_GROUPS: frozenset[Group] = frozenset({Group(id='arch_32_bit', name='32-bit architectures'), Group(id='other_posix', name='Other POSIX-compliant platforms'), Group(id='ibm_mainframe', name='IBM mainframe'), Group(id='arch_64_bit', name='64-bit architectures'), Group(id='unix', name='All Unix'), Group(id='x86', name='x86 family'), Group(id='unix_without_macos', name='All Unix excluding macOS'), Group(id='unknown', name='Unknown'), Group(id='all_windows', name='All Windows'), Group(id='linux', name='Linux distributions'), Group(id='all_platforms', name='All platforms'), Group(id='all_mips', name='MIPS architectures'), Group(id='big_endian', name='Big-endian architectures'), Group(id='webassembly', name='WebAssembly'), Group(id='all_arm', name='ARM architectures'), Group(id='all_sparc', name='SPARC architectures'), Group(id='powerpc', name='PowerPC family'), Group(id='riscv', name='RISC-V family'), Group(id='loongarch', name='LoongArch'), Group(id='all_architectures', name='All architectures'), Group(id='all_ci', name='CI systems'), Group(id='unix_layers', name='Unix compatibility layers'), Group(id='linux_layers', name='Linux compatibility layers'), Group(id='linux_like', name='All Linux & compatibility layers'), Group(id='bsd_without_macos', name='All BSD excluding macOS'), Group(id='bsd', name='All BSD'), Group(id='system_v', name='AT&T System Five'), Group(id='little_endian', name='Little-endian architectures'), Group(id='all_traits', name='All architectures, platforms and CI systems')})¶: All predefined groups.

Hint

This collection contains both canonical and non-canonical groups, including the UNKNOWN group.

extra_platforms.group_data.ALL_PLATFORM_GROUPS: frozenset[Group] = frozenset({Group(id='other_posix', name='Other POSIX-compliant platforms'), Group(id='system_v', name='AT&T System Five'), Group(id='linux_like', name='All Linux & compatibility layers'), Group(id='unix_layers', name='Unix compatibility layers'), Group(id='linux_layers', name='Linux compatibility layers'), Group(id='linux', name='Linux distributions'), Group(id='bsd_without_macos', name='All BSD excluding macOS'), Group(id='unix_without_macos', name='All Unix excluding macOS'), Group(id='bsd', name='All BSD'), Group(id='unix', name='All Unix'), Group(id='all_windows', name='All Windows'), Group(id='all_platforms', name='All platforms')})¶: All groups whose members are Platform.

extra_platforms.group_data.EXTRA_GROUPS: frozenset[Group] = frozenset({Group(id='big_endian', name='Big-endian architectures'), Group(id='arch_32_bit', name='32-bit architectures'), Group(id='arch_64_bit', name='64-bit architectures'), Group(id='linux_like', name='All Linux & compatibility layers'), Group(id='bsd_without_macos', name='All BSD excluding macOS'), Group(id='unix_without_macos', name='All Unix excluding macOS'), Group(id='unix', name='All Unix'), Group(id='all_platforms', name='All platforms'), Group(id='little_endian', name='Little-endian architectures'), Group(id='all_architectures', name='All architectures'), Group(id='all_traits', name='All architectures, platforms and CI systems')})¶: Overlapping groups, defined for convenience.

Hint

None of these groups are marked as canonical.

extra_platforms.group_data.NON_OVERLAPPING_GROUPS: frozenset[Group] = frozenset({Group(id='other_posix', name='Other POSIX-compliant platforms'), Group(id='ibm_mainframe', name='IBM mainframe'), Group(id='webassembly', name='WebAssembly'), Group(id='all_ci', name='CI systems'), Group(id='x86', name='x86 family'), Group(id='all_arm', name='ARM architectures'), Group(id='system_v', name='AT&T System Five'), Group(id='unix_layers', name='Unix compatibility layers'), Group(id='all_sparc', name='SPARC architectures'), Group(id='powerpc', name='PowerPC family'), Group(id='riscv', name='RISC-V family'), Group(id='all_windows', name='All Windows'), Group(id='linux', name='Linux distributions'), Group(id='loongarch', name='LoongArch'), Group(id='linux_layers', name='Linux compatibility layers'), Group(id='bsd', name='All BSD'), Group(id='unknown', name='Unknown'), Group(id='all_mips', name='MIPS architectures')})¶: Non-overlapping groups.

Hint

These groups together cover all Architecture, Platform, and CI traits, including traits from the UNKNOWN group.

All groups in this collection are marked as canonical.

ID collections¶

extra_platforms.group_data.ALL_GROUP_IDS: frozenset[str] = frozenset({'all_architectures', 'all_arm', 'all_ci', 'all_mips', 'all_platforms', 'all_sparc', 'all_traits', 'all_windows', 'arch_32_bit', 'arch_64_bit', 'big_endian', 'bsd', 'bsd_without_macos', 'ibm_mainframe', 'linux', 'linux_layers', 'linux_like', 'little_endian', 'loongarch', 'other_posix', 'powerpc', 'riscv', 'system_v', 'unix', 'unix_layers', 'unix_without_macos', 'webassembly', 'x86'})¶: A frozenset of all recognized group IDs.

Attention

This collection does not contain the UNKNOWN group.

extra_platforms.group_data.ALL_IDS: frozenset[str] = frozenset({'aarch64', 'aix', 'all_architectures', 'all_arm', 'all_ci', 'all_mips', 'all_platforms', 'all_sparc', 'all_traits', 'all_windows', 'altlinux', 'amzn', 'android', 'arch', 'arch_32_bit', 'arch_64_bit', 'arm', 'armv5tel', 'armv6l', 'armv7l', 'armv8l', 'azure_pipelines', 'bamboo', 'big_endian', 'bsd', 'bsd_without_macos', 'buildkite', 'buildroot', 'cachyos', 'centos', 'circle_ci', 'cirrus_ci', 'cloudlinux', 'codebuild', 'cygwin', 'debian', 'dragonfly_bsd', 'exherbo', 'fedora', 'freebsd', 'gentoo', 'github_ci', 'gitlab_ci', 'guix', 'haiku', 'heroku_ci', 'hurd', 'i386', 'i586', 'i686', 'ibm_mainframe', 'ibm_powerkvm', 'illumos', 'kvmibm', 'linux', 'linux_layers', 'linux_like', 'linuxmint', 'little_endian', 'loongarch', 'loongarch64', 'macos', 'mageia', 'mandriva', 'midnightbsd', 'mips', 'mips64', 'mips64el', 'mipsel', 'netbsd', 'nobara', 'openbsd', 'opensuse', 'oracle', 'other_posix', 'parallels', 'pidora', 'powerpc', 'ppc', 'ppc64', 'ppc64le', 'raspbian', 'rhel', 'riscv', 'riscv32', 'riscv64', 'rocky', 's390x', 'scientific', 'slackware', 'sles', 'solaris', 'sparc', 'sparc64', 'sunos', 'system_v', 'teamcity', 'travis_ci', 'tumbleweed', 'tuxedo', 'ubuntu', 'ultramarine', 'unix', 'unix_layers', 'unix_without_macos', 'wasm32', 'wasm64', 'webassembly', 'windows', 'wsl1', 'wsl2', 'x86', 'x86_64', 'xenserver'})¶: A frozenset of all recognized traits and group IDs.

Attention

This collection does not contain all the UNKNOWN_* traits and the UNKNOWN group.

extra_platforms.group_data.ALL_TRAIT_IDS: frozenset[str] = frozenset({'aarch64', 'aix', 'altlinux', 'amzn', 'android', 'arch', 'arm', 'armv5tel', 'armv6l', 'armv7l', 'armv8l', 'azure_pipelines', 'bamboo', 'buildkite', 'buildroot', 'cachyos', 'centos', 'circle_ci', 'cirrus_ci', 'cloudlinux', 'codebuild', 'cygwin', 'debian', 'dragonfly_bsd', 'exherbo', 'fedora', 'freebsd', 'gentoo', 'github_ci', 'gitlab_ci', 'guix', 'haiku', 'heroku_ci', 'hurd', 'i386', 'i586', 'i686', 'ibm_powerkvm', 'illumos', 'kvmibm', 'linuxmint', 'loongarch64', 'macos', 'mageia', 'mandriva', 'midnightbsd', 'mips', 'mips64', 'mips64el', 'mipsel', 'netbsd', 'nobara', 'openbsd', 'opensuse', 'oracle', 'parallels', 'pidora', 'ppc', 'ppc64', 'ppc64le', 'raspbian', 'rhel', 'riscv32', 'riscv64', 'rocky', 's390x', 'scientific', 'slackware', 'sles', 'solaris', 'sparc', 'sparc64', 'sunos', 'teamcity', 'travis_ci', 'tumbleweed', 'tuxedo', 'ubuntu', 'ultramarine', 'wasm32', 'wasm64', 'windows', 'wsl1', 'wsl2', 'x86_64', 'xenserver'})¶: A frozenset of all recognized traits IDs.

Attention

This collection does not contain all the UNKNOWN_* traits.

Trait and group operations¶

extra_platforms.extract_members(*other)[source]¶

Returns all traits found in other.

other can be an arbitrarily nested Iterable of Group, Trait, or their IDs. None values and empty iterables are silently ignored.

Caution

Can returns duplicates.

Return type:: Iterator[Trait]

extra_platforms.traits_from_ids(*trait_and_group_ids)[source]¶

Returns a deduplicated tuple of traits matching the provided IDs.

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

Aliases are automatically resolved to their canonical IDs, with a warning emitted to encourage using the canonical ID directly.

Order of the returned traits matches the order of the provided IDs.

Tip

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

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

extra_platforms.groups_from_ids(*group_ids)[source]¶

Returns a deduplicated tuple of groups matching the provided IDs.

IDs are case-insensitive.

Order of the returned Group instances matches the order of the provided IDs.

Tip

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

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

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

Reduce a collection of traits to a minimal set.

Returns a deduplicated set of Group and Trait that covers the same exact traits as the original input, but group as much traits 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.

Note

The algorithm is a variant of the Set Cover Problem, which is NP-hard. This implementation uses a greedy approximation that iteratively selects the largest group fitting the remaining uncovered traits.

Todo

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

Return type:: frozenset[Group | Trait]

Group implementation¶

class extra_platforms.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 at init, providing O(1) lookup by ID.

property _members: MappingProxyType¶: Typed access to members as MappingProxyType.

Warning

The members field is typed as Iterable to accept any iterable at construction time. After __post_init__, it is always a MappingProxyType. This property provides a cast() to that type, avoiding # type: ignore comments throughout the class.

__post_init__()[source]¶: Normalize members to a sorted, deduplicated mapping.

Hint

Docstring generation is deferred to avoid circular imports during module initialization. See _docstrings._initialize_all_docstrings().

generate_docstring()[source]¶

Generate comprehensive docstring for this group instance.

Combines the attribute docstring from the source module with various metadata.

Return type:: str

property member_ids: frozenset[str]¶: A frozenset of member IDs that belong to this group.

__hash__()[source]¶

Hash based on group ID and member IDs.

Return type:: int

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.

__iter__()[source]¶

Iterate over the members of the group.

Return type:: Iterator[Trait]

__len__()[source]¶

Return the number of members in the group.

Return type:: int

__bool__()[source]¶

Return True if the group has members, False otherwise.

Return type:: bool

__contains__(item)[source]¶

Test if Trait object or its ID is part of the group.

Return type:: bool

__getitem__(member_id)[source]¶

Return the trait whose ID is member_id.

Return type:: Trait

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

__le__(other)¶

Test whether every member in the group is in other.

Return type:: bool

__lt__(other)[source]¶

Test whether every member in the group is in other, but not all.

Return type:: bool

issuperset(other)[source]¶

Test whether every member in other is in the group.

Return type:: bool

__ge__(other)¶

Test whether every member in other is in the group.

Return type:: bool

__gt__(other)[source]¶

Test whether every member in other is in the group, but not all.

Return type:: bool

union(*others)[source]¶

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

Caution