madam.iptc module

IPTC/IIM metadata processor for JPEG images.

Reads and writes IPTC Application Record (record 2) fields embedded in the JPEG APP13/Photoshop 3.0 block. No additional dependencies beyond Pillow are required.

class madam.iptc.IPTCMetadataProcessor(config: Mapping[str, Any] | None = None)[source]

Bases: MetadataProcessor

Reads and writes IPTC/IIM metadata embedded in JPEG files.

IPTC data is stored in the JPEG APP13 (Photoshop 3.0) block. Only JPEG is supported; attempts to read non-JPEG data raise UnsupportedFormatError.

Supported metadata keys under the 'iptc' namespace:

  • object_name — Object Name (dataset 5)

  • category — Category (dataset 15)

  • keywords — Keywords, list of strings (dataset 25, repeatable)

  • instructions — Special Instructions (dataset 40)

  • author — By-line / Author (dataset 80)

  • author_title — By-line Title (dataset 85)

  • city — City (dataset 90)

  • sublocation — Sublocation (dataset 92)

  • state — Province/State (dataset 95)

  • country_code — Country Code (dataset 100)

  • country — Country (dataset 101)

  • headline — Headline (dataset 105)

  • credit — Credit (dataset 110)

  • source — Source (dataset 115)

  • copyright — Copyright Notice (dataset 116)

  • caption — Caption/Abstract (dataset 120)

Added in version 0.24.

__init__(config: Mapping[str, Any] | None = None) → None[source]

Initializes a new IPTCMetadataProcessor.

Parameters:

config – Mapping with settings.

combine(file: IO, metadata: Mapping[str, Mapping]) → IO[source]

Returns a copy of the JPEG file with IPTC metadata embedded.

Existing IPTC data is replaced. Only the 'iptc' key of metadata is used; other keys are ignored.

Parameters:

  • file (IO) – Readable binary file-like object containing JPEG data.

  • metadata (Mapping) – Mapping with an 'iptc' key whose value is a dict of IPTC field names and values.

Returns:

File-like object with IPTC data embedded.

Return type:

IO

Raises:

UnsupportedFormatError – if metadata contains an unknown IPTC format key.

property formats: Iterable[str]

The metadata formats which are supported.

Returns:

supported metadata formats

Return type:

set[str]

read(file: IO) → Mapping[str, Mapping][source]

Reads IPTC metadata from a JPEG file.

Parameters:

file (IO) – Readable binary file-like object containing JPEG data.

Returns:

Mapping with a single 'iptc' key whose value is a dict of decoded metadata fields. Returns an empty mapping when the file contains no IPTC data.

Return type:

Mapping[str, Mapping]

Raises:

UnsupportedFormatError – if the data is not a JPEG file.

strip(file: IO) → IO[source]

Returns a copy of the JPEG file with all IPTC (APP13) data removed.

Parameters:

file (IO) – Readable binary file-like object containing JPEG data.

Returns:

File-like object with IPTC data removed.

Return type:

IO

Raises:

UnsupportedFormatError – if the data is not a JPEG file.