### Install IPTCInfo3

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Commands to install the library using pip or uv.

```bash
# Using pip
pip install IPTCInfo3

# Using uv (recommended)
uv pip install IPTCInfo3
```

--------------------------------

### Install Prerequisites

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Install the uv package manager and twine for distribution management.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install twine for PyPI uploads (optional, uv can also publish)
uv pip install twine
```

--------------------------------

### Install IPTCInfo3

Source: https://github.com/james-see/iptcinfo3/blob/master/README.rst

Installation commands for the library using standard package managers.

```bash
pip install IPTCInfo3
```

```bash
uv pip install IPTCInfo3
```

--------------------------------

### Start local documentation server

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/README.md

Use Python's built-in HTTP server to host the documentation files locally.

```bash
cd docs
python3 -m http.server 8000
# Then visit http://localhost:8000
```

--------------------------------

### Install IPTCInfo3 via uv

Source: https://github.com/james-see/iptcinfo3/blob/master/RELEASE_NOTES_v2.2.0.md

Installation command for the library using the uv package manager.

```bash
uv pip install IPTCInfo3==2.2.0
```

--------------------------------

### Install IPTCInfo3 via pip

Source: https://github.com/james-see/iptcinfo3/blob/master/RELEASE_NOTES_v2.2.0.md

Standard installation command for the library using pip.

```bash
pip install IPTCInfo3==2.2.0
```

--------------------------------

### Test from PyPI

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Install the package from the production PyPI index.

```bash
uv pip install iptcinfo3
```

--------------------------------

### Test Package Locally

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Install the package in development mode or from a specific wheel file for local verification.

```bash
# Install in development mode
uv pip install -e .

# Or install from the built wheel
uv pip install dist/iptcinfo3-2.2.0-py3-none-any.whl
```

--------------------------------

### Test from TestPyPI

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Install the package from the TestPyPI index to verify the remote distribution.

```bash
uv pip install --index-url https://test.pypi.org/simple/ iptcinfo3
```

--------------------------------

### Batch Process Images with IPTC Metadata

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Iterates through all JPEG files in a specified directory, updates their copyright notice, appends a keyword, and saves the changes. This example requires the 'os' module and assumes images are in a 'photos' subdirectory.

```python
import os
from iptcinfo3 import IPTCInfo

# Process all JPEG files in a directory
for filename in os.listdir('photos'):
    if filename.lower().endswith('.jpg'):
        info = IPTCInfo(f'photos/{filename}', force=True)
        info['copyright notice'] = '© 2024 Your Name'
        info['keywords'].append('batch-processed')
        info.save()
        print(f"Processed {filename}")
```

--------------------------------

### Open documentation locally

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/README.md

Use the open command to view the documentation file in the default browser.

```bash
open docs/index.html
```

--------------------------------

### Build the Package

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Clean existing build artifacts and generate new source and wheel distributions.

```bash
# Clean previous builds
rm -rf dist/

# Build with uv (creates both .tar.gz and .whl)
uv build
```

--------------------------------

### Publish to PyPI using uv

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Upload the built distributions to PyPI or TestPyPI using the uv publish command.

```bash
# Publish to PyPI (requires PyPI credentials)
uv publish

# Or publish to TestPyPI first
uv publish --publish-url https://test.pypi.org/legacy/
```

--------------------------------

### Initialize IPTCInfo Object

Source: https://github.com/james-see/iptcinfo3/blob/master/README.rst

Import the library and create an instance to read metadata from an image file.

```python
from iptcinfo3 import IPTCInfo
```

```python
info = IPTCInfo('doge.jpg')
```

```python
info = IPTCInfo('such_iptc.jpg', force=True)
```

--------------------------------

### Configure PyPI Credentials

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Set up authentication for PyPI uploads using a configuration file or environment variables.

```ini
[pypi]
username = __token__
password = pypi-...your-token...

[testpypi]
username = __token__
password = pypi-...your-token...
```

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-...your-token...
```

--------------------------------

### Inspect IPTC Metadata via Command Line

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Demonstrates how to use the `iptcinfo3` library directly from the command line to inspect IPTC metadata of a JPEG image. Shows both module and script execution.

```bash
# Run as module to inspect an image
python -m iptcinfo3 photo.jpg

# Or use the script directly
python iptcinfo3.py photo.jpg

# Example output:
# _data
# 105 b'Mountain Sunrise'
# 25 [b'nature', b'landscape', b'mountains']
# 120 b'A beautiful mountain landscape at sunrise'
# 116 b'2024 Photographer Name'
```

--------------------------------

### Publish to PyPI using twine

Source: https://github.com/james-see/iptcinfo3/blob/master/PUBLISHING.md

Verify distributions and upload them to PyPI or TestPyPI using twine.

```bash
# Check the distributions
twine check dist/*

# Upload to TestPyPI first (optional)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*
```

--------------------------------

### Create IPTC Data with force=True

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Use `force=True` to initialize IPTC metadata for images that lack it. This allows setting new metadata fields and saving them.

```python
from iptcinfo3 import IPTCInfo

# Create IPTC info for an image without existing metadata
info = IPTCInfo('new_photo.jpg', force=True)

# Set metadata fields
info['caption/abstract'] = 'A stunning sunset over the Pacific Ocean'
info['headline'] = 'Pacific Sunset'
info['keywords'] = ['sunset', 'ocean', 'pacific', 'nature', 'landscape']
info['supplemental category'] = ['travel', 'nature photography']
info['by-line'] = 'Jane Photographer'
info['by-line title'] = 'Staff Photographer'
info['copyright notice'] = '2024 Jane Photographer. All rights reserved.'
info['credit line'] = 'Photography Studio Inc.'
info['source'] = 'Photography Studio Inc.'
info['city'] = 'San Francisco'
info['province/state'] = 'California'
info['country/primary location name'] = 'United States'

# Save the metadata to the original file
info.save()

# Verify the metadata was saved
info2 = IPTCInfo('new_photo.jpg')
print(f"Headline: {info2['headline']}")
print(f"Keywords: {info2['keywords']}")
```

--------------------------------

### Create and Access IPTCData

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Instantiate IPTCData using numeric or string keys and access fields by either code or name (case-insensitive). Demonstrates checking for field existence and using nonstandard fields.

```python
from iptcinfo3 import IPTCData

# Create IPTCData with numeric or string keys
data = IPTCData({
    105: 'My Headline',           # Numeric key
    'caption/abstract': 'My Caption',  # String key
    'keywords': ['tag1', 'tag2'],
})

# Access by numeric code or field name (case-insensitive)
print(data[105])              # 'My Headline'
print(data['headline'])       # 'My Headline'
print(data['Headline'])       # 'My Headline'

# Check if field exists
print('headline' in data)     # True
print(105 in data)            # True

# Use nonstandard fields (codes not in IPTC spec)
data2 = IPTCData({'nonstandard_69': 'custom value'})
print(data2[69])              # 'custom value'
```

--------------------------------

### Save File with Overwrite Option

Source: https://github.com/james-see/iptcinfo3/blob/master/ISSUE_CLOSING_COMMENTS.md

Use the overwrite option to prevent the creation of backup files with a tilde suffix.

```python
info.save_as('image.jpg', {'overwrite': True})
```

--------------------------------

### Handle Different Charsets for IPTC Data

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Initializes IPTCInfo with specified input and output charsets to correctly handle various character encodings, including ISO 2022 escape sequences like UTF-8 (ESC % G).

```python
# Specify input and output charsets
info = IPTCInfo('photo.jpg', inp_charset='utf8', out_charset='utf8')

# The library now properly handles ISO 2022 escape sequences
# including UTF-8 (ESC % G) automatically
```

--------------------------------

### Assigning and Saving Custom Metadata Fields

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Use custom keys to store non-standard metadata and call the save method to commit changes to the file.

```python
# Custom fields (custom1 through custom20) for non-standard metadata
info['custom1'] = 'Custom metadata value'
info['custom2'] = 'Another custom value'
info.save()
```

--------------------------------

### Write IPTC Metadata to Image

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Sets various IPTC metadata fields for an image file and saves the changes. Use force=True to create IPTC data for images that do not have it. The changes can be saved to the original file or a new one.

```python
from iptcinfo3 import IPTCInfo

# Open or create IPTC info (force=True for files without IPTC data)
info = IPTCInfo('photo.jpg', force=True)

# Set metadata
info['caption/abstract'] = 'A beautiful sunset over the mountains'
info['keywords'] = ['sunset', 'mountains', 'landscape']
info['copyright notice'] = '© 2024 Your Name'
info['credit line'] = 'Your Photography Studio'

# Save changes
info.save()

# Or save to a new file
info.save_as('photo_with_metadata.jpg')
```

--------------------------------

### Read IPTC Metadata from Image

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Opens an image file and prints specific IPTC metadata fields like caption, keywords, copyright, and by-line. Ensure the image file exists.

```python
from iptcinfo3 import IPTCInfo

# Open an image file
info = IPTCInfo('photo.jpg')

# Read metadata
print(info['caption/abstract'])
print(info['keywords'])
print(info['copyright notice'])
print(info['by-line'])
```

--------------------------------

### Verify IPTC Metadata Lists

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Extract and print keywords, supplemental categories, and contact information from an image's IPTC metadata.

```python
info2 = IPTCInfo('photo.jpg')
print(f"Keywords: {info2['keywords']}")
print(f"Categories: {info2['supplemental category']}")
print(f"Contacts: {info2['contact']}")
```

--------------------------------

### Save Metadata Changes

Source: https://github.com/james-see/iptcinfo3/blob/master/README.rst

Persist changes back to the original file or save to a new file.

```python
info.save()
info.save_as('very_meta.jpg')
```

--------------------------------

### Set Destination Field

Source: https://github.com/james-see/iptcinfo3/blob/master/ISSUE_CLOSING_COMMENTS.md

Use the 'destination' alias for the 'original transmission reference' dataset to ensure compatibility with gThumb and exiftool.

```python
info['destination'] = 'Your destination'
```

--------------------------------

### Set Credit Line Field

Source: https://github.com/james-see/iptcinfo3/blob/master/ISSUE_CLOSING_COMMENTS.md

Update credit information using either the new standard 'credit line' field or the legacy 'credit' field for backward compatibility.

```python
info['credit line'] = 'Your credit'  # New standard name
info['credit'] = 'Your credit'       # Still works for compatibility
```

--------------------------------

### Save IPTC Metadata to a New File

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Utilize the `save_as()` method to save modified IPTC metadata to a different file, preserving the original. Options include overwriting and discarding Adobe data.

```python
from iptcinfo3 import IPTCInfo

# Read existing image
info = IPTCInfo('original.jpg')

# Modify the metadata
info['headline'] = 'Updated Headline'
info['keywords'].append('new-keyword')

# Save to a new file (creates backup of existing file by default)
info.save_as('modified.jpg')

# Save to a new file, overwriting if it exists (no backup)
info.save_as('modified.jpg', options={'overwrite': True})

# Discard Adobe application parts (remove Photoshop-specific data)
info.save_as('clean.jpg', options={'discardAdobeParts': True})
```

--------------------------------

### IPTC Fields Reference

Source: https://context7.com/james-see/iptcinfo3/llms.txt

A reference dictionary mapping standard IPTC IIM record 2 field numbers and names to their descriptions and expected data types. This is for informational purposes and not executable code.

```python
# Standard IPTC Fields (string values unless noted):
IPTC_FIELDS = {
    5: 'object name',                    # Title/name of the image
    7: 'edit status',                    # Editorial status
    10: 'urgency',                       # Urgency (1=high, 5=normal, 8=low)
    15: 'category',                      # Subject category code
    20: 'supplemental category',         # LIST: Additional categories
    22: 'fixture identifier',            # Recurring/recurring event ID
    25: 'keywords',                      # LIST: Searchable keywords
    26: 'content location code',         # ISO country code
    27: 'content location name',         # Location name
    30: 'release date',                  # Date for release (YYYYMMDD)
    35: 'release time',                  # Time for release (HHMMSS)
    40: 'special instructions',          # Handling instructions
    55: 'date created',                  # Creation date (YYYYMMDD)
    60: 'time created',                  # Creation time (HHMMSS)
    65: 'originating program',           # Software that created file
    70: 'program version',               # Version of originating program
    80: 'by-line',                       # Creator/photographer name
    85: 'by-line title',                 # Creator's job title
    90: 'city',                          # City of content origin
    92: 'sub-location',                  # Location within city
    95: 'province/state',                # State/province
    100: 'country/primary location code', # ISO country code
    101: 'country/primary location name', # Country name
    103: 'original transmission reference', # Job ID (alias: 'destination')
    105: 'headline',                     # Brief synopsis
    110: 'credit line',                  # Provider (alias: 'credit')
    115: 'source',                       # Original owner/creator
    116: 'copyright notice',             # Copyright statement
    118: 'contact',                      # LIST: Contact information
    120: 'caption/abstract',             # Full description
    122: 'writer/editor',                # Caption writer
    130: 'image type',                   # Type of image
    131: 'image orientation',            # Orientation (P/L/S)
    135: 'language identifier',          # ISO language code
    # Custom fields 200-219 (custom1 through custom20) for non-standard use
}

```

--------------------------------

### Batch Add Metadata to JPEGs

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Processes all JPEG files in a directory, adding consistent copyright and photographer information. Ensures 'batch-processed' keyword is added if not present. Overwrites existing files without creating backups.

```python
import os
from iptcinfo3 import IPTCInfo

def batch_add_metadata(directory, copyright_text, photographer):
    """Add copyright and photographer info to all JPEGs in directory."""
    processed = 0
    errors = []

    for filename in os.listdir(directory):
        if not filename.lower().endswith(('.jpg', '.jpeg')):
            continue

        filepath = os.path.join(directory, filename)
        try:
            info = IPTCInfo(filepath, force=True)

            # Add standard metadata
            info['copyright notice'] = copyright_text
            info['by-line'] = photographer
            info['source'] = photographer

            # Add processing keyword
            if 'batch-processed' not in (info['keywords'] or []):
                info['keywords'].append('batch-processed')

            # Save with overwrite to avoid creating backup files
            info.save_as(filepath, options={'overwrite': True})
            processed += 1
            print(f"Processed: {filename}")

        except Exception as e:
            errors.append((filename, str(e)))
            print(f"Error processing {filename}: {e}")

    return processed, errors

# Usage
processed, errors = batch_add_metadata(
    directory='./photos',
    copyright_text='2024 Photography Studio. All rights reserved.',
    photographer='John Smith'
)
print(f"\nProcessed {processed} files with {len(errors)} errors")
```

--------------------------------

### Disable Backup Files During Save

Source: https://github.com/james-see/iptcinfo3/blob/master/docs/index.html

Saves changes to an image file without creating a backup file. This is achieved by passing the 'overwrite': True option to the save_as method.

```python
# By default, save operations create a backup with ~ suffix
# To disable this, use the overwrite option:
info.save_as('photo.jpg', {'overwrite': True})
```

--------------------------------

### Read IPTC Metadata from JPEG

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Open a JPEG file and access its IPTC metadata using dictionary-like keys. This is useful for inspecting existing metadata.

```python
from iptcinfo3 import IPTCInfo

# Open a JPEG file and read its IPTC metadata
info = IPTCInfo('photo.jpg')

# Access metadata using field names
caption = info['caption/abstract']
keywords = info['keywords']
copyright_notice = info['copyright notice']
photographer = info['by-line']
headline = info['headline']

# Print all available metadata
print(f"Caption: {caption}")
print(f"Keywords: {keywords}")
print(f"Copyright: {copyright_notice}")
print(f"Photographer: {photographer}")
print(f"Headline: {headline}")
```

--------------------------------

### Manage List-Based IPTC Fields

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Handle fields like keywords, supplemental categories, and contacts which support multiple values using the `UniqueList` class. This class prevents duplicate entries automatically.

```python
from iptcinfo3 import IPTCInfo

info = IPTCInfo('photo.jpg', force=True)

# Keywords field - supports multiple values
info['keywords'] = ['photography', 'nature', 'wildlife']

# Append additional keywords (duplicates are automatically prevented)
info['keywords'].append('landscape')
info['keywords'].append('photography')  # Won't be added (already exists)

# Supplemental categories
info['supplemental category'] = ['portrait', 'outdoor']
info['supplemental category'].append('nature')

# Contacts (multiple contact entries)
info['contact'] = ['editor@example.com', 'sales@example.com']
info['contact'].append('support@example.com')

info.save()
```

--------------------------------

### Access Metadata Attributes

Source: https://github.com/james-see/iptcinfo3/blob/master/README.rst

Retrieve specific IPTC metadata fields from the info object.

```python
print(info['keywords'])
print(info['supplementalCategories'])
print(info['contacts'])
```

```python
caption = info['caption/abstract']
```

--------------------------------

### Set IPTC Metadata with UTF-8 Encoding

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Specify UTF-8 encoding for reading and writing IPTC metadata and set international characters in various fields. Ensure the image file exists and is accessible.

```python
from iptcinfo3 import IPTCInfo

# Specify UTF-8 encoding for reading and writing
info = IPTCInfo('photo.jpg', force=True, inp_charset='utf_8', out_charset='utf_8')

# Set metadata with international characters
info['caption/abstract'] = 'Caf\u00e9 in Paris - \u4e2d\u6587\u6587\u5b57'
info['city'] = 'M\u00fcnchen'
info['country/primary location name'] = 'Deutschland'
info['headline'] = '\u65e5\u672c\u306e\u5bcc\u58eb\u5c71'

info.save()
```

--------------------------------

### Extract JPEG File Parts

Source: https://context7.com/james-see/iptcinfo3/llms.txt

A low-level function to parse and extract the structural components of a JPEG file, including header, image data, and Adobe resource parts. Useful for debugging or custom processing.

```python
from iptcinfo3 import jpeg_collect_file_parts

# Parse JPEG structure
with open('photo.jpg', 'rb') as fh:
    start, end, adobe = jpeg_collect_file_parts(fh)

print(f"Header section: {len(start)} bytes")
print(f"Image data section: {len(end)} bytes")
print(f"Adobe parts: {len(adobe)} bytes")

# The three parts can be used to reconstruct the JPEG:
# - start: JPEG header and markers before IPTC data
# - end: Image data (compressed scan data and EOI marker)
# - adobe: Adobe resource data (excluding IPTC) to preserve
```

--------------------------------

### Safely Read IPTC Data with JPEG Validation

Source: https://context7.com/james-see/iptcinfo3/llms.txt

Verifies if a file is a valid JPEG using `file_is_jpeg` before attempting to read IPTC data. Raises a ValueError if the file is not a JPEG.

```python
from iptcinfo3 import file_is_jpeg, IPTCInfo

def safe_read_iptc(filepath):
    """Safely read IPTC data, checking file type first."""
    with open(filepath, 'rb') as fh:
        if not file_is_jpeg(fh):
            raise ValueError(f"{filepath} is not a valid JPEG file")

    return IPTCInfo(filepath)

# Usage
try:
    info = safe_read_iptc('photo.jpg')
    print(f"Caption: {info['caption/abstract']}")
except ValueError as e:
    print(f"Error: {e}")
except Exception as e:
    print(f"Failed to read IPTC data: {e}")
```

--------------------------------

### Modify Metadata Attributes

Source: https://github.com/james-see/iptcinfo3/blob/master/README.rst

Update or append values to IPTC metadata fields.

```python
info['caption/abstract'] = 'Witty caption here'
info['supplemental category'] = ['portrait']
```

```python
info['keywords']).append('cool')
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.