API documentation

pyexiv2

pyexiv2.version_info
A tuple containing the three components of the version number: major, minor, micro.
pyexiv2.__version__
The version of the module as a string (major.minor.micro).
pyexiv2.exiv2_version_info
A tuple containing the three components of the version number of libexiv2: major, minor, micro.
pyexiv2.__exiv2_version__
The version of libexiv2 as a string (major.minor.micro).

pyexiv2.metadata

class pyexiv2.metadata.ImageMetadata(filename)

A container for all the metadata embedded in an image.

It provides convenient methods for the manipulation of EXIF, IPTC and XMP metadata embedded in image files such as JPEG and TIFF files, using Python types. It also provides access to the previews embedded in an image.

classmethod from_buffer(buffer)

Instantiate an image container from an image buffer.

Parameter:buffer (string) – a buffer containing image data
read()
Read the metadata embedded in the associated image. It is necessary to call this method once before attempting to access the metadata (an exception will be raised if trying to access metadata before calling this method).
write(preserve_timestamps=False)

Write the metadata back to the image.

Parameter:preserve_timestamps (boolean) – whether to preserve the file’s original timestamps (access time and modification time)
dimensions
A tuple containing the width and height of the image, expressed in pixels.
mime_type
The mime type of the image, as a string.
exif_keys
List of the keys of the available EXIF tags.
iptc_keys
List of the keys of the available IPTC tags.
xmp_keys
List of the keys of the available XMP tags.
__getitem__(key)

Get a metadata tag for a given key.

Parameter:key (string) – metadata key in the dotted form familyName.groupName.tagName where familyName may be one of exif, iptc or xmp.
Raises KeyError:
 if the tag doesn’t exist
__setitem__(key, tag_or_value)

Set a metadata tag for a given key. If the tag was previously set, it is overwritten. As a handy shortcut, a value may be passed instead of a fully formed tag. The corresponding tag object will be instantiated.

Parameters:
  • key (string) – metadata key in the dotted form familyName.groupName.tagName where familyName may be one of exif, iptc or xmp.
  • tag_or_value (pyexiv2.exif.ExifTag or pyexiv2.iptc.IptcTag or pyexiv2.xmp.XmpTag or any valid value type) – an instance of the corresponding family of metadata tag, or a value
Raises KeyError:
 

if the key is invalid

__delitem__(key)

Delete a metadata tag for a given key.

Parameter:key (string) – metadata key in the dotted form familyName.groupName.tagName where familyName may be one of exif, iptc or xmp.
Raises KeyError:
 if the tag with the given key doesn’t exist
comment
The image comment.
previews
List of the previews available in the image, sorted by increasing size.
copy(other, exif=True, iptc=True, xmp=True, comment=True)

Copy the metadata to another image. The metadata in the destination is overridden. In particular, if the destination contains e.g. EXIF data and the source doesn’t, it will be erased in the destination, unless explicitly omitted.

Parameters:
  • other (pyexiv2.metadata.ImageMetadata) – the destination metadata to copy to (it must have been read() beforehand)
  • exif (boolean) – whether to copy the EXIF metadata
  • iptc (boolean) – whether to copy the IPTC metadata
  • xmp (boolean) – whether to copy the XMP metadata
  • comment (boolean) – whether to copy the image comment
buffer
The image buffer as a string. If metadata has been modified, the data won’t be up-to-date until write() has been called.

pyexiv2.exif

exception pyexiv2.exif.ExifValueError(value, type)

Exception raised when failing to parse the value of an EXIF tag.

Attribute value:
 the value that fails to be parsed
Attribute type:the EXIF type of the tag
class pyexiv2.exif.ExifTag(key, value=None, _tag=None)

An EXIF tag.

Here is a correspondance table between the EXIF types and the possible python types the value of a tag may take:

  • Ascii: datetime.datetime, datetime.date, string
  • Byte, SByte: string
  • Comment: string
  • Long, SLong: [list of] long
  • Short, SShort: [list of] int
  • Rational, SRational: [list of] pyexiv2.utils.Rational
  • Undefined: string
key
The key of the tag in the dotted form familyName.groupName.tagName where familyName = exif.
type
The EXIF type of the tag (one of Ascii, Byte, SByte, Comment, Short, SShort, Long, SLong, Rational, SRational, Undefined).
name
The name of the tag (this is also the third part of the key).
label
The title (label) of the tag.
description
The description of the tag.
section_name
The name of the tag’s section.
section_description
The description of the tag’s section.
raw_value
The raw value of the tag as a string.
value
The value of the tag as a python object.
human_value
A (read-only) human-readable representation of the value of the tag.

pyexiv2.iptc

exception pyexiv2.iptc.IptcValueError(value, type)

Exception raised when failing to parse the value of an IPTC tag.

Attribute value:
 the value that fails to be parsed
Attribute type:the IPTC type of the tag
class pyexiv2.iptc.IptcTag(key, values=None, _tag=None)

An IPTC tag.

This tag can have several values (tags that have the repeatable property).

Here is a correspondance table between the IPTC types and the possible python types the value of a tag may take:

  • Short: int
  • String: string
  • Date: datetime.date
  • Time: datetime.time
  • Undefined: string
key
The key of the tag in the dotted form familyName.groupName.tagName where familyName = iptc.
type
The IPTC type of the tag (one of Short, String, Date, Time, Undefined).
name
The name of the tag (this is also the third part of the key).
title
The title (label) of the tag.
description
The description of the tag.
photoshop_name
The Photoshop name of the tag.
repeatable
Whether the tag is repeatable (accepts several values).
record_name
The name of the tag’s record.
record_description
The description of the tag’s record.
raw_values
The raw values of the tag as a list of strings.
values
The values of the tag as a list of python objects.

pyexiv2.xmp

exception pyexiv2.xmp.XmpValueError(value, type)

Exception raised when failing to parse the value of an XMP tag.

Attribute value:
 the value that fails to be parsed
Attribute type:the XMP type of the tag
class pyexiv2.xmp.XmpTag(key, value=None, _tag=None)

An XMP tag.

Here is a correspondance table between the XMP types and the possible python types the value of a tag may take:

  • alt, bag, seq: list of the contained simple type
  • lang alt: dict of (language-code: value)
  • Boolean: boolean
  • Colorant: [not implemented yet]
  • Date: datetime.date, datetime.datetime
  • Dimensions: [not implemented yet]
  • Font: [not implemented yet]
  • GPSCoordinate: pyexiv2.utils.GPSCoordinate
  • Integer: int
  • Locale: [not implemented yet]
  • MIMEType: 2-tuple of strings
  • Rational: pyexiv2.utils.Rational
  • Real: [not implemented yet]
  • AgentName, ProperName, Text: unicode string
  • Thumbnail: [not implemented yet]
  • URI, URL: string
  • XPath: [not implemented yet]
key
The key of the tag in the dotted form familyName.groupName.tagName where familyName = xmp.
type
The XMP type of the tag.
name
The name of the tag (this is also the third part of the key).
title
The title (label) of the tag.
description
The description of the tag.
raw_value
The raw value of the tag as a [list of] string(s).
value
The value of the tag as a [list of] python object(s).

pyexiv2.preview

class pyexiv2.preview.Preview(preview)

A preview image (properties and data buffer) embedded in image metadata.

mime_type
The mime type of the preview image (e.g. image/jpeg).
extension
The file extension of the preview image with a leading dot (e.g. .jpg).
size
The size of the preview image in bytes.
dimensions
A tuple containing the width and height of the preview image in pixels.
data
The preview image data buffer.
write_to_file(path)

Write the preview image to a file on disk. The file extension will be automatically appended to the path.

Parameter:path (string) – path to write the preview to (without an extension)

pyexiv2.utils

pyexiv2.utils.undefined_to_string(undefined)

Convert an undefined string into its corresponding sequence of bytes. The undefined string must contain the ascii codes of a sequence of bytes, each followed by a blank space (e.g. “48 50 50 49 ” will be converted into “0221”). The Undefined type is part of the EXIF specification.

Parameter:undefined (string) – an undefined string
Returns:the corresponding decoded string
Return type:string
pyexiv2.utils.string_to_undefined(sequence)

Convert a string into its undefined form. The undefined form contains a sequence of ascii codes, each followed by a blank space (e.g. “0221” will be converted into “48 50 50 49 “). The Undefined type is part of the EXIF specification.

Parameter:sequence (string) – a sequence of bytes
Returns:the corresponding undefined string
Return type:string
class pyexiv2.utils.Rational(numerator, denominator)

A class representing a rational number.

Its numerator and denominator are read-only properties.

numerator
The numerator of the rational number.
denominator
The denominator of the rational number.
static from_string(string)

Instantiate a Rational from a string formatted as [-]numerator/denominator.

Parameter:string (string) – a string representation of a rational number
Returns:the rational number parsed
Return type:Rational
Raises ValueError:
 if the format of the string is invalid
to_float()
Returns:a floating point number approximation of the value
Return type:float
__eq__(other)

Compare two rational numbers for equality.

Two rational numbers are equal if their reduced forms are equal.

Parameter:other (Rational) – the rational number to compare to self for equality
Returns:True if equal, False otherwise
Return type:boolean
class pyexiv2.utils.GPSCoordinate(degrees, minutes, seconds, direction)

A class representing GPS coordinates (e.g. a latitude or a longitude).

Its attributes (degrees, minutes, seconds, direction) are read-only properties.

degrees
The degrees component of the coordinate.
minutes
The minutes component of the coordinate.
seconds
The seconds component of the coordinate.
direction
The direction component of the coordinate.
static from_string(string)

Instantiate a GPSCoordinate from a string formatted as DDD,MM,SSk or DDD,MM.mmk where DDD is a number of degrees, MM is a number of minutes, SS is a number of seconds, mm is a fraction of minutes, and k is a single character N, S, E, W indicating a direction (north, south, east, west).

Parameter:string (string) – a string representation of a GPS coordinate
Returns:the GPS coordinate parsed
Return type:GPSCoordinate
Raises ValueError:
 if the format of the string is invalid
__eq__(other)

Compare two GPS coordinates for equality.

Two coordinates are equal if and only if all their components are equal.

Parameter:other (GPSCoordinate) – the GPS coordinate to compare to self for equality
Returns:True if equal, False otherwise
Return type:boolean
__str__()
Returns:a string representation of the GPS coordinate conforming to the XMP specification
Return type:string

Table Of Contents

Previous topic

Tutorial

Next topic

Developers

This Page