Using a ChangeLog as a canonical source of package metadata (was: Announce: PyPrimes 0.2.1a)

Steven D'Aprano steve+comp.lang.python at
Sun Jan 11 19:17:10 CET 2015

Ben Finney wrote:
> The perils of duplicate sources of information: a Changelog makes claims
> about which version is latest, but the packaging metadata comes from
> somewhere else.
> This problem is addressed quite well, in my opinion, by the Debian
> packaging tools. The tools by default read the following information:
> * release version string
> * maintainer name
> * maintainer email address
> * target suite (a conceptual “which Debian version should this go into”)
> from the Changelog document, automatically. This means that the
> Changelog document, as well as being directly useful to the recipient as
> a text document, becomes the canonical place to record all those fields
> for the packaging tools to read. No need to maintain duplicate records.

A very interesting way to handle this, and one which deserves further

I currently read this metadata from the Python code itself. The advantages
of putting the metadata into the source code include:

- the source code is the definitive source of information about itself;
- even if the user deletes the README and CHANGELOG files, they can 
  still find the metadata;
- if your application wants to report a version number (as many apps 
  do) then it is easy for them to do so.

But the disadvantages include:

- it's a bit sad to have to put such metadata into the source code;
- the risk of the changelog getting out of date.

> I would like Python's packaging tools to have the same capability.
> This requires recording the Changelog document in a machine-parseable
> format, with specified locations for each of the fields to be read for
> each version.

I wonder whether it would be better to have check the CHANGELOG and
halt if it isn't up to date? 

> I have recently gone through a process of converting the Changelog for a
> package I maintain (‘python-daemon’) to reStructuredText [0]. This has
> all the above features: machine-parseable, a well-defined way to attach
> fields to a section, etc.
> [0] reStructuredText: <URL:>
> I've now produced a small Python library which knows how to transform a
> reST Changelog to package metadata; and how to get that package metadata
> into and out of a Python distribution with Distutils.

Sounds interesting. Where can we see this?

> The result is that I will never again upload the package with a mismatch
> between what the Changelog claims is the latest version, and what the
> package metadata says.
> This may be generally useful to others. I'm interested to know how
> people would expect to use this. As an extension to Distutils? As a
> third-party library? Something else?

Offering it as a third-party library is a good start, but perhaps you could
discuss this on the packaging mailing list and see whether they have any
interest in it?


More information about the Python-list mailing list