diff options
| -rw-r--r-- | doc/tutorial.rst | 88 |
1 files changed, 87 insertions, 1 deletions
diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 2a01406..36d26a6 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -1,4 +1,90 @@ Tutorial ======== -TODO +This tutorial is meant to give you a quick overview of what pyexiv2 allows you +to do. You can just read it through or follow it interactively, in which case +you will need to have pyexiv2 installed. + +Let's get started! + +First of all, we import the pyexiv2 module:: + + >>> import pyexiv2 + +We then load a JPEG image file and read its metadata:: + + >>> metadata = pyexiv2.ImageMetadata('test.jpg') + >>> metadata.read() + +Reading and writing EXIF tags +############################# + +Let's retrieve a list of all the available EXIF tags available in the image:: + + >>> metadata.exif_keys + +This returns a list of EXIF keys, much like this:: + + ['Exif.Image.ImageDescription', + 'Exif.Image.XResolution', + 'Exif.Image.YResolution', + 'Exif.Image.ResolutionUnit', + 'Exif.Image.Software', + 'Exif.Image.DateTime', + 'Exif.Image.Artist', + 'Exif.Image.Copyright', + 'Exif.Image.ExifTag', + 'Exif.Photo.Flash', + 'Exif.Photo.PixelXDimension', + 'Exif.Photo.PixelYDimension'] + +Each of those tags can be accessed with the ``[]`` operator on the metadata, +much like a python dictionary:: + + >>> tag = metadata['Exif.Image.DateTime'] + +The value of an :class:`ExifTag` object can be accessed in two different ways: +with the :attr:`raw_value` and with the :attr:`value` attributes:: + + >>> tag.raw_value + '2004-07-13T21:23:44Z' + + >>> tag.value + datetime.datetime(2004, 7, 13, 21, 23, 44) + +The raw value is always a byte string, this is how the value is stored in the +file. The value is lazily computed from the raw value depending on the EXIF type +of the tag, and is represented as a convenient python object to allow easy +manipulation. + +Note that querying the value of a tag may raise an :exc:`ExifValueError` if the +format of the raw value is invalid according to the EXIF specification (may +happen if it was written by other software that implement the specification in a +broken manner), or if pyexiv2 doesn't know how to convert it to a convenient +python object. + +Accessing the value of a tag as a python object allows easy manipulation and +formatting:: + + >>> tag.value.strftime('%A %d %B %Y, %H:%M:%S') + 'Tuesday 13 July 2004, 21:23:44' + +Let's now modify the value of the tag and write it back to the file:: + + >>> from datetime import datetime + >>> tag.value = datetime.today() + + >>> metadata.write() + +Similarly to reading the value of a tag, one can set either the +:attr:`raw_value` or the :attr:`value` (which will be automatically converted to +a correctly formatted byte string by pyexiv2). + +You can also add new tags to the metadata by providing a valid key and value +pair (for a list of valid EXIF tags, see +`exiv2's documentation <http://exiv2.org/tags.html>`_):: + + >>> key = 'Exif.Photo.UserComment' + >>> value = 'This is a useful comment.' + >>> metadata[key] = pyexiv2.ExifTag(key, value) + |