[Python-Dev] Packaging documentation and packaging.pypi API

[Paul Moore]

On 20 June 2012 14:47, Paul Moore <p.f.moore at gmail.com> wrote:
> On 20 June 2012 14:16, Alexis Métaireau <alexis at notmyidea.org> wrote:
>> packaging.pypi is functionally working but IMO the API can (and probably
>> should) be improved (we really lack feedback to know that).
>
> I wasn't aware of this - I've had a look and my first thought is that
> the documentation needs completing. At the moment, there's a lot that
> isn't documented, and we should avoid getting into the same situation
> as with distutils where people have to use undocumented APIs to get
> anything done. There are a lot of examples, but not so much formal API
> documentation.

As a specific example, one thing I would like to do is to be able to
set up a packaging.pypi client object that lets me query and download
distributions. However, rather than just querying PyPI (the default)
I'd like to be able to set up a list of locations (PyPI, a local
server, and maybe some distribution files stored on my PC) and combine
results from all of them. This differs from the mirror support in that
I want to combine the lists, not use one as a fallback if the other
doesn't exist. From the documentation, I can't tell if this is
possible, or a feature request, or unsupported... (Actually, there's
not even any documentation saying how the URL(s) in index_url should
behave, so how exactly do I set up a local repository anyway...?)

On a similar note, at some point, crawler.get_releases('pywin32')
needs to work. I believe the issue here is technically with pywin32,
which uses non-standard version numbers (214) and is hosted externally
(Sourceforge) but I'd expect that packaging.pypi should be able to
access anything that's on PyPI, even if other APIs like
packaging.version can't deal with them.

Ideally, these would be simply things I'd raise as issues on
bugs.python.org. But as things stand, such issues aren't getting
fixed, and we don't move forward. And without the documentation to
back up a debate, it's hard to argue "X is a bug, Y is a feature
request, Z is behaving correctly".

Paul.

PS As I write this, it suggests to me that maybe even the "pick out
the stable APIs" approach isn't as simple as we'd like to think it is.
You can either read this email as a set of specific documentation
points to fix, or as evidence that we should drop packaging.pypi as
well for now, even though it's a pretty cool feature...