Using a ChangeLog as a canonical source of package metadata

[Ben Finney]

Steven D'Aprano <steve+comp.lang.python at pearwood.info> writes:

> 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;

The Changelog document should be in the same source tree and maintained
by the same people, so I don't count that as a difference between the
two approaches.

> - even if the user deletes the README and CHANGELOG files, they can 
>   still find the metadata;

Perhaps I didn't emphasise it, but: The approach I'm advocating (as
inspired by Debian packaging tools) has the version metadata
*canonically* recorded in the Changelog, but not *only* stored there.

The packaging tools parse the version metadata from the Changelog, then
duplicate whatever metadata is needed in various other places — such as
for programmatic access by the package's own code.

> - if your application wants to report a version number (as many apps 
>   do) then it is easy for them to do so.

The idea is to parse from the Changelog the version metadata, and record
it in Setuptools metadata. Then the ‘pkg_resources’ module of Setuptools
allows programmatic access to that metadata.

Thanks for enumerating those points, I think they are adequately
addressed by this approach.


> > 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?

It is the approach used in ‘python-daemon’ version 2. Find the source at
<URL:https://alioth.debian.org/projects/python-daemon/>. The
‘ChangeLog’, ‘setup.py’, ‘version.py’, ‘daemon/_metadata.py’ files are
the relevant ones to examine.

Since this is a new approach I'm trying, I flubbed a couple of versions:
you'll need version 2.0.1 or later (I omitted the ‘version’ module
entirely from the earlier distribution), and you'll need ‘docutils’
already installed (a future ‘python-daemon’ distribution will declare
this dependency).

I'll be interested to see how Python developers like this.

-- 
 \      “The process by which banks create money is so simple that the |
  `\     mind is repelled.” —John Kenneth Galbraith, _Money: Whence It |
_o__)                                       Came, Where It Went_, 1975 |
Ben Finney