Check platform compatibility against specific rules defined by platform hints.¶

This module provides utilities for restricting the availability of functions and classes to specific platforms through a hint-based system. Platform hints are normalized identifiers that represent different aspects of the system (API, kernel, operating system, Python implementation).

Hints are just words such as those returned by sys.platform (eg., win32, darwin, linux) or those found in the Python documentation under the Availability section (see https://docs.python.org/3/library/intro.html).

The hints() function generates a tuple of hints based on the current system. For example, on macOS it would return:

(‘posix’, ‘darwin’, ‘macos’, ‘cpython’)

The returned hints are ordered according to this hierarchy:

• API: nt or posix

• Kernel: win32, linux, darwin or the generic unix hint

• OS: macos, android, windows, freebsd, aix, …

• Implementation: cpython, pypy, jython, …

• Extra: mobile is set for iOS and Android

This classification while not perfect, minimizes the ambiguity caused by the multiple sources that developers face in the Python ecosystem (sys.platform, os.name, platform.system(), …) and mimics the Availability sections found in the Python documentation.

All returned hints and input hints in function calls are lowercased for disambiguation.

Examples

Restrict a function to POSIX systems except macOS:

>>> @availability(only='posix', but='darwin')
... def my_unix_function(a: int, b: int) -> int:
...     # Will run on Linux, FreeBSD, WASI, AIX, etc., but not macOS
...     return a + b

Restrict a function to desktop platforms (exclude mobile):

>>> @availability(only=None, but='mobile')
... def my_desktop_function(a: int, b: int) -> int:
...     # Will raise AvailabilityError on iOS and Android
...     return a * b

This module includes utilities to:

• Get platform hints based on the current system via hints()

• Check platform support against inclusion/exclusion rules via supported()

• Decorate functions and classes to restrict usage by platform via availability()

Module Contents¶

hints() → tuple[str, Ellipsis][source]¶

Get a tuple of platform hints based on the current system.

This function analyzes the current execution environment and returns a tuple of normalized platform hints that identify the system’s characteristics. The hints follow a hierarchical order: API, kernel, operating system, implementation, and any additional flags.

Returns:¶

tuple [ str , … ] – A tuple of platform hints describing the current system. All hints are lowercased.

exception AvailabilityError[source]¶

Extends: NotImplementedError

Exception raised when attempting to use a function or class on an unsupported platform.

This exception is raised by the availability() decorator when the decorated function or class is called or instantiated on a platform that does not meet the specified inclusion/exclusion criteria.

Inherits from:

NotImplementedError: To indicate that the functionality is not implemented for the current platform.

Initialize self. See help(type(self)) for accurate signature.

supported(only: tuple[str, Ellipsis] | str | None, but: tuple[str, Ellipsis] | str | None = None) → bool[source]¶

Check if the current platform is supported by the specified hints.

Evaluates whether the current platform matches the inclusion and exclusion criteria defined by the hints. A platform is supported if it matches any of the only hints (if specified) and does not match any of the but hints (if specified).

Parameters:¶

only: tuple[str, Ellipsis] | str | None¶

A single platform hint, a tuple of platform hints that should be supported, or None to allow all platforms.

but: tuple[str, Ellipsis] | str | None = None¶

A single platform hint, a tuple of platform hints that should not be supported, or None (default) to exclude no platforms.

Returns:¶

bool – True if the current platform is supported according to the rules, False otherwise.

availability(

only: tuple[str, Ellipsis] | str | None,

but: tuple[str, Ellipsis] | str | None = None,

) → collections.abc.Callable[[_T], _T][source]¶

Decorator to restrict the usage of a function or class to specific platforms.

The decorated callable will raises AvailabilityError if called on a platform that does not match the specified platform availability hints. Otherwise, it allows the decorated object to be used normally. For classes, the __new__ method is modified to raise the error at instantiation time. For functions, a wrapper is applied that raises the error on each call.

If the decorated callable has a docstring, an ‘Availability:’ one liner string will be append at its end.

Parameters:¶

only: tuple[str, Ellipsis] | str | None¶

A single platform hint, a tuple of platform hints that should be supported, or None to allow all platforms.

but: tuple[str, Ellipsis] | str | None = None¶

A single platform hint, a tuple of platform hints that should not be supported, or None (default) to exclude no platforms.

Returns:¶

The decorated function or class.