Tutorial: reading and writing EXIF tags.

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