README for debian.changelog
---------------------------

The aim of this module is to provide programmatic access to Debian changelogs
to query and manipulate them.

N.B. The API is not stable yet, and so you can expect it to change.

Create a changelog object using the constuctor. Pass it the contents of the 
file if there are some entries, or None to create an empty changelog.
See /usr/share/doc/python-debian/examples/changelog/ for examples of usage.

If you have the full contents of a changelog, but are only interested in the
most recent versions you can pass the max_blocks keyword parameter to the
constuctor to limit the number of blocks of the changelog that will be parsed.
If you are only interested in the most recent version of the package then pass
max_blocks=1.

The Changelog class provides the following interesting attributes and methods:

 * version
     A Version object representing the version of the last block.  You may
     assign to it a Version object or a full version string.
 * full_version
     The full version number of the last version.
 * debian_version
     The debian part of the version number of the last version.
 * upstream_version
     The upstream part of the version number of the last version.
 * epoch
     The epoch number of the last revision, or None if no epoch was 
     used.
 * versions
     A list of Version objects that the package went through. These version
     objects provide all attributes named the same as the above to get that
     same information.  You cannot assign to this attribute.
 * package
     The name of the package in the last version.
 * distributions
     A string indicating the distributions that the package will be uploaded to
     in the most recent version.
 * urgency
     A string indicating the urgency with which the most recent version will be
     uploaded.
 * author
     The author of the most recent change. This should be a properly formatted
     name/email pair.
 * date
     The date associated with the current entry. Should be a properly formatted
     string with the date and timezone.

 * parse_changelog(file)
     If you create an Changelog object without sepcifying a changelog file, you 
     can parse a changelog file with this method. If the changelog doesn't parse
     cleanly, a ChangelogParseError exception is thrown. The constructor will
     parse the changelog on a best efford basis.
 * add_change(change)
     Adds a change entry to the most recent version. The change entry should
     conform to the required format of the changelog (i.e. start with two 
     spaces). No line wrapping or anything will be performed, so it is 
     advisable to do this yourself if it is a long entry. The change will be
     appended to he current changes, no support is provided for per-maintainer
     changes.
 * new_block(package, version, distributions, urgency, changes, author, date)
     Start a new version of the package. The arguments (all optional) specify
     the values that can be provided to the set_* methods. If they are omitted
     the associated attributes must be assigned to before the changelog is
     created.
 * write_to_open_file(file)
     Write the changelog out to the filehandle passed. The file argument must
     be an open file object.

To get the properly formatted changelog back out of the object merely call 
str() on it. The returned string should be a properly formatted changelog.

There are a number of errors that may be thrown by the module.

 * ChangelogParseError
     Indicates that the changelog could not be parsed, i.e. there is a line
     that does not conform to the requirements, or a line was found out of its
     normal position. May be thrown when using the method parse_changelog. The
     constructor will not throw this exception.
 * ChangelogCreateError
     Some information required to create the changelog was not available. This
     can be thrown when str() is used on the object, and will occur if a 
     required value is None.
 * VersionError
     The string used to create a Version object cannot be parsed as it doesn't
     conform to the specification of a version number. Can be thrown when
     creating a Changelog object from an existing changelog, or instantiating
     a Version object directly to assign to the version attribute of a
     Changelog object.

If you have a changelog that may have no author information yet as it is still
a work in progress, i.e. the author line is just

    --

rather than

    -- Author <author@debian.org>  Thu, 12 Dec 2006 12:23:34 +0000

then you can pass

    allow_empty_author=True

to the Changelog constructor. If you do this then the ``author`` and ``date``
attributes may be ``None``.

This file is (C) 2006-7 James Westby, and licensed under the GPL, see 
changelog.py for details.

