0
# Helper Interface
1

2
User-friendly wrapper around the core ExifTool class that adds convenience methods for common metadata operations, automatic error checking, and simplified file handling. The ExifToolHelper class is recommended for most users as it provides a cleaner API while maintaining access to all core functionality.
3

4
## Capabilities
5

6
### Initialization and Configuration
7

8
Enhanced initialization with helper-specific features and automatic process management.
9

10
```python { .api }
11
class ExifToolHelper(ExifTool):
12
    def __init__(self, auto_start=True, check_execute=True, check_tag_names=True, **kwargs):
13
        """
14
        Initialize ExifToolHelper with enhanced features.
15
        
16
        Parameters:
17
        - auto_start: bool, automatically start subprocess on first command (default: True)
18
        - check_execute: bool, check exit status of commands and raise errors (default: True)
19
        - check_tag_names: bool, validate tag name format before execution (default: True)
20
        - **kwargs: additional arguments passed to ExifTool constructor
21
        """
22

23
    @property
24
    def auto_start(self) -> bool:
25
        """Whether auto-start is enabled (read-only)"""
26

27
    @property
28
    def check_execute(self) -> bool:
29
        """Whether to check command exit status (read/write)"""
30

31
    @property  
32
    def check_tag_names(self) -> bool:
33
        """Whether to validate tag names (read/write)"""
34
```
35

36
### Enhanced Process Control
37

38
Process control methods with improved error handling and auto-start capability.
39

40
```python { .api }
41
def run(self):
42
    """
43
    Start subprocess without warnings if already running.
44
    Enhanced version of ExifTool.run() with better error handling.
45
    """
46

47
def terminate(self, **opts):
48
    """
49
    Terminate subprocess without warnings if not running.
50
    Enhanced version of ExifTool.terminate() with better error handling.
51
    
52
    Parameters:
53
    - **opts: options passed to parent terminate() method
54
    """
55

56
def execute(self, *params, **kwargs):
57
    """
58
    Enhanced execute with auto-start and error checking.
59
    
60
    Parameters:
61
    - *params: command parameters (same as ExifTool.execute)
62
    - **kwargs: additional options (same as ExifTool.execute)
63
    
64
    Returns:
65
    str or bytes: command output
66
    
67
    Raises:
68
    - ExifToolExecuteError: if check_execute enabled and command returns non-zero exit status
69
    """
70
```
71

72
### Metadata Operations
73

74
High-level methods for common metadata extraction and manipulation tasks.
75

76
```python { .api }
77
def get_metadata(self, files, params=None):
78
    """
79
    Get all metadata for specified files.
80
    
81
    Parameters:
82
    - files: str or list, file path(s) to process
83
    - params: str, list, or None, optional exiftool parameters
84
    
85
    Returns:
86
    list: list of metadata dictionaries, one per file
87
    
88
    Raises:
89
    - ValueError: if files parameter is empty
90
    - ExifToolExecuteError: if command fails
91
    """
92

93
def get_tags(self, files, tags, params=None):
94
    """
95
    Get specific tags from files.
96
    
97
    Parameters:
98
    - files: str or list, file path(s) to process  
99
    - tags: str, list, or None, tag name(s) to retrieve (None for all tags)
100
    - params: str, list, or None, optional exiftool parameters
101
    
102
    Returns:
103
    list: list of tag dictionaries, one per file
104
    
105
    Raises:
106
    - ValueError: if files parameter is empty
107
    - TypeError: if parameters have incorrect types
108
    - ExifToolTagNameError: if check_tag_names enabled and invalid tag names found
109
    - ExifToolExecuteError: if command fails
110
    """
111

112
def set_tags(self, files, tags, params=None):
113
    """
114
    Set tag values on files.
115
    
116
    Parameters:
117
    - files: str or list, file path(s) to modify
118
    - tags: dict, mapping of tag names to values
119
    - params: str, list, or None, optional exiftool parameters
120
    
121
    Returns:
122
    str: command output from exiftool
123
    
124
    Raises:
125
    - ValueError: if files parameter is empty or tags is not a dict
126
    - TypeError: if parameters have incorrect types  
127
    - ExifToolTagNameError: if check_tag_names enabled and invalid tag names found
128
    - ExifToolExecuteError: if command fails
129
    """
130
```
131

132
### Utility Methods
133

134
Static methods for parameter validation and processing.
135

136
```python { .api }
137
@staticmethod
138
def _parse_arg_files(files):
139
    """
140
    Parse files argument into list format.
141
    
142
    Parameters:
143
    - files: str or list, files parameter from user
144
    
145
    Returns:
146
    list: list of file strings
147
    
148
    Raises:
149
    - ValueError: if files is empty
150
    """
151

152
@staticmethod  
153
def _check_tag_list(tags):
154
    """
155
    Validate tag names using regex pattern.
156
    
157
    Parameters:
158
    - tags: list, list of tag names to check
159
    
160
    Raises:
161
    - ExifToolTagNameError: for invalid tag names
162
    """
163
```
164

165
## Usage Examples
166

167
### Basic Metadata Operations
168

169
```python
170
import exiftool
171

172
files = ['photo1.jpg', 'photo2.png', 'video.mp4']
173

174
with exiftool.ExifToolHelper() as et:
175
    # Get all metadata
176
    metadata = et.get_metadata(files)
177
    for data in metadata:
178
        print(f"File: {data['SourceFile']}")
179
        if 'EXIF:DateTimeOriginal' in data:
180
            print(f"Date taken: {data['EXIF:DateTimeOriginal']}")
181
        if 'EXIF:Make' in data:
182
            print(f"Camera: {data['EXIF:Make']} {data.get('EXIF:Model', '')}")
183
        print()
184
```
185

186
### Selective Tag Retrieval
187

188
```python
189
with exiftool.ExifToolHelper() as et:
190
    # Get specific tags only
191
    camera_tags = ['EXIF:Make', 'EXIF:Model', 'EXIF:LensModel', 'EXIF:FocalLength']
192
    camera_info = et.get_tags(files, camera_tags)
193
    
194
    for info in camera_info:
195
        print(f"File: {info['SourceFile']}")
196
        print(f"Camera: {info.get('EXIF:Make', 'Unknown')} {info.get('EXIF:Model', '')}")
197
        print(f"Lens: {info.get('EXIF:LensModel', 'Unknown')}")
198
        print(f"Focal Length: {info.get('EXIF:FocalLength', 'Unknown')}")
199
        print()
200
```
201

202
### Setting Tags
203

204
```python
205
with exiftool.ExifToolHelper() as et:
206
    # Set single file tags
207
    et.set_tags('photo.jpg', {
208
        'EXIF:Artist': 'John Doe',
209
        'EXIF:Copyright': '© 2023 John Doe',
210
        'IPTC:Keywords': ['landscape', 'nature', 'photography']
211
    })
212
    
213
    # Set tags on multiple files
214
    et.set_tags(['photo1.jpg', 'photo2.jpg'], {
215
        'EXIF:Artist': 'Jane Smith'
216
    })
217
```
218

219
### Custom Configuration
220

221
```python
222
# Initialize with custom settings
223
with exiftool.ExifToolHelper(
224
    check_execute=True,      # Raise errors on command failures
225
    check_tag_names=True,    # Validate tag names before execution
226
    auto_start=True,         # Auto-start subprocess on first command
227
    common_args=['-G', '-n', '-q']  # Custom common arguments
228
) as et:
229
    metadata = et.get_metadata('image.jpg')
230
```
231

232
### Error Handling Configuration
233

234
```python
235
with exiftool.ExifToolHelper() as et:
236
    # Disable error checking for non-critical operations
237
    et.check_execute = False
238
    result = et.execute('-this-might-fail', 'file.jpg')
239
    
240
    # Re-enable for critical operations
241
    et.check_execute = True
242
    metadata = et.get_metadata('important.jpg')  # Will raise on errors
243
```
244

245
### Advanced Parameter Usage
246

247
```python
248
with exiftool.ExifToolHelper() as et:
249
    # Use additional exiftool parameters
250
    metadata = et.get_metadata(
251
        files=['image1.jpg', 'image2.tiff'], 
252
        params=['-c', '%.6f']  # High precision GPS coordinates
253
    )
254
    
255
    # Get tags with custom formatting
256
    tags = et.get_tags(
257
        files='photo.jpg',
258
        tags=['EXIF:CreateDate', 'EXIF:ISO'],
259
        params=['-d', '%Y-%m-%d %H:%M:%S']  # Custom date format
260
    )
261
```