0
# Core Functions
1
2
Primary API functions for accessing package information including version lookup, distribution objects, metadata access, entry points, files, and dependencies. These functions provide the main interface for package introspection.
3
4
## Capabilities
5
6
### Package Information Lookup
7
8
Get basic information about installed packages including distribution objects, metadata, and version strings.
9
10
```python { .api }
11
def distribution(distribution_name: str) -> Distribution:
12
"""
13
Get the Distribution instance for the named package.
14
15
Parameters:
16
- distribution_name: The name of the distribution package as a string
17
18
Returns:
19
Distribution: A Distribution instance (or subclass thereof)
20
21
Raises:
22
PackageNotFoundError: When the named package's distribution metadata cannot be found
23
"""
24
25
def distributions(**kwargs) -> Iterable[Distribution]:
26
"""
27
Get all Distribution instances in the current environment.
28
29
Parameters:
30
- **kwargs: Keyword arguments for constructing a DistributionFinder.Context
31
32
Returns:
33
Iterable[Distribution]: An iterable of Distribution instances
34
"""
35
36
def metadata(distribution_name: str) -> PackageMetadata | None:
37
"""
38
Get the metadata for the named package.
39
40
Parameters:
41
- distribution_name: The name of the distribution package to query
42
43
Returns:
44
PackageMetadata: A PackageMetadata containing the parsed metadata, or None if not found
45
"""
46
47
def version(distribution_name: str) -> str:
48
"""
49
Get the version string for the named package.
50
51
Parameters:
52
- distribution_name: The name of the distribution package to query
53
54
Returns:
55
str: The version string for the package as defined in the package's "Version" metadata key
56
57
Raises:
58
PackageNotFoundError: When the named package cannot be found
59
"""
60
```
61
62
#### Usage Examples
63
64
```python
65
import importlib_metadata
66
67
# Get a distribution object
68
dist = importlib_metadata.distribution('requests')
69
print(f"Package: {dist.name}, Version: {dist.version}")
70
71
# Get all distributions
72
all_dists = list(importlib_metadata.distributions())
73
print(f"Found {len(all_dists)} installed packages")
74
75
# Get metadata directly
76
meta = importlib_metadata.metadata('requests')
77
print(f"Author: {meta['Author']}")
78
print(f"Summary: {meta['Summary']}")
79
80
# Get version string
81
version = importlib_metadata.version('requests')
82
print(f"requests version: {version}")
83
```
84
85
### Entry Points Access
86
87
Access entry points defined by installed packages, including console scripts, plugins, and other package-defined entry points.
88
89
```python { .api }
90
def entry_points(**params) -> EntryPoints:
91
"""
92
Return EntryPoint objects for all installed packages.
93
94
Pass selection parameters (group or name) to filter the result to entry points
95
matching those properties (see EntryPoints.select()).
96
97
Parameters:
98
- **params: Selection parameters for filtering (group, name, etc.)
99
100
Returns:
101
EntryPoints: EntryPoints collection for all installed packages
102
"""
103
```
104
105
#### Usage Examples
106
107
```python
108
import importlib_metadata
109
110
# Get all entry points
111
all_eps = importlib_metadata.entry_points()
112
print(f"Found {len(all_eps)} entry points")
113
114
# Get console scripts only
115
console_scripts = importlib_metadata.entry_points(group='console_scripts')
116
for ep in console_scripts:
117
print(f"Script: {ep.name} -> {ep.value}")
118
119
# Get entry points by name
120
pip_eps = importlib_metadata.entry_points(name='pip')
121
for ep in pip_eps:
122
print(f"pip entry point in group '{ep.group}': {ep.value}")
123
```
124
125
### File and Dependency Information
126
127
Access package files and dependency information for installed packages.
128
129
```python { .api }
130
def files(distribution_name: str) -> list[PackagePath] | None:
131
"""
132
Return a list of files for the named package.
133
134
Parameters:
135
- distribution_name: The name of the distribution package to query
136
137
Returns:
138
list[PackagePath] | None: List of files composing the distribution, or None if
139
the metadata file that enumerates files is missing
140
"""
141
142
def requires(distribution_name: str) -> list[str] | None:
143
"""
144
Return a list of requirements for the named package.
145
146
Parameters:
147
- distribution_name: The name of the distribution package to query
148
149
Returns:
150
list[str] | None: An iterable of requirements, suitable for
151
packaging.requirement.Requirement, or None if no requirements
152
"""
153
154
def packages_distributions() -> Mapping[str, list[str]]:
155
"""
156
Return a mapping of top-level packages to their distributions.
157
158
Returns:
159
Mapping[str, list[str]]: Dictionary mapping package names to list of distribution names
160
"""
161
```
162
163
#### Usage Examples
164
165
```python
166
import importlib_metadata
167
168
# Get package files
169
files = importlib_metadata.files('requests')
170
if files:
171
print(f"requests has {len(files)} files")
172
for file_path in files[:5]: # Show first 5
173
print(f" {file_path}")
174
175
# Get package dependencies
176
deps = importlib_metadata.requires('requests')
177
if deps:
178
print("requests dependencies:")
179
for dep in deps:
180
print(f" {dep}")
181
182
# Get package to distribution mapping
183
pkg_to_dist = importlib_metadata.packages_distributions()
184
print(f"requests package provided by: {pkg_to_dist.get('requests', 'unknown')}")
185
```
186
187
## Error Handling
188
189
All core functions may raise `PackageNotFoundError` when the requested package cannot be found:
190
191
```python
192
import importlib_metadata
193
194
try:
195
version = importlib_metadata.version('nonexistent-package')
196
except importlib_metadata.PackageNotFoundError as e:
197
print(f"Package not found: {e.name}")
198
```