0
# Core EXIF Processing
1

2
Main functionality for extracting EXIF metadata from image files. Provides comprehensive format detection, tag parsing, and thumbnail extraction with support for TIFF, JPEG, WebP, and HEIC formats.
3

4
## Capabilities
5

6
### Main Processing Function
7

8
The primary entry point for EXIF metadata extraction, handling file format detection and coordinating the parsing process.
9

10
```python { .api }
11
def process_file(fh, stop_tag='UNDEF', details=True, strict=False, debug=False, truncate_tags=True, auto_seek=True):
12
    """
13
    Process an image file and extract EXIF metadata.
14
    
15
    This function handles all arbitrary aspects of the EXIF standard and 
16
    automatically detects file format (TIFF, JPEG, WebP, HEIC).
17
    
18
    Parameters:
19
    - fh: file handle, open file object in binary mode
20
    - stop_tag: str, tag name to stop processing at (default: 'UNDEF')
21
    - details: bool, process MakerNotes and extract thumbnails (default: True) 
22
    - strict: bool, return error on invalid tags instead of ignoring (default: False)
23
    - debug: bool, enable debug output and XMP parsing (default: False)
24
    - truncate_tags: bool, truncate long tag values for display (default: True)
25
    - auto_seek: bool, automatically seek to beginning of file (default: True)
26
    
27
    Returns:
28
    dict: Dictionary mapping tag names to IfdTag objects
29
        Keys are formatted as 'IFD_NAME Tag_Name' (e.g., 'EXIF DateTimeOriginal')
30
        Returns empty dict if no EXIF data found or on format errors
31
    """
32
```
33

34
### Format Detection Functions
35

36
Internal functions for detecting and processing different image formats.
37

38
```python { .api }
39
def increment_base(data, base):
40
    """
41
    Calculate base increment for JPEG segment parsing.
42
    
43
    Parameters:
44
    - data: bytes, image data
45
    - base: int, current base position
46
    
47
    Returns:
48
    int: Increment value for next segment
49
    """
50
```
51

52
### Exception Classes
53

54
Exceptions raised during EXIF processing.
55

56
```python { .api }
57
class InvalidExif(Exception):
58
    """
59
    Raised when EXIF data is corrupted or invalid.
60
    
61
    This exception indicates that the EXIF data structure
62
    does not conform to the EXIF specification.
63
    """
64

65
class ExifNotFound(Exception):
66
    """
67
    Raised when no EXIF data is found in the image file.
68
    
69
    This exception indicates that the image file does not
70
    contain EXIF metadata or the metadata is not accessible.
71
    """
72
```
73

74
### Constants
75

76
Module-level constants used in processing.
77

78
```python { .api }
79
__version__: str = '2.3.2'
80
"""Package version string."""
81

82
DEFAULT_STOP_TAG: str = 'UNDEF'
83
"""Default tag name to stop processing at."""
84

85
FIELD_TYPES: tuple = (
86
    (0, 'X', 'Proprietary'),
87
    (1, 'B', 'Byte'),
88
    (1, 'A', 'ASCII'),
89
    (2, 'S', 'Short'),
90
    (4, 'L', 'Long'),
91
    (8, 'R', 'Ratio'),
92
    (1, 'SB', 'Signed Byte'),
93
    (1, 'U', 'Undefined'),
94
    (2, 'SS', 'Signed Short'),
95
    (4, 'SL', 'Signed Long'),
96
    (8, 'SR', 'Signed Ratio'),
97
    (4, 'F32', 'Single-Precision Floating Point (32-bit)'),
98
    (8, 'F64', 'Double-Precision Floating Point (64-bit)'),
99
    (4, 'L', 'IFD'),
100
)
101
"""EXIF field type definitions as (length, abbreviation, full name) tuples."""
102

103
IGNORE_TAGS: tuple = (0x9286, 0x927C, 0x02BC)
104
"""Tags to ignore during quick processing mode (UserComment, MakerNote, XPM)."""
105

106
EXIF_TAGS: dict
107
"""Standard EXIF tag definitions mapping tag IDs to names and processors."""
108

109
GPS_TAGS: dict
110
"""GPS-specific EXIF tags mapping tag IDs to names and processors."""
111

112
INTEROP_TAGS: dict
113
"""Interoperability EXIF tags mapping tag IDs to names and processors."""
114
```
115

116
## Usage Examples
117

118
### Basic EXIF Extraction
119

120
```python
121
import exifread
122

123
# Open and process image file
124
with open('photo.jpg', 'rb') as f:
125
    tags = exifread.process_file(f)
126
    
127
# Check if EXIF data was found
128
if tags:
129
    # Display basic information
130
    for tag_name, tag_value in tags.items():
131
        print(f"{tag_name}: {tag_value}")
132
else:
133
    print("No EXIF data found")
134
```
135

136
### Quick Processing Mode
137

138
```python
139
import exifread
140

141
# Process without MakerNotes for faster performance
142
with open('photo.jpg', 'rb') as f:
143
    tags = exifread.process_file(f, details=False)
144
    
145
# Access specific tags
146
if 'Image DateTime' in tags:
147
    print(f"Date: {tags['Image DateTime']}")
148
if 'Image Make' in tags:
149
    print(f"Camera: {tags['Image Make']}")
150
if 'Image Model' in tags:
151
    print(f"Model: {tags['Image Model']}")
152
```
153

154
### Strict Mode Processing
155

156
```python
157
import exifread
158

159
try:
160
    with open('photo.jpg', 'rb') as f:
161
        tags = exifread.process_file(f, strict=True)
162
        print(f"Successfully extracted {len(tags)} tags")
163
except exifread.InvalidExif as e:
164
    print(f"Invalid EXIF data: {e}")
165
except exifread.ExifNotFound as e:
166
    print(f"No EXIF data found: {e}")
167
```
168

169
### Stop at Specific Tag
170

171
```python
172
import exifread
173

174
# Stop processing after finding the date tag
175
with open('photo.jpg', 'rb') as f:
176
    tags = exifread.process_file(f, stop_tag='DateTimeOriginal')
177
    
178
if 'EXIF DateTimeOriginal' in tags:
179
    print(f"Photo taken: {tags['EXIF DateTimeOriginal']}")
180
```
181

182
### Debug Mode
183

184
```python
185
import exifread
186

187
# Enable debug output and XMP parsing
188
with open('photo.jpg', 'rb') as f:
189
    tags = exifread.process_file(f, debug=True)
190
    
191
# XMP data will be included if present
192
if 'Image ApplicationNotes' in tags:
193
    print("XMP metadata found")
194
```