Path: csiph.com!usenet.pasdenom.info!gegeweb.org!aioe.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed3.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
To: python-list@python.org
From: Ben Finney <ben+python@benfinney.id.au>
Subject: Re: Using a ChangeLog as a canonical source of package metadata
Date: Mon, 12 Jan 2015 07:21:25 +1100
References: <54ae0917$0$2738$c3e8da3$76491128@news.astraweb.com> <mailman.17465.1420701187.18130.python-list@python.org> <54ae6715$0$12987$c3e8da3$5496439d@news.astraweb.com> <mailman.17488.1420762070.18130.python-list@python.org> <54b2be27$0$13000$c3e8da3$5496439d@news.astraweb.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux)
Cancel-Lock: sha1:EykkIhugMOZFuwuXx9MapYF04JQ=
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.17593.1421007692.18130.python-list@python.org>
Lines: 59
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: csiph.com comp.lang.python:83561

Steven D'Aprano <steve+comp.lang.python@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