0
# Version and Library Information
1

2
Access to pypdfium2 and PDFium version information, build details, feature flags, and compatibility data. The version module provides comprehensive information about both the Python bindings and underlying PDFium library.
3

4
## Capabilities
5

6
### Version Objects
7

8
Access version information through dedicated version objects with comprehensive metadata.
9

10
```python { .api }
11
# Primary version objects
12
PYPDFIUM_INFO: _version_pypdfium2  # pypdfium2 helpers version
13
PDFIUM_INFO: _version_pdfium       # PDFium library version
14

15
# Deprecated constants (removed in v5)
16
V_PYPDFIUM2: str      # pypdfium2 version string
17
V_LIBPDFIUM: str      # PDFium build number string
18
V_LIBPDFIUM_FULL: str # Full PDFium version string
19
V_BUILDNAME: str      # PDFium binary origin
20
V_PDFIUM_IS_V8: bool  # V8/XFA support flag
21
```
22

23
Basic version access:
24

25
```python
26
import pypdfium2 as pdfium
27

28
# Access version objects
29
pypdfium_version = pdfium.PYPDFIUM_INFO
30
pdfium_version = pdfium.PDFIUM_INFO
31

32
print(f"pypdfium2 version: {pypdfium_version.version}")
33
print(f"PDFium version: {pdfium_version.version}")
34

35
# Deprecated API (still available but will be removed)
36
print(f"pypdfium2 (deprecated): {pdfium.V_PYPDFIUM2}")
37
print(f"PDFium build (deprecated): {pdfium.V_LIBPDFIUM}")
38
```
39

40
### pypdfium2 Version Information
41

42
Comprehensive version information for the pypdfium2 Python bindings.
43

44
```python { .api }
45
class _version_pypdfium2:
46
    @property
47
    def version(self) -> str:
48
        """Complete version string (tag + desc)."""
49
    
50
    @property
51
    def tag(self) -> str:
52
        """Version numbers as string, including possible beta."""
53
    
54
    @property
55
    def desc(self) -> str:
56
        """Non-numeric descriptors (commits, dirty state, etc.)."""
57
    
58
    @property
59
    def api_tag(self) -> tuple[int]:
60
        """Version numbers as tuple, excluding beta."""
61
    
62
    @property
63
    def major(self) -> int:
64
        """Major version number."""
65
    
66
    @property
67
    def minor(self) -> int:
68
        """Minor version number."""
69
    
70
    @property
71
    def patch(self) -> int:
72
        """Patch version number."""
73
    
74
    @property
75
    def beta(self) -> int | None:
76
        """Beta version number, or None if not a beta."""
77
    
78
    @property
79
    def n_commits(self) -> int:
80
        """Number of commits after tag at install time."""
81
    
82
    @property
83
    def hash(self) -> str | None:
84
        """Commit hash if n_commits > 0, None otherwise."""
85
    
86
    @property
87
    def dirty(self) -> bool:
88
        """True if uncommitted changes at install time."""
89
    
90
    @property
91
    def data_source(self) -> str:
92
        """Source of version info: 'git', 'given', or 'record'."""
93
    
94
    @property
95
    def is_editable(self) -> bool | None:
96
        """True for editable install, False otherwise, None if unknown."""
97
```
98

99
pypdfium2 version analysis:
100

101
```python
102
info = pdfium.PYPDFIUM_INFO
103

104
print("pypdfium2 Version Information:")
105
print(f"  Full version: {info.version}")
106
print(f"  Tag: {info.tag}")
107
print(f"  Description: {info.desc}")
108
print(f"  API tag: {info.api_tag}")
109
print(f"  Major.Minor.Patch: {info.major}.{info.minor}.{info.patch}")
110

111
if info.beta is not None:
112
    print(f"  Beta version: {info.beta}")
113

114
print(f"  Commits after tag: {info.n_commits}")
115
if info.hash:
116
    print(f"  Commit hash: {info.hash}")
117

118
print(f"  Dirty build: {info.dirty}")
119
print(f"  Data source: {info.data_source}")
120
print(f"  Editable install: {info.is_editable}")
121

122
# Version comparison
123
required_version = (4, 30, 0)
124
if info.api_tag >= required_version:
125
    print(f"Version {info.api_tag} meets requirement {required_version}")
126
else:
127
    print(f"Version {info.api_tag} does not meet requirement {required_version}")
128
```
129

130
### PDFium Version Information
131

132
Detailed information about the underlying PDFium library including build details and feature flags.
133

134
```python { .api }
135
class _version_pdfium:
136
    @property
137
    def version(self) -> str:
138
        """Complete version string (tag + desc)."""
139
    
140
    @property
141
    def tag(self) -> str:
142
        """Version numbers as string."""
143
    
144
    @property
145
    def desc(self) -> str:
146
        """Descriptors (origin, flags) as string."""
147
    
148
    @property
149
    def api_tag(self) -> tuple[int]:
150
        """Version numbers as tuple."""
151
    
152
    @property
153
    def major(self) -> int:
154
        """Chromium major version."""
155
    
156
    @property
157
    def minor(self) -> int:
158
        """Chromium minor version."""
159
    
160
    @property
161
    def build(self) -> int:
162
        """Chromium/PDFium build number (unique identifier)."""
163
    
164
    @property
165
    def patch(self) -> int:
166
        """Chromium patch version."""
167
    
168
    @property
169
    def n_commits(self) -> int:
170
        """Commits after tag at build time."""
171
    
172
    @property
173
    def hash(self) -> str | None:
174
        """Commit hash if n_commits > 0."""
175
    
176
    @property
177
    def origin(self) -> str:
178
        """Binary origin: 'pdfium-binaries', 'sourcebuild', or 'system'."""
179
    
180
    @property
181
    def flags(self) -> tuple[str]:
182
        """Feature flags tuple (e.g., ('V8', 'XFA') for V8 build)."""
183
```
184

185
PDFium version analysis:
186

187
```python
188
info = pdfium.PDFIUM_INFO
189

190
print("PDFium Version Information:")
191
print(f"  Full version: {info.version}")
192
print(f"  Tag: {info.tag}")
193
print(f"  Description: {info.desc}")
194
print(f"  API tag: {info.api_tag}")
195
print(f"  Chromium version: {info.major}.{info.minor}.{info.build}.{info.patch}")
196
print(f"  Build number: {info.build}")
197

198
print(f"  Commits after tag: {info.n_commits}")
199
if info.hash:
200
    print(f"  Commit hash: {info.hash}")
201

202
print(f"  Binary origin: {info.origin}")
203
print(f"  Feature flags: {info.flags}")
204

205
# Check for specific features
206
has_v8 = "V8" in info.flags
207
has_xfa = "XFA" in info.flags
208
print(f"  V8 JavaScript: {has_v8}")
209
print(f"  XFA Forms: {has_xfa}")
210

211
# Origin-specific information
212
if info.origin == "pdfium-binaries":
213
    print("  Using pre-built pdfium-binaries")
214
elif info.origin == "sourcebuild":
215
    print("  Using custom-built PDFium")
216
elif info.origin == "system":
217
    print("  Using system-installed PDFium")
218
```
219

220
### Version Compatibility
221

222
Check version compatibility and feature availability.
223

224
```python
225
def check_compatibility():
226
    """Check version compatibility and available features."""
227
    
228
    pypdfium_info = pdfium.PYPDFIUM_INFO
229
    pdfium_info = pdfium.PDFIUM_INFO
230
    
231
    print("Compatibility Check:")
232
    
233
    # Check pypdfium2 version requirements
234
    min_pypdfium_version = (4, 0, 0)
235
    if pypdfium_info.api_tag >= min_pypdfium_version:
236
        print(f"✓ pypdfium2 {pypdfium_info.api_tag} meets minimum requirement")
237
    else:
238
        print(f"✗ pypdfium2 {pypdfium_info.api_tag} below minimum {min_pypdfium_version}")
239
    
240
    # Check PDFium build requirements  
241
    min_pdfium_build = 6000  # Example minimum build
242
    if pdfium_info.build >= min_pdfium_build:
243
        print(f"✓ PDFium build {pdfium_info.build} meets minimum requirement")
244
    else:
245
        print(f"✗ PDFium build {pdfium_info.build} below minimum {min_pdfium_build}")
246
    
247
    # Feature availability
248
    features = {
249
        'V8 JavaScript': "V8" in pdfium_info.flags,
250
        'XFA Forms': "XFA" in pdfium_info.flags,
251
        'Text extraction': True,  # Always available
252
        'Image rendering': True,  # Always available
253
        'Page manipulation': True,  # Always available
254
    }
255
    
256
    print("\nFeature Availability:")
257
    for feature, available in features.items():
258
        status = "✓" if available else "✗"
259
        print(f"  {status} {feature}")
260
    
261
    # Installation type
262
    print(f"\nInstallation Info:")
263
    print(f"  pypdfium2 data source: {pypdfium_info.data_source}")
264
    print(f"  Editable install: {pypdfium_info.is_editable}")
265
    print(f"  PDFium origin: {pdfium_info.origin}")
266
    
267
    # Development info
268
    if pypdfium_info.dirty or pypdfium_info.n_commits > 0:
269
        print("\nDevelopment Build Detected:")
270
        if pypdfium_info.dirty:
271
            print("  ⚠ Uncommitted changes present")
272
        if pypdfium_info.n_commits > 0:
273
            print(f"  ⚠ {pypdfium_info.n_commits} commits ahead of release")
274
            if pypdfium_info.hash:
275
                print(f"  Commit: {pypdfium_info.hash}")
276

277
# Usage
278
check_compatibility()
279
```
280

281
### Version Comparison
282

283
Compare versions for compatibility and feature detection.
284

285
```python
286
def compare_versions(required_pypdfium=None, required_pdfium_build=None):
287
    """Compare current versions against requirements."""
288
    
289
    results = {
290
        'pypdfium2_compatible': True,
291
        'pdfium_compatible': True,
292
        'issues': []
293
    }
294
    
295
    if required_pypdfium:
296
        current = pdfium.PYPDFIUM_INFO.api_tag
297
        if current < required_pypdfium:
298
            results['pypdfium2_compatible'] = False
299
            results['issues'].append(
300
                f"pypdfium2 {current} < required {required_pypdfium}"
301
            )
302
    
303
    if required_pdfium_build:
304
        current = pdfium.PDFIUM_INFO.build
305
        if current < required_pdfium_build:
306
            results['pdfium_compatible'] = False
307
            results['issues'].append(
308
                f"PDFium build {current} < required {required_pdfium_build}"
309
            )
310
    
311
    return results
312

313
# Usage examples
314
result = compare_versions(
315
    required_pypdfium=(4, 25, 0),
316
    required_pdfium_build=6000
317
)
318

319
if result['pypdfium2_compatible'] and result['pdfium_compatible']:
320
    print("✓ All version requirements met")
321
else:
322
    print("✗ Version compatibility issues:")
323
    for issue in result['issues']:
324
        print(f"  - {issue}")
325
```
326

327
### Build Information Analysis
328

329
Analyze build characteristics and installation details.
330

331
```python
332
def analyze_build_info():
333
    """Analyze pypdfium2 and PDFium build information."""
334
    
335
    pypdfium_info = pdfium.PYPDFIUM_INFO
336
    pdfium_info = pdfium.PDFIUM_INFO
337
    
338
    analysis = {
339
        'pypdfium2': {
340
            'is_release': pypdfium_info.n_commits == 0 and not pypdfium_info.dirty,
341
            'is_beta': pypdfium_info.beta is not None,
342
            'is_development': pypdfium_info.n_commits > 0 or pypdfium_info.dirty,
343
            'install_type': 'editable' if pypdfium_info.is_editable else 'standard',
344
            'version_source': pypdfium_info.data_source
345
        },
346
        'pdfium': {
347
            'is_prebuilt': pdfium_info.origin == 'pdfium-binaries',
348
            'is_custom': pdfium_info.origin == 'sourcebuild',
349
            'is_system': pdfium_info.origin == 'system',
350
            'has_javascript': 'V8' in pdfium_info.flags,
351
            'has_xfa': 'XFA' in pdfium_info.flags,
352
            'feature_count': len(pdfium_info.flags)
353
        }
354
    }
355
    
356
    # Print analysis
357
    print("Build Analysis:")
358
    print(f"\npypdfium2:")
359
    for key, value in analysis['pypdfium2'].items():
360
        print(f"  {key}: {value}")
361
    
362
    print(f"\nPDFium:")
363
    for key, value in analysis['pdfium'].items():
364
        print(f"  {key}: {value}")
365
    
366
    # Recommendations
367
    print(f"\nRecommendations:")
368
    if analysis['pypdfium2']['is_development']:
369
        print("  ⚠ Using development build - consider stable release for production")
370
    
371
    if analysis['pdfium']['is_system']:
372
        print("  ⚠ Using system PDFium - version may vary across systems")
373
    
374
    if not analysis['pdfium']['has_javascript']:
375
        print("  ℹ JavaScript/V8 not available - some advanced PDF features disabled")
376
    
377
    return analysis
378

379
# Usage
380
build_analysis = analyze_build_info()
381
```
382

383
### Environment Information
384

385
Get comprehensive environment and dependency information.
386

387
```python
388
def get_environment_info():
389
    """Get comprehensive environment information."""
390
    import sys
391
    import platform
392
    
393
    env_info = {
394
        'python': {
395
            'version': sys.version,
396
            'platform': platform.platform(),
397
            'architecture': platform.architecture(),
398
        },
399
        'pypdfium2': {            
400
            'version': pdfium.PYPDFIUM_INFO.version,
401
            'api_tag': pdfium.PYPDFIUM_INFO.api_tag,
402
            'install_type': pdfium.PYPDFIUM_INFO.is_editable,
403
            'data_source': pdfium.PYPDFIUM_INFO.data_source,
404
        },
405
        'pdfium': {
406
            'version': pdfium.PDFIUM_INFO.version,
407
            'build': pdfium.PDFIUM_INFO.build,
408
            'origin': pdfium.PDFIUM_INFO.origin,
409
            'flags': pdfium.PDFIUM_INFO.flags,
410
        }
411
    }
412
    
413
    return env_info
414

415
def print_environment_report():
416
    """Print comprehensive environment report."""
417
    env = get_environment_info()
418
    
419
    print("Environment Report")
420
    print("=" * 50)
421
    
422
    print(f"\nPython Environment:")
423
    print(f"  Version: {env['python']['version'].split()[0]}")
424
    print(f"  Platform: {env['python']['platform']}")
425
    print(f"  Architecture: {env['python']['architecture'][0]}")
426
    
427
    print(f"\npypdfium2:")
428
    print(f"  Version: {env['pypdfium2']['version']}")
429
    print(f"  API Tag: {env['pypdfium2']['api_tag']}")
430
    print(f"  Install Type: {'Editable' if env['pypdfium2']['install_type'] else 'Standard'}")
431
    print(f"  Data Source: {env['pypdfium2']['data_source']}")
432
    
433
    print(f"\nPDFium Library:")
434
    print(f"  Version: {env['pdfium']['version']}")
435
    print(f"  Build: {env['pdfium']['build']}")
436
    print(f"  Origin: {env['pdfium']['origin']}")
437
    print(f"  Features: {', '.join(env['pdfium']['flags']) if env['pdfium']['flags'] else 'None'}")
438

439
# Usage
440
print_environment_report()
441
```
442

443
## Data Source Types
444

445
Understanding pypdfium2 version data sources:
446

447
- **`git`**: Parsed from git repository (highest accuracy, development installs)
448
- **`given`**: Pre-supplied version file (sdist packages, custom builds)  
449
- **`record`**: Parsed from autorelease record (some information may be incomplete)
450

451
## PDFium Origins
452

453
Understanding PDFium binary origins:
454

455
- **`pdfium-binaries`**: Pre-built binaries from bblanchon/pdfium-binaries project
456
- **`sourcebuild`**: Custom-built PDFium using pypdfium2's build scripts
457
- **`system`**: System-installed PDFium library loaded dynamically
458

459
## Feature Flags
460

461
Common PDFium feature flags:
462

463
- **`V8`**: V8 JavaScript engine support
464
- **`XFA`**: XFA (XML Forms Architecture) support
465
- Additional flags may be present depending on build configuration