Reference — Python XMP Toolkit v1.0b3 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Python XMP Toolkit v1.0b3 documentation »

# 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)

### Navigation

- index
- modules |
- next |
- previous |
- Python XMP Toolkit v1.0b3 documentation »