API documentation — pyexiv2 v0.3.2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- pyexiv2 v0.3.2 documentation »

# 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.

    Parameters: | 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.

    Parameters: | 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.

  `iptc_charset`

    An optional character set the IPTC data is encoded in.

  `xmp_keys`

    List of the keys of the available XMP tags.

  `__getitem__`(key)

    Get a metadata tag for a given key.

    Parameters: | 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.

    Parameters: | 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] `fractions.Fraction` if available (Python ≥ 2.6) or `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.

class `pyexiv2.exif.``ExifThumbnail`(_metadata)

  A thumbnail image optionally embedded in the IFD1 segment of the EXIF data.

  The image is either a TIFF or a JPEG image.

  `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`).

  `data`

    The raw thumbnail data. Setting it is restricted to a buffer in the JPEG format.

  `set_from_file`(path)

    Set the EXIF thumbnail to the JPEG image path. This sets only the `Compression`, `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` tags, which is not all the thumbnail EXIF information mandatory according to the EXIF standard (but it is enough to work with the thumbnail).

    Parameters: | path (string) – path to a JPEG file to set the thumbnail to

  `write_to_file`(path)

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

    Parameters: | path (string) – path to write the thumbnail to (without an extension)

  `erase`()

    Delete the thumbnail from the EXIF data. Removes all Exif.Thumbnail.*, i.e. Exif IFD1 tags.

## 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_value`

    The raw values of the tag as a list of strings.

  `value`

    The values of the tag as a list of python objects.

## pyexiv2.xmp

`pyexiv2.xmp.``register_namespace`(name, prefix)

  Register a custom XMP namespace.

  Overriding the prefix of a known or previously registered namespace is not allowed.

  Parameters: | name (string) – the name of the custom namespace (ending with a `/`), typically a URL (e.g. http://purl.org/dc/elements/1.1/) prefix (string) – the prefix for the custom namespace (keys in this namespace will be in the form `Xmp.{prefix}.{something}`)
  Raises: | ValueError – if the name doesn’t end with a `/` KeyError – if a namespace already exist with this prefix

`pyexiv2.xmp.``unregister_namespace`(name)

  Unregister a custom XMP namespace.

  A custom namespace is identified by its name, not by its prefix.

  Attempting to unregister an unknown namespace raises an error, as does attempting to unregister a builtin namespace.

  Parameters: | name (string) – the name of the custom namespace (ending with a `/`), typically a URL (e.g. http://purl.org/dc/elements/1.1/)
  Raises: | ValueError – if the name doesn’t end with a `/` KeyError – if the namespace is unknown or a builtin namespace

`pyexiv2.xmp.``unregister_namespaces`()

  Unregister all custom XMP namespaces.

  Builtin namespaces are not unregistered.

  This function always succeeds.

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: `fractions.Fraction` if available (Python ≥ 2.6) or `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.

    Parameters: | 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, separated by white spaces (e.g. “48 50 50 49” will be converted into “0221”). The Undefined type is part of the EXIF specification.

  Parameters: | 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 separated by white spaces (e.g. “0221” will be converted into “48 50 50 49”). The Undefined type is part of the EXIF specification.

  Parameters: | sequence (string) – a sequence of bytes
  Returns: | the corresponding undefined string
  Return type: | string

`pyexiv2.utils.``make_fraction`(*args)

  Make a fraction.

  The type of the returned object depends on the availability of the fractions module in the standard library (Python ≥ 2.6).

  Raises TypeError:
  | if the arguments do not match the expected format for a fraction

class `pyexiv2.utils.``Rational`(numerator, denominator)

  A class representing a rational number.

  Its numerator and denominator are read-only properties.

  Do not use this class directly to instantiate a rational number. Instead, use `make_fraction()`.

  `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`.

    Parameters: | 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.

    Parameters: | other (`Rational`) – the rational number to compare to self for equality
    Returns: | True if equal, False otherwise
    Return type: | boolean

  `__str__`()

    Returns: | a string representation of the rational number
    Return type: | string

  `__repr__`()

    Returns: | the official string representation of the object
    Return type: | string

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).

    Parameters: | 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.

    Parameters: | 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

### Navigation

- index
- modules |
- next |
- previous |
- pyexiv2 v0.3.2 documentation »