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={}, **kwargs)

append_array_item() 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. T 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.

:param schema_ns The namespace URI; see GetProperty(). :param array_name The name of the array. Can be a general path expression, must not be null or the empty string; see GetProperty() for namespace prefix usage. :param item_value The new item value, a null-terminated UTF-8 string, if the array item has a value. :param array_options An optional dictionary of keywords from XMP_PROP_OPTIONS describing the array type to create. :param **kwargs Optional keyword arguments describing the item type to create. :return True if the array item was appended correctly, False otherwise. :rtype bool

clone()

Create a new XMP packet from this one.

count_array_items(schema_ns, array_name)

count_array_items returns the number of a given array’s items

delete_property(schema_ns, prop_name)

delete_property() deletes an XMP subtree rooted at a given property. It is not an error if the property does not exist.

does_array_item_exist(schema_ns, array_name, item)

does_array_item_exist() reports whether an array’s item currently exists.

Returns:True if item is in array, False otherwise Return type:bool

does_property_exist(schema_ns, prop_name)

does_property_exist() reports whether a property currently exists.

:param schema_ns The namespace URI for the property; see get_property(). :param prop_name The name of the property; see get_property().

:return True if the property exists, False otherwise.

get_array_item(schema_ns, array_name, item_index)

get_array_item() provides access to items within an array.

Reports whether the item exists; if it does, and if it has a value, the function retrieves the value.; if it doesn’t it raises Exception. Items are accessed by an integer index, where the first item has index 1.

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, **kwargs)

get_localized_text() returns information about a selected item in an alt-text array.

:param schema_ns The namespace URI for the alt-text array. Has the same usage as in GetProperty. :param alt_text_name The name of the alt-text array. May be a general path expression, must not be null or the empty string. Has the same namespace prefix usage as propName in GetProperty. :param generic_lang 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. :param specific_lang The name of the specific language as an RFC 3066 tag. Must not be null or the empty string.

Returns:The property’s value if the property exists, None otherwise.

static get_namespace_for_prefix(prefix)

Checks if a prefix is registered. Parameters: prefix: the prefix to check.

Returns the associated namespace if registered, None if the prefix is not registered

static get_prefix_for_namespace(namespace)

Check if a namespace is registered.

Parameters: namespace: the namespace to check.

Returns the associated prefix if registered, None if the namespace is not registered

get_property(schema_ns, prop_name)

get_property() reports whether a property exists, and retrieves its value.

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

:param schema_ns 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. :param prop_name 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, None otherwise.

Todo

Make get_property optionally return keywords describing property’s options

get_property_bool(schema_ns, prop_name)

get_property_bool is just like get_property(), but it’s only to be used to get boolean properties.

:param schema_ns 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. :param prop_name 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.

:return The property’s value if the property exists, None otherwise.

Todo

Make get_property_bool optionally return keywords describing property’s options

get_property_datetime(schema_ns, prop_name)

get_property_date is just like get_property(), but it’s only to be used to get datetime properties. It returns a standart datetime.datetime instance.

:param schema_ns 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. :param prop_name 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. :return The property’s value if the property exists, None otherwise.

Todo

Make get_property_int optionally return keywords describing property’s options

Todo

Ad the tzInfo to the datetime.datetime object

get_property_float(schema_ns, prop_name)

get_property_float is just like get_property(), but it’s only to be used to get float properties.

:param schema_ns 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. :param prop_name 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. :return The property’s value if the property exists, None otherwise.

Todo

Make get_property_float optionally return keywords describing property’s options

get_property_int(schema_ns, prop_name)

get_property_int is just like get_property(), but it’s only to be used to get integer properties.

:param schema_ns 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. :param prop_name 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. :return The property’s value if the property exists, None otherwise.

Todo

Make get_property_int optionally return keywords describing property’s options

get_property_long(schema_ns, prop_name)

get_property_long is just like get_property(), but it’s only to be used to get long nteger properties.

:param schema_ns 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. :param prop_name 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. :return The property’s value if the property exists, None otherwise.

Todo

Make get_property_long 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 – String to parse.
• xmpmeta_wrap – Optional - If True, the string will be wrapped in an <x:xmpmeta> element.
• input_encoding – Optional - If xmp_packet_str is a 8-bit string, it will by default be assumed to be UTF-8 encoded.

Returns:

true if libxmp.core.XMPMeta object can be written in file.

Return type:

bool

static register_namespace(namespace_uri, suggested_prefix)

Register a new namespace to save properties to.

Parameters: namespace_uri: the new namespace’s URI suggested prefix: the suggested prefix: note that is NOT guaranteed it’ll be the actual namespace’s prefix

Returns the actual registered prefix for the namespace of None if the namespace wasn’t created.

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 – The number of bytes of padding, useful for modifying embedded XMP in place.
• newlinechr – The new line character to use.
• tabchr – The indentation character to use.
• indent – The initial indentation level.
• omit_packet_wrapper – Do not include an XML packet wrapper.
• read_only_packet – Create a read-only XML packet wapper.
• use_compact_format – Use a highly compact RDF syntax and layout.
• include_thumbnail_pad – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.
• exact_packet_length – The padding parameter provides the overall packet length.
• write_alias_comments – Include XML comments for aliases.
• omit_all_formatting – Omit all formatting whitespace.

Returns:

XMPMeta object serialized into a string as RDF.

Return type:

unicode string.

serialize_to_str(padding=0, **kwargs)

Serializes an XMPMeta object into a string (8-bit, UTF-8 encoded) as RDF and format.

Parameters:

• padding – The number of bytes of padding, useful for modifying embedded XMP in place.
• omit_packet_wrapper – Do not include an XML packet wrapper.
• read_only_packet – Create a read-only XML packet wapper.
• use_compact_format – Use a highly compact RDF syntax and layout.
• include_thumbnail_pad – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.
• exact_packet_length – The padding parameter provides the overall packet length.
• write_alias_comments – Include XML comments for aliases.
• omit_all_formatting – Omit all formatting whitespace.

Returns:

XMPMeta object serialized into a string as RDF.

Return type:

str 8-bit string in UTF-8 encoding (ready to e.g. be writtin 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 – The number of bytes of padding, useful for modifying embedded XMP in place.
• omit_packet_wrapper – Do not include an XML packet wrapper.
• read_only_packet – Create a read-only XML packet wapper.
• use_compact_format – Use a highly compact RDF syntax and layout.
• include_thumbnail_pad – Include typical space for a JPEG thumbnail in the padding if no xmp:Thumbnails property is present.
• exact_packet_length – The padding parameter provides the overall packet length.
• write_alias_comments – Include XML comments for aliases.
• omit_all_formatting – 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)

set_array_item() 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. T 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 – The namespace URI; see get_property().
• array_mame – The name of the array. Can be a general path expression, must not be null or the empty string; see get_property() for namespace prefix usage.
• item_index – The 1-based index of the desired item.
• item_value – The new item value, a string, if the array item has a 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.

:return True if the array item was set correctly, False otherwise. :rtype bool

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

set_localized_text() creates or sets a localized text value.

Parameters:

• schema_ns – The namespace URI; see get_property().
• alt_text_name – 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 – A valid generic language tag from RFC 3066 specification (i.e. en for English). Passing “x” for a generic language is allow, but considered poor practice. An empty string may be specified.
• specific_lang – A specific language tag from RFC 3066 specification (i.e en-US for US English).
• prop_value – Item value
• **kwargs –

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

:return True if the property was set correctly, False otherwise.

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

set_property() 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 – The namespace URI; see get_property().
• prop_name – 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.
• **kwargs –

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

:return True if the property was set correctly, False otherwise.

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

set_property_bool is just like set_property(), but it’s only to be used to set boolean properties

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

set_property_datetime is just like set_property(), but it’s only to be used to set datetime properties

Todo

Add tzInfo support

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

set_property_float is just like set_property(), but it’s only to be used to set float properties

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

set_property_int is just like set_property(), but it’s only to be used to set integer properties

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

set_property_long is just like set_property(), but it’s only to be used to set long integer properties

XMPIterator

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

XMPIterator provides a uniform means to iterate over the schema and properties within an XMP object. It’s implemented according to Python’s iterator protocol and it’s the iterator for XMPMeta class. :param xmp_obj : an XMPMeta instance :param schema_ns: Optional namespace URI to restrict the iteration. :param prop_name: Optional property name to restrict the iteration. :param **kwargs : Optional keyword arguments from XMP_ITERATOR_OPTIONS :returns: an iterator for the given xmp_obj

skip(**kwargs)

skip() 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)

Determines if a given libxmp.core.XMPMeta objet can be written in the file.

Parameters:xmp_obj – An libxmp.core.XMPMeta object Returns:true if libxmp.core.XMPMeta object can be written in 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 – 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

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.

Note, Exempi library is automatically initialized when loading libxmp and normally you will not need to call this method. However, there might be cases where

libxmp.utils.object_to_dict(xmp)

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

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.

Constants

libxmp.consts.XMP_NS_XMP

XMP Namespace

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

Internal function for creating the options bit mask to parse into 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 )