Reference¶
XMP Toolkit¶
Exceptions¶
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.
-
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 )