1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
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.
|
