exiv2._iptc

IPTC metadatum, container and iterators.

Classes

IptcData	A container for IPTC data.
IptcData_iterator	Python wrapper for an IptcData iterator.
IptcData_iterator_base	Python wrapper for an IptcData iterator that points to the 'end' value and can not be dereferenced.
Iptcdatum	An IPTC metadatum ("dataset"), consisting of an IptcKey and a Value and methods to manipulate these.

class IptcData

Bases: SwigPyObject

A container for IPTC data. This is a top-level class of the Exiv2 library.

Provide high-level access to the IPTC data of an image: - read IPTC information from JPEG files - access metadata through keys and standard C++ iterators - add, modify and delete metadata - write IPTC data to JPEG files - extract IPTC metadata to files, insert from these files

add()

Overload 1:

Add an Iptcdatum from the supplied key and value pair. This method copies (clones) the value. A check for non-repeatable datasets is performed.

Return type:

int

Returns:

0 if successful;

6 if the dataset already exists and is not repeatable

Overload 2:

Add a copy of the Iptcdatum to the IPTC metadata. A check for non-repeatable datasets is performed.

Return type:

int

Returns:

0 if successful;

6 if the dataset already exists and is not repeatable;

begin()

Begin of the metadata

clear()

Delete all Iptcdatum instances resulting in an empty container.

count()

Get the number of metadata entries

detectCharset()

Return the metadata charset name or 0

empty()

Return true if there is no IPTC metadata

end()

End of the metadata

erase()

Delete the Iptcdatum at iterator position pos, return the position of the next Iptcdatum. Note that iterators into the metadata, including pos, are potentially invalidated by this call.

findId()

Find the first Iptcdatum with the given record and dataset it, return a const iterator to it.

findKey()

Find the first Iptcdatum with the given key, return an iterator to it.

size()

Return the exact size of all contained IPTC metadata

sortByKey()

Sort metadata by key

sortByTag()

Sort metadata by tag (aka dataset)

class IptcData_iterator

Bases: IptcData_iterator_base

Python wrapper for an IptcData iterator. It has most of the methods of Iptcdatum allowing easy access to the data it points to.

copy()

See Iptcdatum.copy().

count()

See Iptcdatum.count().

familyName()

See Iptcdatum.familyName().

getValue()

See Iptcdatum.getValue().

groupName()

See Iptcdatum.groupName().

key()

Return the key of the Iptcdatum. The key is of the form ‘Iptc.recordName.datasetName’. Note however that the key is not necessarily unique, i.e., an IptcData object may contain multiple metadata with the same key.

print()

Write the interpreted value to a string.

Implemented in terms of write(), see there.

record()

Return the record id

Return type:

int

Returns:

record id

recordName()

Return the name of the record (deprecated)

Return type:

str

Returns:

record name

setValue()

See Iptcdatum.setValue().

size()

See Iptcdatum.size().

tag()

Return the tag (aka dataset) number

tagDesc()

See Iptcdatum.tagDesc().

tagLabel()

See Iptcdatum.tagLabel().

tagName()

Return the name of the tag (aka dataset)

Return type:

str

Returns:

tag name

toFloat()

See Iptcdatum.toFloat().

toInt64()

See Iptcdatum.toInt64().

toRational()

See Iptcdatum.toRational().

toString()

See Iptcdatum.toString().

toUint32()

Return the n-th component of the value converted to uint32_t.

typeId()

See Iptcdatum.typeId().

typeName()

See Iptcdatum.typeName().

typeSize()

See Iptcdatum.typeSize().

value()

See Iptcdatum.value().

write()

See Iptcdatum.write().

class IptcData_iterator_base

Bases: SwigPyObject

Python wrapper for an IptcData iterator that points to the ‘end’ value and can not be dereferenced.

class Iptcdatum

Bases: Metadatum

An IPTC metadatum (“dataset”), consisting of an IptcKey and a Value and methods to manipulate these.

This is referred in the standard as a property.

copy()

Write value to a data buffer and return the number of bytes written.

The user must ensure that the buffer has enough memory. Otherwise the call results in undefined behaviour.

Parameters:

• buf (writeable bytes-like object) – Data buffer to write to.

• byteOrder (ByteOrder) – Applicable byte order (little or big endian).

Return type:

int

Returns:

Number of characters written.

count()

Return the number of components in the value

familyName()

Return the name of the metadata family (which is also the first part of the key)

getValue()

Return an auto-pointer to a copy (clone) of the value. The caller owns this copy and the auto-poiner ensures that it will be deleted.

This method is provided for users who need full control over the value. A caller may, e.g., downcast the pointer to the appropriate subclass of Value to make use of the interface of the subclass to set or modify its contents.

Return type:

Value

Returns:

An auto-pointer containing a pointer to a copy (clone) of the value, 0 if the value is not set.

groupName()

Return the name of the metadata group (which is also the second part of the key)

key()

Return the key of the Iptcdatum. The key is of the form ‘Iptc.recordName.datasetName’. Note however that the key is not necessarily unique, i.e., an IptcData object may contain multiple metadata with the same key.

record()

Return the record id

Return type:

int

Returns:

record id

recordName()

Return the name of the record (deprecated)

Return type:

str

Returns:

record name

setValue()

Overload 1:

Set the value. This method copies (clones) the value pointed to by pValue.

Overload 2:

Set the value to the string buf. Uses Value::read(const std::string& buf). If the metadatum does not have a value yet, then one is created. See subclasses for more details. Return 0 if the value was read successfully.

size()

Return the size of the value in bytes

tag()

Return the tag (aka dataset) number

tagDesc()

Return a description for the tag

tagLabel()

Return a label for the tag

tagName()

Return the name of the tag (aka dataset)

Return type:

str

Returns:

tag name

toFloat()

Return the n-th component of the value converted to float. The return value is -1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toInt64()

Return the n-th component of the value converted to int64_t. The return value is -1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toRational()

Return the n-th component of the value converted to Rational. The return value is -1/1 if the value is not set and the behaviour of the method is undefined if there is no n-th component.

toString()

Overload 1:

Return the value as a string.

Overload 2:

Return the n-th component of the value converted to a string. The behaviour of the method is undefined if there is no n-th component.

typeId()

Return the type id of the value

typeName()

Return the name of the type

typeSize()

Return the size in bytes of one component of this type

value()

Return a constant reference to the value.

This method is provided mostly for convenient and versatile output of the value which can (to some extent) be formatted through standard stream manipulators. Do not attempt to write to the value through this reference. An Error is thrown if the value is not set; as an alternative to catching it, one can use count() to check if there is any data before calling this method.

Return type:

Value

Returns:

A constant reference to the value.

Raises:

Exiv2Error if the value is not set.

write()

Write the interpreted value to an output stream, return the stream.

The method takes an optional pointer to a metadata container. Pretty-print functions may use that to refer to other metadata as it is sometimes not sufficient to know only the value of the metadatum that should be interpreted. Thus, it is advisable to always call this method with a pointer to the metadata container if possible.

This functionality is currently only implemented for Exif tags. The pointer is ignored when used to write IPTC datasets or XMP properties.

Without the optional metadata pointer, you do not usually have to use this function; it is used for the implementation of the output operator for Metadatum , operator<<(std::ostream &os, const Metadatum &md).

See also print(), which prints the interpreted value to a string.