0
# Experimental Features
1
2
The ExifToolAlpha class provides experimental functionality for specialized use cases including enhanced error handling, batch operations, keyword management, and file-to-file tag copying. These features are considered alpha-quality and may change in future versions.
3
4
## Capabilities
5
6
### Enhanced Execution Methods
7
8
Wrapper methods with additional error handling, retry logic, and validation for robust batch processing.
9
10
```python { .api }
11
class ExifToolAlpha(ExifToolHelper):
12
def execute_json_wrapper(self, filenames, params=None, retry_on_error=True):
13
"""
14
Execute JSON command with error handling and retry logic.
15
16
Parameters:
17
- filenames: iterable of str, files to process
18
- params: list or None, optional parameters
19
- retry_on_error: bool, retry on subprocess errors (default: True)
20
21
Returns:
22
list: list of metadata dictionaries
23
"""
24
25
def get_metadata_batch_wrapper(self, filenames, params=None):
26
"""
27
Get metadata for multiple files with additional checks.
28
29
Parameters:
30
- filenames: iterable, files to process
31
- params: list or None, optional parameters
32
33
Returns:
34
list: list of metadata dictionaries
35
"""
36
37
def get_metadata_wrapper(self, filename, params=None):
38
"""
39
Get metadata for single file with additional checks.
40
41
Parameters:
42
- filename: str, single file to process
43
- params: list or None, optional parameters
44
45
Returns:
46
dict: single metadata dictionary
47
"""
48
```
49
50
### Enhanced Tag Operations
51
52
Extended tag retrieval methods with additional validation and error handling.
53
54
```python { .api }
55
def get_tags_batch_wrapper(self, tags, filenames, params=None):
56
"""
57
Get specific tags from multiple files with checks.
58
59
Parameters:
60
- tags: list, tag names to retrieve
61
- filenames: iterable, files to process
62
- params: list or None, optional parameters
63
64
Returns:
65
list: list of tag dictionaries
66
"""
67
68
def get_tags_wrapper(self, tags, filename, params=None):
69
"""
70
Get specific tags from single file.
71
72
Parameters:
73
- tags: list, tag names to retrieve
74
- filename: str, single file to process
75
- params: list or None, optional parameters
76
77
Returns:
78
dict: single tag dictionary
79
"""
80
81
def get_tag_batch_wrapper(self, tag, filenames, params=None):
82
"""
83
Get single tag value from multiple files.
84
85
Parameters:
86
- tag: str, single tag name
87
- filenames: iterable, files to process
88
- params: list or None, optional parameters
89
90
Returns:
91
list: list of tag values
92
"""
93
94
def get_tag_wrapper(self, tag, filename, params=None):
95
"""
96
Get single tag value from single file.
97
98
Parameters:
99
- tag: str, single tag name
100
- filename: str, single file to process
101
- params: list or None, optional parameters
102
103
Returns:
104
any: single tag value
105
"""
106
```
107
108
### Legacy Single-Tag Methods
109
110
Legacy methods for single tag extraction with existence checks.
111
112
```python { .api }
113
def get_tag_batch(self, filenames, tag):
114
"""
115
Extract single tag from multiple files (legacy method).
116
117
Parameters:
118
- filenames: iterable, files to process
119
- tag: str, single tag name
120
121
Returns:
122
list or None: list of tag values or None
123
"""
124
125
def get_tag(self, filename, tag):
126
"""
127
Extract single tag from single file with existence checks.
128
129
Parameters:
130
- filename: str, file to process
131
- tag: str, tag name to retrieve
132
133
Returns:
134
any or None: tag value or None
135
136
Raises:
137
- FileNotFoundError: if file does not exist
138
- RuntimeError: if other processing errors occur
139
"""
140
```
141
142
### File Operations
143
144
Advanced operations for copying tags between files and specialized metadata management.
145
146
```python { .api }
147
def copy_tags(self, from_filename, to_filename):
148
"""
149
Copy all tags from one file to another.
150
151
Parameters:
152
- from_filename: str, source file
153
- to_filename: str, destination file
154
"""
155
```
156
157
### Keyword Management
158
159
Specialized methods for managing IPTC Keywords tags with different operation modes.
160
161
```python { .api }
162
def set_keywords_batch(self, files, mode, keywords):
163
"""
164
Modify keywords tag for multiple files.
165
166
Parameters:
167
- files: iterable, files to modify
168
- mode: int, operation mode (KW_REPLACE, KW_ADD, or KW_REMOVE)
169
- keywords: iterable of str, keywords to process
170
171
Returns:
172
str: command execution result
173
174
Raises:
175
- TypeError: if parameters have incorrect types
176
"""
177
178
def set_keywords(self, filename, mode, keywords):
179
"""
180
Modify keywords tag for single file.
181
182
Parameters:
183
- filename: str, file to modify
184
- mode: int, operation mode (KW_REPLACE, KW_ADD, or KW_REMOVE)
185
- keywords: iterable of str, keywords to process
186
187
Returns:
188
str: command execution result
189
"""
190
```
191
192
### Validation Utilities
193
194
Static methods for result validation and error checking.
195
196
```python { .api }
197
@staticmethod
198
def _check_result_filelist(file_paths, result):
199
"""
200
Validate that result matches requested files.
201
202
Parameters:
203
- file_paths: list, requested file paths
204
- result: list, returned results from exiftool
205
206
Raises:
207
- IOError: if mismatch detected between requested and returned files
208
"""
209
```
210
211
## Constants
212
213
Keyword operation mode constants for use with keyword management methods.
214
215
```python { .api }
216
KW_TAGNAME = "IPTC:Keywords" # Keywords tag name
217
KW_REPLACE = 0 # Replace keywords mode
218
KW_ADD = 1 # Add keywords mode
219
KW_REMOVE = 2 # Remove keywords mode
220
```
221
222
## Utility Functions
223
224
Helper functions for result processing and error checking.
225
226
```python { .api }
227
def strip_nl(s):
228
"""
229
Strip newlines from string, replacing with spaces.
230
231
Parameters:
232
- s: str, string to process
233
234
Returns:
235
str: string with newlines replaced by spaces
236
"""
237
238
def check_ok(result):
239
"""
240
Check if exiftool write operation succeeded.
241
242
Parameters:
243
- result: str, output from execute() method
244
245
Returns:
246
bool: True if operation appears successful
247
"""
248
249
def format_error(result):
250
"""
251
Format exiftool operation result as human-readable message.
252
253
Parameters:
254
- result: str, output from execute() method
255
256
Returns:
257
str: formatted status message
258
"""
259
```
260
261
## Usage Examples
262
263
### Robust Batch Processing
264
265
```python
266
import exiftool
267
268
files = ['photo1.jpg', 'photo2.png', 'photo3.tiff']
269
270
with exiftool.ExifToolAlpha() as et:
271
# Enhanced error handling for batch operations
272
try:
273
metadata = et.get_metadata_batch_wrapper(files)
274
for data in metadata:
275
print(f"Processed: {data['SourceFile']}")
276
except Exception as e:
277
print(f"Batch processing failed: {e}")
278
```
279
280
### Single Tag Extraction
281
282
```python
283
with exiftool.ExifToolAlpha() as et:
284
# Get single tag from multiple files
285
iso_values = et.get_tag_batch_wrapper('EXIF:ISO', files)
286
287
for i, iso in enumerate(iso_values):
288
print(f"{files[i]}: ISO {iso}")
289
290
# Get single tag with existence check
291
camera_make = et.get_tag('photo.jpg', 'EXIF:Make')
292
if camera_make:
293
print(f"Camera make: {camera_make}")
294
else:
295
print("No camera make information found")
296
```
297
298
### Tag Copying
299
300
```python
301
with exiftool.ExifToolAlpha() as et:
302
# Copy all metadata from source to destination
303
et.copy_tags('source_with_metadata.jpg', 'destination.jpg')
304
print("Tags copied successfully")
305
```
306
307
### Keyword Management
308
309
```python
310
from exiftool.experimental import KW_REPLACE, KW_ADD, KW_REMOVE
311
312
with exiftool.ExifToolAlpha() as et:
313
# Replace all keywords
314
et.set_keywords('photo.jpg', KW_REPLACE, ['landscape', 'nature', 'sunset'])
315
316
# Add new keywords
317
et.set_keywords('photo.jpg', KW_ADD, ['golden hour', 'mountains'])
318
319
# Remove specific keywords
320
et.set_keywords('photo.jpg', KW_REMOVE, ['sunset'])
321
322
# Batch keyword operations
323
et.set_keywords_batch(
324
files=['photo1.jpg', 'photo2.jpg'],
325
mode=KW_ADD,
326
keywords=['vacation', '2023']
327
)
328
```
329
330
### Enhanced Error Checking
331
332
```python
333
from exiftool.experimental import check_ok, format_error
334
335
with exiftool.ExifToolAlpha() as et:
336
# Execute operation and check result
337
result = et.execute('-overwrite_original', '-EXIF:Artist=Jane Doe', 'photo.jpg')
338
339
if check_ok(result):
340
print("Tags updated successfully")
341
else:
342
error_msg = format_error(result)
343
print(f"Operation failed: {error_msg}")
344
```
345
346
### Result Validation
347
348
```python
349
with exiftool.ExifToolAlpha() as et:
350
requested_files = ['photo1.jpg', 'photo2.jpg', 'photo3.jpg']
351
352
# Get metadata with validation
353
metadata = et.get_metadata_batch_wrapper(requested_files)
354
355
# Validate results match request
356
try:
357
et._check_result_filelist(requested_files, metadata)
358
print("All files processed successfully")
359
except IOError as e:
360
print(f"File processing mismatch: {e}")
361
```