Reference

AVM Toolkit

Exceptions

exception libavm.exceptions.AVMListLengthError

Raised when a list is not the correct length

exception libavm.exceptions.AVMItemNotInControlledVocabularyError

Raise when an string is not in a required controlled vocabulary

Core Module

A module for parsing, manipulating, and serializing AVM data in the XMP format.

AVMMeta

class libavm.core.AVMMeta(avm_dict=None, xmp=None, version='1.1')

AVMMeta is a class offering direct access and validation of AVM metadata. An AVM dictionary or XMPMeta object may be passed to the constructor. Priority will be given to the AVM dictionary.

Parameters:
  • avm_dict – Python dictionary containing AVM
  • xmp – XMPMeta object
  • version – AVM version, default to the current (1.1)
to_string(key)

Method to decompress data to a SQL-friendly string.

Returns:String (UTF-8)

Utils Module

libavm.utils.avm_from_file(file_path)

Function to retrieve the XMP packet from a file

Parameters:file_path – Path to file
Returns:A dictionary with AVM data
libavm.utils.avm_obj_from_file(file_path)

Function to retrieve the XMP packet from a file

Parameters:file_path – Path to file
Returns:A dictionary with AVM data
libavm.utils.avm_to_file(file_path, dict={}, replace=False)

Function to inject AVM into a file. Preserves existing XMP in the file, while replacing fields passed through dict.

If a field is an unordered list, then data is appended to existing values

Parameters:
  • file_path – Path to file
  • dict – A dictionary containing AVM metadata
  • xmp – An XMPMeta instance
  • replace – Boolean to replace the exisiting XMP in the file. By default it is set to False.
Returns:

Boolean

Todo

Improve avm_to_file function. Add ability to input an XMP file

Data Types

Definition of various AVM specific data types

AVMData

class libavm.datatypes.AVMData(ns, path, deprecated=False, **kwargs)

Abstract AVM data class. All other data classes inherit from AVMData.

check_data(value)

All other data classes should define check_data() based on the type of data. Encoding of string into UTF-8 happens here.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMString

class libavm.datatypes.AVMString(ns, path, deprecated=False, **kwargs)

Data type for strings

check_data(value)

Check that the data is a string or unicode, otherwise it raises a TypeError.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMStringCV

class libavm.datatypes.AVMStringCV(ns, path, cv, **kwargs)
check_cv(value)

If a controlled vocabulary is specified, this function checks the input value against the allowed values. AVMItemNotInControlledVocabularyError is raised if not in the controlled vocabulary

Returns:Boolean
check_data(value)

Check that the data is a string or unicode, formats the data appropriately using format_data() and calls check_cv()

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

format_data(value)
Returns:String
get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMStringCVCapitalize

class libavm.datatypes.AVMStringCVCapitalize(ns, path, cv, **kwargs)
check_cv(value)

If a controlled vocabulary is specified, this function checks the input value against the allowed values. AVMItemNotInControlledVocabularyError is raised if not in the controlled vocabulary

Returns:Boolean
check_data(value)

Check that the data is a string or unicode, formats the data appropriately using format_data() and calls check_cv()

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

format_data(value)

Formats the data to be a capitalized string

Returns:String
get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMStringCVUpper

class libavm.datatypes.AVMStringCVUpper(ns, path, cv, **kwargs)
check_cv(value)

If a controlled vocabulary is specified, this function checks the input value against the allowed values. AVMItemNotInControlledVocabularyError is raised if not in the controlled vocabulary

Returns:Boolean
check_data(value)

Check that the data is a string or unicode, formats the data appropriately using format_data() and calls check_cv()

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

format_data(value)

Formats the data to be an upper case string

Returns:String:
get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMURL

class libavm.datatypes.AVMURL(ns, path, deprecated=False, **kwargs)

Data type for URLs.

Returns:String (UTF-8)
check_data(value)

Checks the data is a string or unicode, and checks data against a regular expression for a URL. If the user leaves off the protocol,then ‘http://‘ is attached as a default.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMEmail

class libavm.datatypes.AVMEmail(ns, path, deprecated=False, **kwargs)

Data type for email addresses.

Returns:String (UTF-8)
check_data(value)

Checks data is a string or unicode, and checks against a regular expression for an email. If value is not a string or unicode, a TypeError is raised. If the value is not a proper email, then a ValueError is raised.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMLocalizedString

class libavm.datatypes.AVMLocalizedString(ns, path, **kwargs)

Data type for localized strings. (i.e. fields contained in an alt tag, such as dc:description)

check_data(value)

Check that the data is a string or unicode, otherwise it raises a TypeError.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves localized data from an XMP packet.

Returns:String
set_data(xmp_packet, value)

After calling check_data(), injects the data into the XMP packet.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMFloat

class libavm.datatypes.AVMFloat(ns, path, deprecated=False, **kwargs)

Data type for float fields

check_data(value)

Checks that data can be represented as a number.

Returns:String (UTF-8)
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Retrieves data from an XMP packet. Should be overridden when appropriate.

Returns:Object. Depending on the data type, different objects will be returned. If the data does not exist

in the xmp packet, then the None object is returned

set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMUnorderedList

class libavm.datatypes.AVMUnorderedList(ns, path, **kwargs)

Generic data type for lists (i.e xmp bag arrays)

check_data(values)

Checks that the data type is a Python List. Calls check_length() first.

Todo

Redo this function. Implement the dash functionality only for ordered lists.

Returns:List (UTF-8 elements)
check_length(values)

Checks the length of the Python List.

Returns:Boolean
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Extract data from XMP packet

Returns:List (UTF-8 elements) or None if array does not have any elements
set_data(xmp_packet, values)

After checking length and type, inject the data to the XMP packet. This function replaces the existing data; it is not meant to append values.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMUnorderedStringList

class libavm.datatypes.AVMUnorderedStringList(ns, path, **kwargs)

Data type for an unordered list of strings

check_data(values)

Check that the passed data is a Python List, and checks that the elements are strings or unicode.

Returns:List of strings (UTF-8)
check_length(values)

Checks the length of the Python List.

Returns:Boolean
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Extract data from XMP packet

Returns:List (UTF-8 elements) or None if array does not have any elements
set_data(xmp_packet, values)

After checking length and type, inject the data to the XMP packet. This function replaces the existing data; it is not meant to append values.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMOrderedList

class libavm.datatypes.AVMOrderedList(ns, path, **kwargs)

Data type for ordered lists (i.e. seq arrays)

check_data(values)

Checks that the data type is a Python List. Calls check_length() first.

Todo

Redo this function. Implement the dash functionality only for ordered lists.

Returns:List (UTF-8 elements)
check_length(values)

Checks the length of the Python List.

Returns:Boolean
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Extract data from XMP packet

Returns:List (UTF-8 elements) or None if array does not have any elements
set_data(xmp_packet, values)

Checks the data before injecting to the XMP packets.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMOrderedStringList

AVMOrderedStringListCV

AVMOrderedFloatList

class libavm.datatypes.AVMOrderedFloatList(ns, path, **kwargs)

Data type for ordered lists of floats.

check_data(values)

Checks that the data is of the correct type, length and elements are strings able to be represented as floats.

Returns:List of strings (UTF-8)
check_length(values)

Checks the length of the Python List.

Returns:Boolean
delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

Extract data from XMP packet

Returns:List (UTF-8 elements) or None if array does not have any elements
set_data(xmp_packet, values)

Checks the data before injecting to the XMP packets.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)

AVMDate

class libavm.datatypes.AVMDate(ns, path, deprecated=False, **kwargs)

Data type for Dates.

check_data(value)

Checks for a Python date

Todo

Implement a better way to determine class.

delete_data(xmp_packet)

Deletes data from an XMP packet. Should be overridden when appropriate.

get_data(xmp_packet)

.todo:: Something funny happens here...

Returns:Python date object
set_data(xmp_packet, value)

Injects data into an XMP packet. Should be overridden if other requirements are necessary.

Returns:Boolean
to_string(xmp_packet)

Method to retrieve data from an XMP packet in a SQL-friendly string format.

Returns:String (UTF-8)