Linux Distribution - a Linux OS platform information API Release 1.3.0 Nir Cohen, Andreas Maier Sep 04, 2018 Contents 1 Overview and motivation 3 2 Compatibility 5 3 Data sources 7 4 Access to the information 9 5 Consolidated accessor functions 11 6 Single source accessor functions 17 7 LinuxDistribution class 19 8 Normalization tables 23 9 Os-release file 25 10 Lsb_release command output 27 11 Distro release file 29 Python Module Index 31 i ii Linux Distribution - a Linux OS platform information API, Release 1.3.0 Official distro repository: distro official repo Contents 1 Linux Distribution - a Linux OS platform information API, Release 1.3.0 2 Contents CHAPTER 1 Overview and motivation The distro package (distro stands for Linux Distribution) provides information about the Linux distribution it runs on, such as a reliable machine-readable distro ID, or version information. It is the recommended replacement for Python’s original platform.linux_distribution() function, but it provides much more functionality. An alternative implementation became necessary because Python 3.5 deprecated this function, and Python 3.8 will remove it altogether. Its predecessor function platform.dist() was already deprecated since Python 2.6 and will also be removed in Python 3.8. Still, there are many cases in which access to OS distribution information is needed. See Python issue 1322 for more information. If you want to jump into the API description right away, read about the consolidated accessor functions. 3 Linux Distribution - a Linux OS platform information API, Release 1.3.0 4 Chapter 1. Overview and motivation CHAPTER 2 Compatibility The distro package is supported on Python 2.7, 3.4+ and PyPy, and on any Linux or *BSD distribution that provides one or more of the data sources used by this package. This package is tested on Python 2.7, 3.4+ and PyPy, with test data that mimics the exact behavior of the data sources of a number of Linux distributions. If you want to add test data for more distributions, please create an issue in the distro issue tracker and provide the following information in the issue: • The content of the /etc/os-release file, if any. • The file names and content of the /etc/*release and /etc/*version files, if any. • The output of the command: lsb_release -a, if available. • The file names and content of any other files you are aware of that provide useful information about the distro. There are already some open issues on missing test data. 5 Linux Distribution - a Linux OS platform information API, Release 1.3.0 6 Chapter 2. Compatibility CHAPTER 3 Data sources The distro package implements a robust and inclusive way of retrieving the information about a Linux distribution based on new standards and old methods, namely from these data sources: • The os-release file, if present. • The lsb_release command output, if the lsb_release command is available. • The distro release file, if present. • The ‘uname command output‘_, if present. 7 Linux Distribution - a Linux OS platform information API, Release 1.3.0 8 Chapter 3. Data sources CHAPTER 4 Access to the information This package provides three ways to access the information about a Linux distribution: • Consolidated accessor functions These are module-global functions that take into account all data sources in a priority order, and that return information about the current Linux distribution. These functions should be the normal way to access the information. The precedence of data sources is applied for each information item separately. Therefore, it is possible that not all information items returned by these functions come from the same data source. For example, on a distribution that has an lsb_release command that returns the “Distributor ID” field but not the “Codename” field, and that has a distro release file that specifies a codename inside, the distro ID will come from the lsb_release command (because it has higher precedence), and the codename will come from the distro release file (because it is not provided by the lsb_release command). Examples: distro.id() for retrieving the distro ID, or ld.info() to get the machine-readable part of the information in a more aggregated way, or distro.linux_distribution() with an interface that is compatible to the original platform.linux_distribution() function, supporting a subset of its parameters. • Single source accessor functions These are module-global functions that take into account a single data source, and that return information about the current Linux distribution. They are useful for distributions that provide multiple inconsistent data sources, or for retrieving information items that are not provided by the consolidated accessor functions. Examples: distro.os_release_attr() for retrieving a single information item from the os-release data source, or distro.lsb_release_info() for retrieving all information items from the lsb_release com- mand output data source. • LinuxDistribution class The distro.LinuxDistribution class provides the main code of this package. 9 Linux Distribution - a Linux OS platform information API, Release 1.3.0 This package contains a private module-global distro.LinuxDistribution instance with default initial- ization arguments, that is used by the consolidated and single source accessor functions. A user-defined instance of the distro.LinuxDistribution class allows specifying the path names of the os-release file and distro release file and whether the lsb_release command should be used or not. That is useful for example when the distribution information from a chrooted environment is to be retrieved, or when a distro has multiple distro release files and the default algorithm uses the wrong one. 10 Chapter 4. Access to the information CHAPTER 5 Consolidated accessor functions This section describes the consolidated accessor functions. See access to the information for a discussion of the different kinds of accessor functions. distro.linux_distribution(full_distribution_name=True) Return information about the current OS distribution as a tuple (id_name, version, codename) with items as follows: • id_name: If full_distribution_name is false, the result of distro.id(). Otherwise, the result of distro.name(). • version: The result of distro.version(). • codename: The result of distro.codename(). The interface of this function is compatible with the original platform.linux_distribution() func- tion, supporting a subset of its parameters. The data it returns may not exactly be the same, because it uses more data sources than the original function, and that may lead to different data if the OS distribution is not consistent across multiple data sources it provides (there are indeed such distributions . ). Another reason for differences is the fact that the distro.id() method normalizes the distro ID string to a reliable machine-readable value for a number of popular OS distributions. distro.id() Return the distro ID of the current distribution, as a machine-readable string. For a number of OS distributions, the returned distro ID value is reliable, in the sense that it is documented and that it does not change across releases of the distribution. This package maintains the following reliable distro ID values: 11 Linux Distribution - a Linux OS platform information API, Release 1.3.0 Distro ID Distribution “ubuntu” Ubuntu “debian” Debian “rhel” RedHat Enterprise Linux “centos” CentOS “fedora” Fedora “sles” SUSE Linux Enterprise Server “opensuse” openSUSE “amazon” Amazon Linux “arch” Arch Linux “cloudlinux” CloudLinux OS “exherbo” Exherbo Linux “gentoo” GenToo Linux “ibm_powerkvm” IBM PowerKVM “kvmibm” KVM for IBM z Systems “linuxmint” Linux Mint “mageia” Mageia “mandriva” Mandriva Linux “parallels” Parallels “pidora” Pidora “raspbian” Raspbian “oracle” Oracle Linux (and Oracle Enterprise Linux) “scientific” Scientific Linux “slackware” Slackware “xenserver” XenServer “openbsd” OpenBSD “netbsd” NetBSD “freebsd” FreeBSD If you have a need to get distros for reliable IDs added into this set, or if you find that the distro.id() function returns a different distro ID for one of the listed distros, please create an issue in the distro issue tracker. Lookup hierarchy and transformations: First, the ID is obtained from the following sources, in the specified order. The first available and non-empty value is used: • the value of the “ID” attribute of the os-release file, • the value of the “Distributor ID” attribute returned by the lsb_release command, • the first part of the file name of the distro release file, The so determined ID value then passes the following transformations, before it is returned by this method: • it is translated to lower case, • blanks (which should not be there anyway) are translated to underscores, • a normalization of the ID is performed, based upon normalization tables. The purpose of this normalization is to ensure that the ID is as reliable as possible, even across incompatible changes in the OS distributions. A common reason for an incompatible change is the addition of an os-release file, or the addition of the lsb_release command, with ID values that differ from what was previously determined from the distro release file name. 12 Chapter 5. Consolidated accessor functions Linux Distribution - a Linux OS platform information API, Release 1.3.0 distro.name(pretty=False) Return the name of the current OS distribution, as a human-readable string. If pretty is false, the name is returned without version or codename. (e.g. “CentOS Linux”) If pretty is true, the version and codename are appended.