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 is the class providing the core services of the library
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
Create a new XMP packet from this one.
count_array_items returns the number of a given array’s items
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() reports whether an array’s item currently exists.
Returns: | True if item is in array, False otherwise |
---|---|
Return type: | bool |
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() 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() 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. |
---|
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
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() 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 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_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 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 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 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
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: |
|
---|---|
Returns: | true if libxmp.core.XMPMeta object can be written in file. |
Return type: | bool |
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.
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: |
|
---|---|
Returns: | XMPMeta object serialized into a string as RDF. |
Return type: | unicode string. |
Serializes an XMPMeta object into a string (8-bit, UTF-8 encoded) as RDF and format.
Parameters: |
|
---|---|
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). |
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: |
|
---|---|
Returns: | XMPMeta object serialized into a string as RDF. |
Return type: | unicode string. |
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: |
|
---|
:return True if the array item was set correctly, False otherwise. :rtype bool
set_localized_text() creates or sets a localized text value.
Parameters: |
|
---|
:return True if the property was set correctly, False otherwise.
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: |
|
---|
:return True if the property was set correctly, False otherwise.
set_property_bool is just like set_property(), but it’s only to be used to set boolean properties
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 is just like set_property(), but it’s only to be used to set float properties
set_property_int is just like set_property(), but it’s only to be used to set integer properties
set_property_long is just like set_property(), but it’s only to be used to set long integer properties
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() 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 |
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.
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
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 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 from file.
Returns: | A new libxmp.core.XMPMeta instance. |
---|---|
Raises XMPError: | |
in case of errors. |
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
Write XMPMeta object to file. See also can_put_xmp().
Parameters: | xmp_obj – An libxmp.core.XMPMeta object |
---|
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
Extracts all XMP data from a given XMPMeta instance organizing it into a standard Python dictionary.
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. |
XMP Namespace
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 )