Using a ChangeLog as a canonical source of package metadata (was: Announce: PyPrimes 0.2.1a)
steve+comp.lang.python at pearwood.info
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 setup.py 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 . This has
> all the above features: machine-parseable, a well-defined way to attach
> fields to a section, etc.
>  reStructuredText: <URL:http://docutils.sourceforge.net/rst.html>
> 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