Documented the high-level binding with doc strings.

1 files changed, 103 insertions, 24 deletions

diff --git a/src/pyexiv2.py b/src/pyexiv2.py
index a7e0fb1..79fe6ca 100644
--- a/src/pyexiv2.py
+++ b/src/pyexiv2.py
@@ -25,38 +25,104 @@
 # File:      pyexiv2.py
 # Author(s): Olivier Tilloy <olivier@tilloy.net>
 # History:   28-Dec-06, Olivier Tilloy: created
+#            30-Dec-06, Olivier Tilloy: documentation using doc strings
 #
 # ******************************************************************************
 
+"""
+Manipulation of EXIF and IPTC metadata embedded in image files.
+
+This module provides a single class, Image, and utility functions to manipulate
+EXIF and IPTC metadata embedded in image files such as JPEG and TIFF files.
+EXIF and IPTC metadata can be accessed in both read and write modes.
+
+This module is a higher-level interface to the Python binding of the excellent
+C++ library Exiv2, libpyexiv2.
+Its only class, Image, inherits from libpyexiv2.Image and provides convenient
+methods for the manipulation of EXIF and IPTC metadata using Python's built-in
+types and modules such as datetime.
+These methods should be preferred to the ones directly provided by
+libpyexiv2.Image.
+
+A typical use of this binding is as follows:
+
+	import pyexiv2
+	import datetime
+	image = pyexiv2.Image('path/to/imagefile')
+	image.readMetadata()
+	print image.getAvailableExifTags()
+	print image.getExifTagValue('Exif.Photo.DateTimeOriginal')
+	today = datetime.datetime.today()
+	image.setExifTagValue('Exif.Photo.DateTimeOriginal', today)
+	image.writeMetadata()
+	...
+
+"""
+
 import libpyexiv2
 
 import re
 import datetime
 
 def UndefinedToString(undefined):
-	# undefined must be a string containing the ascii codes of a sequence of
-	# bytes, each followed by a blank space (e.g. "48 50 50 49 " for "0221")
+	"""
+	Convert an undefined string into its corresponding sequence of bytes.
+
+	Convert a string containing the ascii codes of a sequence of bytes, each
+	followed by a blank space, into the corresponding string (e.g.
+	"48 50 50 49 " will be converted into "0221").
+	The Undefined type is defined in the EXIF specification.
+
+	Keyword arguments:
+	undefined -- the string containing the ascii codes of a sequence of bytes
+	"""
 	return ''.join(map(lambda x: chr(int(x)), undefined.rstrip().split(' ')))
 
-def StringToUndefined(string):
-	# string must be a string containing a sequence of ascii representations
-	# of bytes, to be converted in the suitable format for the type
-	# 'Undefined' in EXIF specification (e.g. "0221" will be converted into
-	# "48 50 50 49 ")
-	return ''.join(map(lambda x: '%d ' % ord(x), string))
+def StringToUndefined(sequence):
+	"""
+	Convert a string containing a sequence of bytes into its undefined form.
+
+	Convert a string containing a sequence of bytes into the corresponding
+	sequence of ascii codes, each	followed by a blank space (e.g. "0221" will
+	be converted into "48 50 50 49 ").
+	The Undefined type is defined in the EXIF specification.
+
+	Keyword arguments:
+	sequence -- the string containing the sequence of bytes
+	"""
+	return ''.join(map(lambda x: '%d ' % ord(x), sequence))
 
 class Image(libpyexiv2.Image):
+
 	"""
-	A class that extends the methods of class libpyexiv2.Image with "higher
-	level methods", making use of Python's built-in types and classes such as
-	datetime.
+	Provide convenient methods for the manipulation of EXIF and IPTC metadata.
+
+	Provide convenient methods for the manipulation of EXIF and IPTC metadata
+	embedded in image files such as JPEG and TIFF files, using Python's built-in
+	types and modules such as datetime.
+
+	Public methods:
+	getExifTagValue -- get the value associated to a key in EXIF metadata
+	setExifTagValue -- set the value associated to a key in EXIF metadata
 	"""
+
 	def getExifTagValue(self, key):
+		"""
+		Get the value associated to a key in EXIF metadata.
+
+		Get the value associated to a key in EXIF metadata.
+		Whenever possible, the value is typed using Python's built-in types or
+		modules such as datetime when the value is composed of a date and a time
+		(e.g. the EXIF tag 'Exif.Photo.DateTimeOriginal').
+
+		Keyword arguments:
+		key -- the EXIF key of the requested metadata tag
+		"""
 		tagType, tagValue = self.getExifTag(key)
 		if tagType == 'Byte':
 			return tagValue
 		elif tagType == 'Ascii':
-			# tries to guess if the value is a datetime
+			# try to guess if the value is a datetime
 			pattern = re.compile("([0-9]{4}):([0-9]{2}):([0-9]{2}) ([0-9]{2}):([0-9]{2}):([0-9]{2})")
 			match = pattern.match(tagValue)
 			if match == None:
@@ -87,18 +153,31 @@ class Image(libpyexiv2.Image):
 				v = map(long, match.groups())
 				return v[0], v[1]
 		elif tagType == 'Undefined':
-			# tagValue is a sequence of bytes whose codes are written as
-			# a string, each code being followed by a blank space
-			# (e.g. "48 50 50 49 " for "0221")
-			# Note: in the case of tag "Exif.Photo.UserComment", it is
-			# better to call method getExifTagToString() to obtain
-			# directly the value as a human-readable string
+			# tagValue is a sequence of bytes whose codes are written as a
+			# string, each code being followed by a blank space (e.g.
+			# "48 50 50 49 " for "0221").
+			# Note: in the case of tag "Exif.Photo.UserComment", it is better to
+			# call method getExifTagToString() to obtain directly the value as a
+			# human-readable string.
 			return UndefinedToString(tagValue)
 		else:
 			# empty type and value
 			return
 
 	def setExifTagValue(self, key, value):
+		"""
+		Set the value associated to a key in EXIF metadata.
+
+		Set the value associated to a key in EXIF metadata.
+		The new value passed should be typed using Python's built-in types or
+		modules such as datetime when the value is composed of a date and a time
+		(e.g. the EXIF tag 'Exif.Photo.DateTimeOriginal'), the method takes care
+		of converting it before setting the internal EXIF tag value.
+
+		Keyword arguments:
+		key -- the EXIF key of the requested metadata tag
+		value -- the new value for the requested metadata tag
+		"""
 		valueType = value.__class__
 		if valueType == int or valueType == long:
 			strVal = str(value)
@@ -107,11 +186,11 @@ class Image(libpyexiv2.Image):
 		elif valueType == tuple:
 			strVal = '%s/%s' % (str(value[0]), str(value[1]))
 		else:
-			# value must already be a string
-			# warning: no distinction is possible between values that
-			# really are strings (type 'Ascii') and those that are
-			# supposed to be sequences of bytes (type 'Undefined'), in
-			# which case value must be passed as a string correctly
-			# formatted, using function StringToUndefined()
+			# Value must already be a string.
+			# Warning: no distinction is possible between values that really are
+			# strings (type 'Ascii') and those that are supposed to be sequences
+			# of bytes (type 'Undefined'), in which case value must be passed as
+			# a string correctly formatted, using utility function
+			# StringToUndefined().
 			strVal = value
 		self.setExifTag(key, strVal)