debian._arch_table module

architecture matching

This leverages code from dpkg’s Dpkg::Arch as well as python rewrites from other people. Copyright years imported from the sources.

@copyright: 2006-2015 Guillem Jover <guillem@debian.org> @copyright: 2014, Ansgar Burchardt <ansgar@debian.org> @copyright: 2014-2017, Johannes Schauer Marin Rodrigues <josch@debian.org> @copyright: 2022, Niels Thykier <niels@thykier.net> @license: GPL-2+

class debian._arch_table.CPUDetail(debian_name: str, gnu_name: str, config_guess_regex: str, bits: int, endianness: str)

Bases: object

class debian._arch_table.DpkgArchTable(arch2tuple: dict[str, DpkgArchitecture], valid_architectures: list[DpkgArchitecture], cputable: dict[str, CPUDetail], ostable: dict[str, tuple[str, ...]])

Bases: object

classmethod _from_file(tuple_table_fd: IO[str], os_table_fd: IO[str], cpu_table_fd: IO[str], triplet_compat: bool = False) → DpkgArchTable
_resolve_dpkg_arch(dpkg_arch: str) → DpkgArchitecture
_resolve_dpkg_wildcard(arch: str) → DpkgArchitecture
all_valid_dpkg_architectures() → Iterator[DpkgArchitecture]

Returns the list of valid dpkg architectures

This method is the closest match to dpkg’s Dpkg::Arch::get_valid_arches function.

architecture_equals(arch1: str, arch2: str) → bool

Determine whether two dpkg architecture are exactly the same [debarch_eq]

Unlike Python’s == operator, this method also accounts for things like linux-amd64 is a valid spelling of the dpkg architecture amd64 (i.e., architecture_equals(“linux-amd64”, “amd64”) is True).

This method is the closest match to dpkg’s Dpkg::Arch::debarch_eq function.

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.architecture_equals("linux-amd64", "amd64")
True
>>> arch_table.architecture_equals("amd64", "linux-i386")
False
>>> arch_table.architecture_equals("i386", "linux-amd64")
False
>>> arch_table.architecture_equals("amd64", "amd64")
True
>>> arch_table.architecture_equals("i386", "amd64")
False
>>> # Compatibility with dpkg: if the parameters are equal, then it always return True
>>> arch_table.architecture_equals("unknown", "unknown")
True

Compatibility note: The method emulates Dpkg::Arch::debarch_eq function and therefore returns True if both parameters are the same even though they are wildcards or not known to be architectures.

Parameters:

  • arch1 – A string representing a dpkg architecture.

  • arch2 – A string representing a dpkg architecture.

Returns:

True if the dpkg architecture parameters are (logically) the exact same.

architecture_is_concerned(architecture: str, architecture_restrictions: Iterable[str], allow_mixing_positive_and_negative: bool = False) → bool

Determine if a dpkg architecture is part of a list of restrictions [debarch_is_concerned]

This method is the closest match to dpkg’s Dpkg::Arch::debarch_is_concerned function.

Compatibility notes:

  • The Dpkg::Arch::debarch_is_concerned function allow matching of negative and positive restrictions by default. Often, this behaviour is not allowed nor recommended and the Debian Policy does not allow this practice in e.g., Build-Depends. Therefore, this implementation defaults to raising ValueError when this occurs. If the original behaviour is needed, set allow_mixing_positive_and_negative to True.

  • The Dpkg::Arch::debarch_is_concerned function is lazy and exits as soon as it finds a match. This means that if negative and positive restrictions are mixed, then order of the matches are important. This adaption matches that behaviour (provided that allow_mixing_positive_and_negative is set to True)

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.architecture_is_concerned("linux-amd64", ["amd64", "i386"])
True
>>> arch_table.architecture_is_concerned("amd64", ["!amd64", "!i386"])
False
>>> # This is False because the "!amd64" is matched first.
>>> arch_table.architecture_is_concerned("linux-amd64", ["!linux-amd64", "linux-any"],
...                                      allow_mixing_positive_and_negative=True)
False
>>> # This is True because the "linux-any" is matched first.
>>> arch_table.architecture_is_concerned("linux-amd64", ["linux-any", "!linux-amd64"],
...                                      allow_mixing_positive_and_negative=True)
True
Parameters:

  • architecture – A string representing a dpkg architecture/wildcard.

  • architecture_restrictions – A list of positive (amd64) or negative (!amd64) dpkg architectures or/and wildcards.

  • allow_mixing_positive_and_negative – If True, the architecture_restrictions list can mix positive and negative (e.g., [“!any-amd64”, “any”]) restrictions. If False, mixing will trigger a ValueError.

Returns:

True if architecture is accepted by the architecture_restrictions.

dpkg_arch_to_multiarch(dpkg_arch: str) → str

Return the multiarch name for a given dpkg architecture [debarch_to_multiarch]

This method is the closest match to dpkg’s Dpkg::Arch::debarch_to_multiarch function.

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.dpkg_arch_to_multiarch("amd64")
'x86_64-linux-gnu'
>>> arch_table.dpkg_arch_to_multiarch("armhf")
'arm-linux-gnueabihf'
Parameters:

dpkg_arch – A string representing a dpkg architecture.

Returns:

The multiarch name corresponding to the dpkg architecture.

get(item: str) → DpkgArchitecture | None
is_wildcard(wildcard: str) → bool

Determine if a given string is a dpkg wildcard [debarch_is_wildcard]

This method is the closest match to dpkg’s Dpkg::Arch::debarch_is_wildcard function.

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.is_wildcard("linux-any")
True
>>> arch_table.is_wildcard("amd64")
False
>>> arch_table.is_wildcard("unknown")
False
>>> # Compatibility with the dpkg version of the function.
>>> arch_table.is_wildcard("unknown-any")
True
Compatibility note: The original dpkg function does not ensure that the wildcard matches

any supported architecture and this re-implementation matches that behaviour. Therefore, this method can return True for a wildcard that can never match anything in practice.

Parameters:

wildcard – A string that might represent a dpkg architecture or wildcard.

Returns:

True the parameter is a known dpkg wildcard.

classmethod load_arch_table(path: str | PathLike[str] = '/usr/share/dpkg') → DpkgArchTable

Load the Dpkg Architecture Table

This class method loads the architecture table from dpkg, so it can be used.

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.matches_architecture("amd64", "any")
True

>>> # It is also possible to lookup DpkgArchitecture objects
>>> armel = arch_table["armel"]
>>> armel.debian_name()
'armel'
>>> armel.debian_cpu_name()
'arm'
>>> armel.os_name()
'linux'
>>> armel.cpu_bits()
32
>>> armel.cpu_endianness()
'little'
>>> # also supports partial `dpkg-architecture` names as aliases
>>> armel["ARCH_OS"]
'linux'

>>> # Wildcards are not supported in this mode currently. This is a deliberate choice,
>>> # since wildcards are special (multiple names point to the same alias, they match
>>> # multiple architectures, so some queries are unanswerable like bits and endianness)
>>> arch_table["linux-any"]
Traceback (most recent call last):
    ...
KeyError: 'linux-any'

The method assumes the dpkg “tuple arch” format version 1.0 or the older triplet format.

Parameters:

path – Choose a different directory for loading the architecture data. The provided directory must contain the architecture data files from dpkg (such as “tupletable” and “cputable”)

matches_architecture(architecture: str, alias: str) → bool

Determine if a dpkg architecture matches another architecture or a wildcard [debarch_is]

This method is the closest match to dpkg’s Dpkg::Arch::debarch_is function.

>>> arch_table = DpkgArchTable.load_arch_table()
>>> arch_table.matches_architecture("amd64", "linux-any")
True
>>> arch_table.matches_architecture("i386", "linux-any")
True
>>> arch_table.matches_architecture("amd64", "amd64")
True
>>> arch_table.matches_architecture("i386", "amd64")
False
>>> arch_table.matches_architecture("all", "amd64")
False
>>> arch_table.matches_architecture("all", "all")
True
>>> # i386 is the short form of linux-i386. Therefore, it does not match kfreebsd-i386
>>> arch_table.matches_architecture("i386", "kfreebsd-i386")
False
>>> # Note that "armel" and "armhf" are "arm" CPUs, so it is matched by "any-arm"
>>> # (similar holds for some other architecture <-> CPU name combinations)
>>> all(arch_table.matches_architecture(n, 'any-arm') for n in ['armel', 'armhf'])
True
>>> # Since "armel" is not a valid CPU name, this returns False (the correct would be
>>> # any-arm as noted above)
>>> arch_table.matches_architecture("armel", "any-armel")
False
>>> # Wildcards used as architecture always fail (except for special cases noted in the
>>> # compatibility notes below)
>>> arch_table.matches_architecture("any-i386", "i386")
False
>>> # any-i386 is not a subset of linux-any (they only have i386/linux-i386 as overlap)
>>> arch_table.matches_architecture("any-i386", "linux-any")
False
>>> # Compatibility with dpkg - if alias is `any` then it always returns True
>>> # even if the input otherwise would not make sense.
>>> arch_table.matches_architecture("any-unknown", "any")
True
>>> # Another side effect of the dpkg compatibility
>>> arch_table.matches_architecture("all", "any")
True

Compatibility note: The method emulates Dpkg::Arch::debarch_is function and therefore returns True if both parameters are the same even though they are wildcards or not known to be architectures. Additionally, if alias is any, then this method always returns True as any is the “match-everything-wildcard”.

Parameters:

  • architecture – A string representing a dpkg architecture.

  • alias – A string representing a dpkg architecture or wildcard to match with.

Returns:

True if the architecture parameter is (logically) the same as the alias parameter OR, if alias is a wildcard, the architecture parameter is a subset of the wildcard. The method returns False if architecture is not a known dpkg architecture, or it is a wildcard.

class debian._arch_table.DpkgArchitecture(name: str, arch_tuple: QuadTupleDpkgArchitecture, cputable: dict[str, CPUDetail], ostable: dict[str, tuple[str, ...]])

Bases: object

Representation of a dpkg architecture

This is also used internally by DpkgArchTable for wildcard, which is why wildcards are partially supported. However, the wildcard variant of this is never returned by any public method of DpkgArchTable nor is it part of the public API.

cpu_bits() → int

The CPU bits of this dpkg architecture

Matches the ARCH_BITS value of dpkg-architecture output for dpkg architectures.

Implementation detail: For CPU wildcards, it will raise as there is no clear single definition.

cpu_endianness() → str

The CPU endianness of this dpkg architecture

Matches the ARCH_ENDIAN value of dpkg-architecture output for dpkg architectures.

Implementation detail: For CPU wildcards, it will raise as there is no clear single definition.

debian_cpu_name() → str

The Debian CPU name of this dpkg architecture

Matches the ARCH_CPU value of dpkg-architecture output for dpkg architectures.

Note this is confusingly similar to the debian_name() for some architectures. However, it is important to not mistakenly use the wrong name here, debian_name() is the Debian name for the architecture such as armel where as debian_cpu_name() is the Debian name for the CPU such as arm.

Implementation detail: For wildcards, it can return any.

debian_name() → str

Name of the dpkg architecture or wildcard.

For dpkg architectures (that is, non-wildcards) this matches the name that dpkg uses for it. Wildcards can have multiple names for the same wildcard (linux-any & any-linux-any are both the same wildcard).

It is currently implementation defined which name variant is returned by this method for wildcards. Callers should cope if the implementation detail changes in the future.

property is_wildcard: bool

Whether this dpkg architecture is a form of wildcard

multiarch() → str

The multi-arch name of this dpkg architecture.

Matches the *_MULTIARCH value of dpkg-architecture output.

Implementation detail: Raises if this instance is a wildcard.

os_name() → str

The OS name of this dpkg architecture

Matches the ARCH_OS value of dpkg-architecture output for dpkg architectures.

Implementation detail: For wildcards, it can return any.

class debian._arch_table.QuadTupleDpkgArchitecture(api_name: str, libc_name: str, os_name: str, cpu_name: str)

Bases: object

Implementation detail of ArchTable

debtuple() → str
property is_wildcard: bool
class debian._arch_table._QuadTuple(api_name, libc_name, os_name, cpu_name)

Bases: tuple

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('api_name', 'libc_name', 'os_name', 'cpu_name')
classmethod _make(iterable)

Make a new _QuadTuple object from a sequence or iterable

_replace(**kwds)

Return a new _QuadTuple object replacing specified fields with new values

api_name

Alias for field number 0

cpu_name

Alias for field number 3

libc_name

Alias for field number 1

os_name

Alias for field number 2

debian._arch_table._parse_table_file(fd: IO[str]) → Iterable[list[str]]