### Navigation

- index
- modules |
- next |
- previous |
- Python XMP Toolkit 2.0.1 documentation »

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

`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

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 )

### Navigation

- index
- modules |
- next |
- previous |
- Python XMP Toolkit 2.0.1 documentation »