Tutorial

This tutorial is meant to give you a quick overview of what py3exiv2 allows you to do. You can just read it through or follow it interactively, in which case you will need to have py3exiv2 installed. It doesn’t cover all the possibilities offered by py3exiv2, only a basic subset of them. For complete reference, see the API documentation.

Let’s get started!

Remember, the lib is named py3exiv2 but the top-level module, for compatibility reasons, is named pyexiv2. So, we import the pyexiv2 module:

>>> import pyexiv2

We then load an image file and read its metadata:

>>> metadata = pyexiv2.ImageMetadata('test.jpg')
>>> metadata.read()

Reading and writing EXIF tags

Let’s retrieve a list of all the available EXIF tags available in the image:

>>> metadata.exif_keys
['Exif.Image.ImageDescription',
 'Exif.Image.XResolution',
 'Exif.Image.YResolution',
 'Exif.Image.ResolutionUnit',
 'Exif.Image.Software',
 'Exif.Image.DateTime',
 'Exif.Image.Artist',
 'Exif.Image.Copyright',
 'Exif.Image.ExifTag',
 'Exif.Photo.Flash',
 'Exif.Photo.PixelXDimension',
 'Exif.Photo.PixelYDimension']

Each of those tags can be accessed with the [] operator on the metadata, much like a python dictionary:

>>> tag = metadata['Exif.Image.DateTime']

The value of an ExifTag object can be accessed in two different ways: with the raw_value and with the value attributes:

>>> tag.raw_value
'2004-07-13T21:23:44Z'

>>> tag.value
datetime.datetime(2004, 7, 13, 21, 23, 44)

The raw value is always a byte string, this is how the value is stored in the file. The value is lazily computed from the raw value depending on the EXIF type of the tag, and is represented as a convenient python object to allow easy manipulation.

Note that querying the value of a tag may raise an ExifValueError if the format of the raw value is invalid according to the EXIF specification (may happen if it was written by other software that implements the specification in a broken manner), or if pyexiv2 doesn’t know how to convert it to a convenient python object.

Accessing the value of a tag as a python object allows easy manipulation and formatting:

>>> tag.value.strftime('%A %d %B %Y, %H:%M:%S')
'Tuesday 13 July 2004, 21:23:44'

Now let’s modify the value of the tag and write it back to the file:

>>> import datetime
>>> tag.value = datetime.datetime.today()

>>> metadata.write()

Similarly to reading the value of a tag, one can set either the raw_value or the value (which will be automatically converted to a correctly formatted byte string by pyexiv2).

You can also add new tags to the metadata by providing a valid key and value pair (see exiv2’s documentation for a list of valid EXIF tags):

>>> key = 'Exif.Photo.UserComment'
>>> value = 'This is a useful comment.'
>>> metadata[key] = pyexiv2.ExifTag(key, value)

As a handy shortcut, you can always assign a value for a given key regardless of whether it’s already present in the metadata. If a tag was present, its value is overwritten. If the tag was not present, one is created and its value is set:

>>> metadata[key] = value

The EXIF data may optionally embed a thumbnail in the JPEG or TIFF format. The thumbnail can be accessed, set from a JPEG file or buffer, saved to disk and erased:

>>> thumb = metadata.exif_thumbnail
>>> thumb.set_from_file('/tmp/thumbnail.jpg')
>>> thumb.write_to_file('/tmp/copy')
>>> thumb.erase()
>>> metadata.write()

Reading and writing IPTC tags

Reading and writing IPTC tags works pretty much the same way as with EXIF tags. Let’s retrieve the list of all available IPTC tags in the image:

>>> metadata.iptc_keys
['Iptc.Application2.Caption',
 'Iptc.Application2.Writer',
 'Iptc.Application2.Byline',
 'Iptc.Application2.ObjectName',
 'Iptc.Application2.DateCreated',
 'Iptc.Application2.City',
 'Iptc.Application2.ProvinceState',
 'Iptc.Application2.CountryName',
 'Iptc.Application2.Category',
 'Iptc.Application2.Keywords',
 'Iptc.Application2.Copyright']

Each of those tags can be accessed with the [] operator on the metadata:

>>> tag = metadata['Iptc.Application2.DateCreated']

An IPTC tag always has a list of values rather than a single value. This is because some tags have a repeatable character. Tags that are not repeatable only hold one value in their list of values.

Check the repeatable attribute to know whether a tag can hold more than one value:

>>> tag.repeatable
False

As with EXIF tags, the values of an IptcTag object can be accessed in two different ways: with the raw_value and with the value attributes:

>>> tag.raw_value
['2004-07-13']

>>> tag.value
[datetime.date(2004, 7, 13)]

Note that querying the values of a tag may raise an IptcValueError if the format of the raw values is invalid according to the IPTC specification (may happen if it was written by other software that implements the specification in a broken manner), or if pyexiv2 doesn’t know how to convert it to a convenient python object.

Now let’s modify the values of the tag and write it back to the file:

>>> tag.value = [datetime.date.today()]

>>> metadata.write()

Similarly to reading the values of a tag, one can set either the raw_value or the value (which will be automatically converted to correctly formatted byte strings by pyexiv2).

You can also add new tags to the metadata by providing a valid key and values pair (see exiv2’s documentation for a list of valid IPTC tags):

>>> key = 'Iptc.Application2.Contact'
>>> values = ['John', 'Paul', 'Ringo', 'George']
>>> metadata[key] = pyexiv2.IptcTag(key, values)

As a handy shortcut, you can always assign values for a given key regardless of whether it’s already present in the metadata. If a tag was present, its values are overwritten. If the tag was not present, one is created and its values are set:

>>> metadata[key] = values

The IPTC metadata in an image may embed an optional character set for its encoding. This is defined by the Iptc.Envelope.CharacterSet tag. The ImageMetadata class has an iptc_charset property that allows to easily get, set and delete this value:

>>> metadata.iptc_charset
'ascii'

>>> metadata.iptc_charset = 'utf-8'

>>> del metadata.iptc_charset

Note that at the moment, the only supported charset that can be assigned to the property is utf-8. Also note that even if the charset is not explicitly set, its value may be inferred from the contents of the image. If not, it will be None.

Reading and writing XMP tags

Reading and writing XMP tags works pretty much the same way as with EXIF tags. Let’s retrieve the list of all available XMP tags in the image:

>>> metadata.xmp_keys
['Xmp.dc.creator',
 'Xmp.dc.description',
 'Xmp.dc.rights',
 'Xmp.dc.source',
 'Xmp.dc.subject',
 'Xmp.dc.title',
 'Xmp.xmp.CreateDate',
 'Xmp.xmp.ModifyDate']

Each of those tags can be accessed with the [] operator on the metadata:

>>> tag = metadata['Xmp.xmp.ModifyDate']

As with EXIF tags, the value of an XmpTag object can be accessed in two different ways: with the raw_value and with the value attributes:

>>> tag.raw_value
'2002-07-19T13:28:10'

>>> tag.value
datetime.datetime(2002, 7, 19, 13, 28, 10)

Note that querying the value of a tag may raise an XmpValueError if the format of the raw value is invalid according to the XMP specification (may happen if it was written by other software that implements the specification in a broken manner), or if pyexiv2 doesn’t know how to convert it to a convenient python object.

Now let’s modify the value of the tag and write it back to the file:

>>> tag.value = datetime.datetime.today()

>>> metadata.write()

Similarly to reading the value of a tag, one can set either the raw_value or the value (which will be automatically converted to a correctly formatted byte string by pyexiv2).

You can also add new tags to the metadata by providing a valid key and value pair (see exiv2’s documentation for a list of valid XMP tags):

>>> key = 'Xmp.xmp.Label'
>>> value = 'A beautiful picture.'
>>> metadata[key] = pyexiv2.XmpTag(key, value)

As a handy shortcut, you can always assign a value for a given key regardless of whether it’s already present in the metadata. If a tag was present, its value is overwritten. If the tag was not present, one is created and its value is set:

>>> metadata[key] = value

Accessing to the tags of type XmpSeq <Property>Detail. Example with Xmp.plus.Licensor wich is type XmpSeq LicensorDetail:

>>> base = "Xmp.plus.Licensor"
>>> # Always chek if the tag already exists
>>> try:
>>>     seq = data[base]
>>> except KeyError:
>>>     # Tag not set, create one. Note the value [""]
>>>     tag = pyexiv2.xmp.XmpTag(base, [""])
>>>     data[base] = tag
>>> key = "".join([base, "[1]/plus:LicensorID"])
>>> datum = pyexiv2.xmp.XmpTag(key, "https://iptc.org")
>>> data[key] = datum
>>> key = "".join([base, "[1]/plus:LicensorName"])
>>> datum = pyexiv2.xmp.XmpTag(key, "John Doe")
>>> data[key] = datum
>>> key = "".join([base, "[1]/plus:LicensorCountry"])
>>> datum = pyexiv2.xmp.XmpTag(key, "USA")
>>> data[key] = datum
>>> key = "".join([base, "[1]/plus:LicensorCity"])
>>> datum = pyexiv2.xmp.XmpTag(key, "Washington")
>>> data[key] = datum

If you need to write custom metadata, you can register a custom XMP namespace:

>>> pyexiv2.xmp.register_namespace('http://example.org/foo/', 'foo')
>>> metadata['Xmp.foo.bar'] = 'baz'

Note that a limitation of the current implementation is that only simple text values can be written to tags in a custom namespace.

A custom namespace can be unregistered. This has the effect of invalidating all tags in this namespace for images that have not been written back yet:

>>> pyexiv2.xmp.unregister_namespace('http://example.org/foo/')

Accessing embedded previews

Images may embed previews (also called thumbnails) of various sizes in their metadata. pyexiv2 allows to easily access them:

>>> previews = metadata.previews

>>> len(previews)
2

They are sorted by increasing size. Let’s play with the largest one:

>>> largest = previews[-1]

>>> largest.dimensions
(320, 240)

>>> largest.mime_type
'image/jpeg'

>>> largest.write_to_file('largest')