0
# importlib_metadata
1
2
A library providing third-party access to the functionality of `importlib.metadata`, allowing Python applications to read metadata from installed packages. It serves as a backport and enhancement of the standard library's `importlib.metadata` module, offering compatibility across different Python versions and additional features.
3
4
The library enables developers to discover package metadata, entry points, files, and dependencies programmatically, making it essential for tools that need to introspect installed packages. It supports both modern package formats (dist-info) and legacy formats (egg-info), provides efficient path searching and caching mechanisms, and offers a comprehensive API for package discovery and metadata extraction.
5
6
## Package Information
7
8
- **Package Name**: importlib_metadata
9
- **Language**: Python
10
- **Installation**: `pip install importlib_metadata`
11
- **Requires**: Python >=3.9
12
13
## Core Imports
14
15
```python
16
import importlib_metadata
17
```
18
19
Common imports for specific functionality:
20
21
```python
22
from importlib_metadata import (
23
Distribution,
24
PackageNotFoundError,
25
distribution,
26
distributions,
27
entry_points,
28
files,
29
metadata,
30
packages_distributions,
31
requires,
32
version
33
)
34
```
35
36
## Basic Usage
37
38
```python
39
import importlib_metadata
40
41
# Get version of an installed package
42
pkg_version = importlib_metadata.version('requests')
43
print(f"requests version: {pkg_version}")
44
45
# Get distribution object for a package
46
dist = importlib_metadata.distribution('requests')
47
print(f"Package name: {dist.name}")
48
print(f"Version: {dist.version}")
49
50
# Get package metadata
51
meta = importlib_metadata.metadata('requests')
52
print(f"Summary: {meta['Summary']}")
53
print(f"Author: {meta['Author']}")
54
55
# Get entry points from all packages
56
eps = importlib_metadata.entry_points()
57
console_scripts = eps.select(group='console_scripts')
58
for ep in console_scripts:
59
print(f"Script: {ep.name} -> {ep.value}")
60
61
# Get files in a package
62
package_files = importlib_metadata.files('requests')
63
if package_files:
64
for file_path in package_files[:5]: # Show first 5 files
65
print(f"File: {file_path}")
66
67
# Get package dependencies
68
deps = importlib_metadata.requires('requests')
69
if deps:
70
for dep in deps:
71
print(f"Dependency: {dep}")
72
```
73
74
## Architecture
75
76
The importlib_metadata library follows a layered architecture:
77
78
- **Distribution Classes**: Abstract and concrete implementations for accessing package metadata
79
- **Entry Point System**: Comprehensive handling of package entry points with selection and filtering
80
- **Path and File Management**: Efficient traversal and caching of package installation paths
81
- **Metadata Protocols**: Type-safe interfaces for accessing package metadata
82
- **Finder System**: Pluggable discovery mechanism for locating package distributions
83
84
This design allows the library to work across different package installation methods, Python versions, and package formats while maintaining performance through caching and lazy loading.
85
86
## Capabilities
87
88
### Core Functions
89
90
Primary API functions for accessing package information including version lookup, distribution objects, metadata access, entry points, files, and dependencies.
91
92
```python
93
def distribution(distribution_name: str) -> Distribution: ...
94
def distributions(**kwargs) -> Iterable[Distribution]: ...
95
def metadata(distribution_name: str) -> PackageMetadata | None: ...
96
def version(distribution_name: str) -> str: ...
97
def entry_points(**params) -> EntryPoints: ...
98
def files(distribution_name: str) -> list[PackagePath] | None: ...
99
def requires(distribution_name: str) -> list[str] | None: ...
100
def packages_distributions() -> Mapping[str, list[str]]: ...
101
``` { .api }
102
103
[Core Functions](./core-functions.md)
104
105
### Distribution Classes
106
107
Distribution classes provide object-oriented access to package metadata, including abstract base classes and concrete implementations for different package formats.
108
109
```python { .api }
110
class Distribution(metaclass=abc.ABCMeta):
111
@abc.abstractmethod
112
def read_text(self, filename) -> str | None: ...
113
@abc.abstractmethod
114
def locate_file(self, path: str | os.PathLike[str]) -> SimplePath: ...
115
116
@classmethod
117
def from_name(cls, name: str) -> Distribution: ...
118
@classmethod
119
def discover(cls, *, context=None, **kwargs) -> Iterable[Distribution]: ...
120
121
@property
122
def metadata(self) -> PackageMetadata | None: ...
123
@property
124
def name(self) -> str: ...
125
@property
126
def version(self) -> str: ...
127
```
128
129
[Distribution Classes](./distribution-classes.md)
130
131
### Entry Points System
132
133
Comprehensive entry point discovery and management, including entry point objects, collections, and selection mechanisms for package-defined executable scripts and plugins.
134
135
```python { .api }
136
class EntryPoint:
137
name: str
138
value: str
139
group: str
140
dist: Distribution | None
141
142
def load(self) -> Any: ...
143
def matches(self, **params) -> bool: ...
144
145
class EntryPoints(tuple):
146
def select(self, **params) -> EntryPoints: ...
147
def __getitem__(self, name: str) -> EntryPoint: ...
148
149
@property
150
def names(self) -> set[str]: ...
151
@property
152
def groups(self) -> set[str]: ...
153
```
154
155
[Entry Points System](./entry-points.md)
156
157
### Path and File Management
158
159
File path handling and package file enumeration, including path objects, file hashing, and file access methods for package contents.
160
161
```python { .api }
162
class PackagePath(pathlib.PurePosixPath):
163
hash: FileHash | None
164
size: int
165
dist: Distribution
166
167
def read_text(self, encoding: str = 'utf-8') -> str: ...
168
def read_binary(self) -> bytes: ...
169
def locate(self) -> SimplePath: ...
170
171
class FileHash:
172
mode: str
173
value: str
174
```
175
176
[Path and File Management](./path-file-management.md)
177
178
## Types
179
180
Core type definitions used throughout the API:
181
182
```python { .api }
183
class PackageNotFoundError(ModuleNotFoundError):
184
"""Exception raised when package metadata cannot be found."""
185
@property
186
def name(self) -> str: ...
187
188
# Protocol interfaces
189
class PackageMetadata(Protocol):
190
"""
191
Protocol for accessing package metadata as a mapping-like object.
192
193
This protocol defines the interface for metadata objects returned by
194
Distribution.metadata, providing dictionary-like access to package
195
metadata fields as defined by Python packaging standards.
196
"""
197
198
def __len__(self) -> int:
199
"""Return the number of metadata fields."""
200
201
def __contains__(self, item: str) -> bool:
202
"""Check if a metadata field exists."""
203
204
def __getitem__(self, key: str) -> str:
205
"""Get a metadata field value. Raises KeyError if not found."""
206
207
def __iter__(self) -> Iterator[str]:
208
"""Iterate over metadata field names."""
209
210
def get(self, name: str, failobj=None) -> str | None:
211
"""Get a metadata field value, returning failobj if not found."""
212
213
def get_all(self, name: str, failobj=None) -> list[Any] | None:
214
"""Get all values for a metadata field (for multi-valued fields)."""
215
216
@property
217
def json(self) -> dict[str, str | list[str]]:
218
"""Return metadata as a JSON-serializable dictionary."""
219
220
class SimplePath(Protocol):
221
"""
222
A minimal subset of pathlib.Path required by Distribution.
223
224
This protocol defines the interface that path objects must implement
225
to work with the importlib_metadata system. It provides the essential
226
path operations needed for accessing package files and metadata.
227
"""
228
229
def joinpath(self, other: str | os.PathLike[str]) -> SimplePath:
230
"""
231
Join this path with another path component.
232
233
Parameters:
234
- other: Path component to join
235
236
Returns:
237
SimplePath: New path with component joined
238
"""
239
240
def __truediv__(self, other: str | os.PathLike[str]) -> SimplePath:
241
"""
242
Path division operator (/) for joining paths.
243
244
Parameters:
245
- other: Path component to join
246
247
Returns:
248
SimplePath: New path with component joined
249
"""
250
251
@property
252
def parent(self) -> SimplePath:
253
"""
254
Return the parent directory of this path.
255
256
Returns:
257
SimplePath: Parent directory path
258
"""
259
260
def read_text(self, encoding=None) -> str:
261
"""
262
Read the file as text.
263
264
Parameters:
265
- encoding: Text encoding (optional, defaults to locale encoding)
266
267
Returns:
268
str: File contents as text
269
270
Raises:
271
FileNotFoundError: If file doesn't exist
272
UnicodeDecodeError: If file cannot be decoded as text
273
"""
274
275
def read_bytes(self) -> bytes:
276
"""
277
Read the file as binary data.
278
279
Returns:
280
bytes: File contents as bytes
281
282
Raises:
283
FileNotFoundError: If file doesn't exist
284
"""
285
286
def exists(self) -> bool:
287
"""
288
Check if the path exists.
289
290
Returns:
291
bool: True if path exists, False otherwise
292
"""
293
```