Reference

XMP Toolkit

Exceptions

XMPError

exception libxmp.XMPError

General XMP Error.

ExempiLoadError

exception libxmp.ExempiLoadError

Error signaling that the Exempi library cannot be loaded.

Core Module

A module for parsing, manipulating, and serializing XMP data. The core module has no knowledge of files. The core API is provided by the XMPMeta and XMPIterator classes.

XMPMeta

class libxmp.core.XMPMeta(**kwargs)

XMPMeta is the class providing the core services of the library

append_array_item(schema_ns, array_name, item_value, array_options=None, **kwargs)

Adds an item to an array, creating the array if necessary.

This function simplifies construction of an array by not requiring that you pre-create an empty array. The array that is assigned is created automatically if it does not yet exist. If the array exists, it must have the form specified by the options. Each call appends a new item to the array.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • array_name (str) – The name of the array property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

  • item_value (str) – The new item value.

  • array_options (dict) – An optional dictionary of keywords from XMP_PROP_OPTIONS describing the array type to create.

  • **kwargs

    Optional keyword arguments describing the item type to create.

clone()

Create a new XMP packet from this one.

Returns

Copy of XMP packet.

Return type

XMPMeta

count_array_items(schema_ns, array_name)

count_array_items returns the number of a given array’s items

delete_localized_text(schema_ns, alt_text_name, generic_lang, specific_lang)

Remove a localized property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • alt_text_name (str) – The name of the alt-text array. May be a general path expression, must not be None or the empty string. Has the same namespace prefix usage as propName in GetProperty.

  • generic_lang (str) – The name of the generic language as an RFC 3066 primary subtag. May be null or the empty string if no generic language is wanted.

  • specific_lang (str) – The name of the specific language as an RFC 3066 tag. Must not be null or the empty string.

Raises

XMPError if operation fails.

delete_property(schema_ns, prop_name)

Delete a property from XMP packet.

Deletes an XMP subtree rooted at a given property. It is not an error if the property does not exist.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property; see get_property().

does_array_item_exist(schema_ns, array_name, item)

Reports whether an item exists in an array.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • array_name (str) – The name of the array; see get_property().

  • item (str) – The name of the item.

Returns

True if item is in array, False otherwise

Return type

bool

does_property_exist(schema_ns, prop_name)

Queries for existence of a property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property; see get_property().

Returns

True if the property exists, False otherwise.

get_array_item(schema_ns, array_prop_name, index)

Get an item from an array property.

Items are accessed by an integer index

Parameters
  • schema_ns (str) – The namespace URI for the property; can be null or the empty string if the first component of the prop_name path contains a namespace prefix.

  • array_prop_name (str) – The name of the array property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

  • index (int) – The 1-based index of the item.

Raises

IOError if exempi library routine fails.

Todo

Make get_array_item optionally return keywords describing array item’s options

get_localized_text(schema_ns, alt_text_name, generic_lang, specific_lang)

Returns information about a selected item in an alt-text array.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • alt_text_name (str) – The name of the alt-text array. May be a general path expression, must not be None or the empty string. Has the same namespace prefix usage as propName in GetProperty.

  • generic_lang (str) – The name of the generic language as an RFC 3066 primary subtag. May be None or the empty string if no generic language is wanted.

  • specific_lang (str) – The name of the specific language as an RFC 3066 tag. Must not be null or the empty string.

Raises

IOError if operation fails.

Returns

The property’s value.

static get_namespace_for_prefix(prefix)

Checks if a prefix is registered.

Parameters

prefix (str) – The prefix to check.

Returns

The associated namespace if registered.

Raises

IOError if exempi library routine fails.

static get_prefix_for_namespace(namespace)

Check if a namespace is registered.

Parameters: :param str namespace: the namespace to check. :returns: the associated prefix if registered :raises: IOError if exempi library routine fails.

get_property(schema_ns, prop_name)

Retrieves property value.

This is the simplest property accessor: use this to retrieve the values of top-level simple properties.

Parameters
  • schema_ns (str) – The namespace URI for the property; can be null or the empty string if the first component of the prop_name path contains a namespace prefix.

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Returns

The property’s value if the property exists.

Raises

IOError if exempi library routine fails.

Todo

Make get_property optionally return keywords describing property’s options

get_property_bool(schema, name)

Retrieve a boolean property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • array_name (str) – The name of the array property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Raises

IOError if operation fails.

Returns

The boolean property value.

Todo

Make get_property_bool optionally return keywords describing property’s options

get_property_datetime(schema_ns, prop_name)

Retrieve a datetime property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Returns

datetime.datetime instance.

Raises

IOError if operation fails.

get_property_float(schema_ns, prop_name)

Return a property value as floating point.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Raises

IOError if operation fails.

Returns

The floating point property value.

Todo

Make get_property_float optionally return keywords describing property’s options

get_property_int(schema_ns, name)

Retrieve an integer property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Raises

IOError if operation fails.

Returns

The integer property value.

Todo

Make get_property_int optionally return keywords describing property’s options

get_property_long(schema_ns, prop_name)

Retrieve a long (int64) property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

Raises

IOError if operation fails.

Returns

The 64-bit integer property value.

Todo

Make get_property_int optionally return keywords describing property’s options

parse_from_str(xmp_packet_str, xmpmeta_wrap=False, input_encoding=None)

Parses RDF from a string into a XMP object.

The input for parsing may be any valid Unicode encoding. ISO Latin-1 is also recognized, but its use is strongly discouraged.

Note RDF string must contain an outermost <x:xmpmeta> object.

Parameters
  • xmp_packet_str (str) – String to parse.

  • xmpmeta_wrap (bool) – Optional - If True, the string will be wrapped in an <x:xmpmeta> element.

  • input_encoding (str) – Optional - If xmp_packet_str is a 8-bit string, it will by default be assumed to be UTF-8 encoded.

Raises

IOError if operation fails.

static register_namespace(namespace_uri, suggested_prefix)

Register a new namespace.

Parameters
  • namespace_uri (str) – the new namespace’s URI

  • suggested prefix (str) – the suggested prefix: note that is NOT guaranteed it’ll be the actual namespace’s prefix

Returns

the actual registered prefix for the namespace

serialize_and_format(padding=0, newlinechr='\n', tabchr='\t', indent=0, **kwargs)

Serializes an XMPMeta object into a string as RDF.

Note, normally it is sufficient to use either serialize_to_str or serialize_to_unicode unless you need high degree of control over the serialization.

The specified parameters must be logically consistent, an exception is raised if not. You cannot specify both omit_packet_wrapper along with read_only_packet, include_thumbnail_pad, or exact_packet_length.

Parameters
  • padding (int) – The number of bytes of padding, useful for modifying embedded XMP in place.

  • newlinechr (str) – The new line character to use.

  • tabchr (str) – The indentation character to use.

  • indent (int) – The initial indentation level.

  • omit_packet_wrapper (bool) – Do not include an XML packet wrapper.

  • read_only_packet (bool) – Create a read-only XML packet wapper.

  • use_compact_format (bool) – Use a highly compact RDF syntax and layout.

  • include_thumbnail_pad (bool) – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.

  • exact_packet_length (bool) – The padding parameter provides the overall packet length.

  • write_alias_comments (bool) – Include XML comments for aliases.

  • omit_all_formatting (bool) – Omit all formatting whitespace.

Returns

XMPMeta object serialized into a string as RDF.

Return type

utf-8 string.

serialize_to_str(padding=0, **kwargs)

Serialize into a string (8-bit, UTF-8 encoded) as RDF and format.

Parameters
  • padding (int) – The number of bytes of padding, useful for modifying embedded XMP in place.

  • omit_packet_wrapper (bool) – Do not include an XML packet wrapper.

  • read_only_packet (bool) – Create a read-only XML packet wapper.

  • use_compact_format (bool) – Use a highly compact RDF syntax and layout.

  • include_thumbnail_pad (bool) – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.

  • exact_packet_length (int) – The padding parameter provides the overall packet length.

  • write_alias_comments (bool) – Include XML comments for aliases.

  • omit_all_formatting (bool) – Omit all formatting whitespace.

Returns

str 8-bit string in UTF-8 encoding (ready to be written to a file).

serialize_to_unicode(**kwargs)

Serializes an XMPMeta object into a Unicode string as RDF and format. Note, this is wrapper around serialize_to_str.

The specified parameters must be logically consistent, an exception is raised if not. You cannot specify both omit_packet_wrapper along with read_only_packet, include_thumbnail_pad, or exact_packet_length.

Parameters
  • padding (int) – The number of bytes of padding, useful for modifying embedded XMP in place.

  • omit_packet_wrapper (bool) – Do not include an XML packet wrapper.

  • read_only_packet (bool) – Create a read-only XML packet wapper.

  • use_compact_format (bool) – Use a highly compact RDF syntax and layout.

  • include_thumbnail_pad (bool) – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.

  • exact_packet_length (bool) – The padding parameter provides the overall packet length.

  • write_alias_comments (bool) – Include XML comments for aliases.

  • omit_all_formatting (bool) – Omit all formatting whitespace.

Returns

XMPMeta object serialized into a string as RDF.

Return type

unicode string.

set_array_item(schema_ns, array_name, item_index, item_value, **kwargs)

Creates or sets the value of an item within an array.

Items are accessed by an integer index, where the first item has index 1. This function creates the item if necessary, but the array itself must already exist: use append_array_item() to create arrays. A new item is automatically appended if the index is the array size plus 1; to insert a new item before or after an existing item, use kwargs.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • array_name (str) – The name of the array property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix; if present without a schema_ns value, the prefix specifies the namespace.

  • item_index (int) – The 1-based index of the desired item.

  • item_value – The new item value.

  • **kwargs

    Optional keywork arguments describing the array type and insertion location for a new item. The type, if specified, must match the existing array type, prop_array_is_ordered, prop_array_is_alternate, or prop_array_is_alt_text. Default (no keyword parameters) matches the existing array type.

Raises

IOError if exempi library routine fails.

set_localized_text(schema_ns, alt_text_name, generic_lang, specific_lang, prop_value, **kwargs)

Creates or sets a localized text value.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • alt_text_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string. The first component can be a namespace prefix.

  • generic_lang (str) – A valid generic language tag from RFC 3066 specification (i.e. en for English). Passing “x” for a generic language is allowed, but considered poor practice. An empty string may be specified.

  • specific_lang (str) – A specific language tag from RFC 3066 specification (i.e en-US for US English).

  • prop_value (str) – Item value

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

set_property(schema_ns, prop_name, prop_value, **kwargs)

Creates or sets a property value.

The method takes optional keyword aguments that describe the property. You can use these functions to create empty arrays and structs by setting appropriate option flags. When you assign a value, all levels of a struct that are implicit in the assignment are created if necessary; append_array_item() implicitly creates the named array if necessary.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (str) – The new item value.

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

set_property_bool(schema_ns, prop_name, prop_value, **kwargs)

Set a boolean property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (bool) – The new item value.

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

set_property_datetime(schema_ns, prop_name, prop_value, **kwargs)

Set a datetime property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (datetime.datetime) – The new datetime value.

Raises

IOError if exempi library routine fails.

set_property_float(schema_ns, prop_name, prop_value, **kwargs)

Set a floating point property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (float) – The new item value.

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

set_property_int(schema_ns, prop_name, prop_value, **kwargs)

Set an integer property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (int) – The new item value.

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

set_property_long(schema_ns, prop_name, prop_value, **kwargs)

Set a long integer (int64) property.

Parameters
  • schema_ns (str) – The namespace URI; see get_property().

  • prop_name (str) – The name of the property. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.

  • prop_value (long) – The new item value.

  • **kwargs

    Optional keyword arguments describing the options; must much an already existing option from consts.XMP_PROP_OPTIONS

Raises

IOError if exempi library routine fails.

XMPIterator

class libxmp.core.XMPIterator(xmp_obj, schema_ns=None, prop_name=None, **kwargs)

Provides means to iterate over a schema and properties.

XMPIterator provides a uniform means to iterate over the schema and properties within an XMP object. It is implemented according to Python’s iterator protocol and it is the iterator for XMPMeta class.

Parameters
  • xmp_obj (obj) – an XMPMeta instance

  • schema_ns (str) – Optional namespace URI to restrict the iteration.

  • prop_name (str) – Optional property name to restrict the iteration.

  • **kwargs

    Optional keyword arguments from XMP_ITERATOR_OPTIONS

Returns

an iterator for the given xmp_obj

next()

Implements iterator protocol for 2.X

Todo

Suppress this in sphinx docs

Raises

StopIteration

skip(**kwargs)

Skips some portion of the remaining iterations.

Parameters

**kwargs

Optional keyword parameters from XMP_SKIP_OPTIONS to control the iteration

Returns

None

Return type

NoneType

Files Module

The Files module provides support for locating the XMP in a file, adding XMP to a file, or updating the XMP in a file. It returns the entire XMP packet, the core pacakage can then be used to manipulate the individual XMP properties. XMPFiles contains a number of “smart” file handlers that know how to efficiently access the XMP in specific file formats. It also includes a fallback packet scanner that can be used for unknown file formats.

XMPFiles

class libxmp.files.XMPFiles(**kwargs)

API for access to the “main” metadata in a file.

XMPFiles provides the API for the Exempi’s File Handler component. This provides convenient access to the main, or document level, XMP for a file. The general model is to open a file, read and write the metadata, then close the file. While open, portions of the file might be maintained in RAM data structures. Memory usage can vary considerably depending on file format and access options. The file may be opened for read-only or read-write access, with typical exclusion for both modes.

Errors result in raising of an libxmp.XMPError exception.

Parameters

file_path – Path to file to open.

Todo

Documentation

can_put_xmp(xmp_obj)

Determine if XMP can be written into the file.

Determines if a given libxmp.core.XMPMeta object can be written into the file.

Parameters

xmp_obj – An libxmp.core.XMPMeta object

Returns

true if libxmp.core.XMPMeta object writeable to file.

Return type

bool

close_file(close_flags=0)

Close file after use. XMP will not be written to file until this method has been called.

Parameters

close_flags – One of the close flags

Raises

XMPError – in case of errors.

Todo

Change signature into using kwargs to set option flag

get_xmp()

Get XMP from file.

Returns

A new libxmp.core.XMPMeta instance.

Raises

XMPError – in case of errors.

open_file(file_path, **kwargs)

Open a given file and read XMP from file. File must be closed again with close_file()

Parameters

file_path (str) – Path to file to open.

Raises

XMPError – in case of errors.

Todo

Change signature into using kwargs to set option flag

put_xmp(xmp_obj)

Write XMPMeta object to file. See also can_put_xmp().

Parameters

xmp_obj – An libxmp.core.XMPMeta object

Utils Module

Helper utilities.

libxmp.utils.file_to_dict(file_path)

Extracts all XMP data from a given file organizing it into a standard Python dictionary.

Parameters

file_path – Path to file to open.

Returns

An empty dictionary if there’s no valid XMP in the file passed as an argument.

libxmp.utils.object_to_dict(xmp)

Extracts all XMP data from a given XMPMeta instance organizing it into a standard Python dictionary.

libxmp.utils.terminate()

Terminate usage of library.

Normally function should not be called. Cases however might exists where memory clean-up is needed, then this method may be called.

Warning

After this function have been called, any call to methods in libxmp will result in a crash of Python.

Constants

Constants from exempi headers.

libxmp.consts.options_mask(xmp_options, **kwargs)

Creates the options bit mask for consumption by exempi C functions.

Example:

opt = consts.options_mask( consts.XMP_SERIAL_OPTIONS, **kwargs )

or:

opt = consts.options_mask( consts.XMP_SERIAL_OPTIONS, omit_packet_wrapper=True )