0
# Distro
1

2
A reliable and comprehensive API for retrieving information about the operating system distribution on Linux and BSD-based systems. It serves as the recommended replacement for Python's deprecated `platform.linux_distribution` function, offering machine-readable distribution IDs, version information, and codenames through multiple detection methods.
3

4
## Package Information
5

6
- **Package Name**: distro
7
- **Language**: Python
8
- **Installation**: `pip install distro`
9
- **Version**: 1.9.0
10
- **License**: Apache License 2.0
11

12
## Core Imports
13

14
```python
15
import distro
16
```
17

18
For accessing specific functions directly:
19

20
```python
21
from distro import id, name, version, info
22
```
23

24
For using the main class:
25

26
```python
27
from distro import LinuxDistribution
28
```
29

30
## Basic Usage
31

32
```python
33
import distro
34

35
# Get basic distribution information
36
print(f"Distribution ID: {distro.id()}")
37
print(f"Distribution Name: {distro.name()}")  
38
print(f"Version: {distro.version()}")
39
print(f"Codename: {distro.codename()}")
40

41
# Get comprehensive information
42
info = distro.info()
43
print(f"Complete info: {info}")
44

45
# Pretty formatted output
46
print(f"Pretty name: {distro.name(pretty=True)}")
47
print(f"Pretty version: {distro.version(pretty=True)}")
48

49
# Version components
50
major, minor, build = distro.version_parts()
51
print(f"Version parts: {major}.{minor}.{build}")
52
```
53

54
## Architecture
55

56
Distro uses a hierarchical data source approach with fallback mechanisms:
57

58
- **Primary**: `/etc/os-release` file (modern Linux standard)
59
- **Secondary**: `lsb_release` command output (LSB-compliant systems) 
60
- **Tertiary**: Distribution-specific release files (`/etc/*-release`)
61
- **Fallback**: `uname` command (BSD systems)
62

63
The `LinuxDistribution` class encapsulates all detection logic with caching for performance. Module-level convenience functions use a global instance for simple access patterns.
64

65
## Capabilities
66

67
### Core Distribution Information
68

69
Essential functions for identifying and describing the operating system distribution, including machine-readable IDs, human-readable names, version strings, and codenames.
70

71
```python { .api }
72
def id() -> str: ...
73
def name(pretty: bool = False) -> str: ...
74
def version(pretty: bool = False, best: bool = False) -> str: ...
75
def codename() -> str: ...
76
def like() -> str: ...
77
def info(pretty: bool = False, best: bool = False) -> InfoDict: ...
78
```
79

80
[Core Distribution Information](./core-info.md)
81

82
### Version Components
83

84
Functions for parsing and accessing individual components of version numbers, including major version, minor version, and build numbers.
85

86
```python { .api }
87
def version_parts(best: bool = False) -> Tuple[str, str, str]: ...
88
def major_version(best: bool = False) -> str: ...
89
def minor_version(best: bool = False) -> str: ...
90
def build_number(best: bool = False) -> str: ...
91
```
92

93
[Version Components](./version-components.md)
94

95
### Data Source Access
96

97
Low-level access to the underlying data sources that distro uses for distribution detection, including os-release files, lsb_release command, distro release files, and uname command.
98

99
```python { .api }
100
def os_release_info() -> Dict[str, str]: ...
101
def lsb_release_info() -> Dict[str, str]: ...
102
def distro_release_info() -> Dict[str, str]: ...
103
def uname_info() -> Dict[str, str]: ...
104
def os_release_attr(attribute: str) -> str: ...
105
def lsb_release_attr(attribute: str) -> str: ...
106
def distro_release_attr(attribute: str) -> str: ...
107
def uname_attr(attribute: str) -> str: ...
108
```
109

110
[Data Source Access](./data-sources.md)
111

112
### LinuxDistribution Class
113

114
The main class that encapsulates all distribution detection logic with configurable data sources and custom file paths for testing or alternative environments.
115

116
```python { .api }
117
class LinuxDistribution:
118
    def __init__(
119
        self,
120
        include_lsb: Optional[bool] = None,
121
        os_release_file: str = "",
122
        distro_release_file: str = "",
123
        include_uname: Optional[bool] = None,
124
        root_dir: Optional[str] = None,
125
        include_oslevel: Optional[bool] = None,
126
    ) -> None: ...
127
```
128

129
[LinuxDistribution Class](./linux-distribution.md)
130

131
## Types
132

133
```python { .api }
134
from typing import TypedDict, Tuple, Dict, Optional
135

136
class VersionDict(TypedDict):
137
    major: str
138
    minor: str
139
    build_number: str
140

141
class InfoDict(TypedDict):
142
    id: str
143
    version: str
144
    version_parts: VersionDict
145
    like: str
146
    codename: str
147

148
# Package version
149
__version__: str
150

151
# Normalization constants
152
NORMALIZED_OS_ID: Dict[str, str]
153
NORMALIZED_LSB_ID: Dict[str, str] 
154
NORMALIZED_DISTRO_ID: Dict[str, str]
155
```
156

157
## Normalization Constants
158

159
The distro package uses normalization tables to map various distribution identifiers to standardized names for reliable cross-distribution compatibility.
160

161
### OS Release ID Normalization
162

163
```python { .api }
164
NORMALIZED_OS_ID = {
165
    "ol": "oracle",  # Oracle Linux
166
    "opensuse-leap": "opensuse",  # Newer versions of OpenSUSE report as opensuse-leap
167
}
168
```
169

170
Maps ID values from `/etc/os-release` files to normalized distribution identifiers.
171

172
### LSB Release ID Normalization  
173

174
```python { .api }
175
NORMALIZED_LSB_ID = {
176
    "enterpriseenterpriseas": "oracle",  # Oracle Enterprise Linux 4
177
    "enterpriseenterpriseserver": "oracle",  # Oracle Linux 5  
178
    "redhatenterpriseworkstation": "rhel",  # RHEL 6, 7 Workstation
179
    "redhatenterpriseserver": "rhel",  # RHEL 6, 7 Server
180
    "redhatenterprisecomputenode": "rhel",  # RHEL 6 ComputeNode
181
}
182
```
183

184
Maps Distributor ID values from `lsb_release` command output to normalized identifiers.
185

186
### Distro Release File ID Normalization
187

188
```python { .api }
189
NORMALIZED_DISTRO_ID = {
190
    "redhat": "rhel",  # RHEL 6.x, 7.x
191
}
192
```
193

194
Maps distribution identifiers derived from release file names (e.g., `/etc/redhat-release`) to normalized values.
195

196
Usage example:
197
```python
198
import distro
199

200
# These normalization tables are used internally by distro.id()
201
# to ensure consistent identifiers across different data sources
202
dist_id = distro.id()  # Returns normalized ID like "rhel" instead of "redhat"
203
```
204

205
## CLI Interface
206

207
Distro provides a command-line interface for system administration and scripting:
208

209
```bash
210
# Basic information
211
distro
212

213
# JSON output
214
distro -j
215

216
# Help
217
distro --help
218
```
219

220
```python { .api }
221
def main() -> None:
222
    """
223
    Command-line interface entry point for the distro tool.
224
    
225
    Provides command-line access to distribution information with options for:
226
    - Basic text output (default)
227
    - JSON formatted output (-j/--json)
228
    - Help information (--help)
229
    
230
    This function is called when running 'distro' command or 'python -m distro'.
231
    """
232
```
233

234
## Legacy Compatibility
235

236
```python { .api }
237
def linux_distribution(full_distribution_name: bool = True) -> Tuple[str, str, str]:
238
    """
239
    DEPRECATED: Compatibility function for platform.linux_distribution()
240
    
241
    Returns:
242
        Tuple of (id_name, version, codename)
243
    """
244
```