[Distutils] Python people want CPAN and how the latter came about

[Steffen Mueller]

Hi Lennart,

Lennart Regebro <regebro <at> gmail.com> writes:
> Interesting. I generally don't find automatically generated
> documentation useful, but if it works for PERL I guess that's a
> personal taste.

Let me add two nits here:
It's Perl, not PERL. The name of the language is *not* an acronym. Some people
are really picky about that.

More importantly, it's not "auto-generated" documentation per se. Not something
like using doxygen to generate an API reference purely from the function/method
name and signature. Instead, search.cpan.org (and kobesearch) extract the
inlined documentation from the Perl modules. This documentation was written by
the authors. It was *not* generated from the code itself. Here's what that looks
like for a random one of my modules:
http://search.cpan.org/~smueller/PAR-Repository-Client/lib/PAR/Repository/
Client.pm

You could get the same page via
http://search.cpan.org/perldoc?PAR::Repository::Client. This is an example of
how CPAN works on namespace and distribution level. After a new file is
uploaded, its contained namespaces (packages/class names) are added to the
index if they're not already there. The index always contains a reference to
the distribution that contains the newest *authorized* version of any
namespace. Thus, you can access the distribution directly like in the first
URL or have search.cpan.org go from package name to the most recent
authorized version automatically (via the perldoc link).

> > 4. Namespaces and some way of reserving them. There are likely many
> > modules named postgresql on PyPI, but there's only one DBD::Pg (although
> > there are other PostgreSQL modules that implement the perl DBI driver
> > interface). This also helps with specifying dependencies.
> 
> There is no reserving in the Python world, that's true. I'm skeptical.
> There's enough problems with packages not being updated, we don't want
> that for namespaces too, that would be terrible.

We have a band of PAUSE admins with super cow powers to save the day. It's not
like there's a lot of us, but so far, we've been able to handle authorization
requests reasonably. Our policy in case an author goes missing who has
permissions for a certain namespace are documented here:
http://search.cpan.org/CPAN/modules/04pause.html#takeover

> > It definitely appears to have the framework, but lacks some finishing
> > touches that would enormously enhance usability.
> 
> So far we have identified a "show all versions" link, and
> automatically generated documentation. Thanks! Finally something
> concrete! 

In a very concrete context: I really like how search.cpan.org will show you the
latest stable version by default and provide drop-downs to select any developer
(alpha) or old releases. It also has nice, consistent URLs as demonstrated
above. ...~author will get me to author's overview page, .../dist/XXX will get
me to the XXX distribution's overview, etc. Accessing any files within each
distribution is possible via similar URLs.

Another point that I really like about the service is that the distribution
pages provide links to many other related services that are run by other
volunteers. Take for example http://search.cpan.org/dist/PAR-Repository-Client/
There is a link to cpanforum, specifically the relevant discussion forum for the
module at hand. It shows a link to the bug/request tracker with the number of
open bugs, the one next to it will display a nice hierarchical (recursive) list
of dependencies. Again. Run by another volunteer. The line below is dedicated to
CPAN testers results. It shows the number of FAIL/PASS/UNKNOWN results followed
by a link to the page with the raw reports and -- this is extremely useful as an
author -- a colourful matrix that shows the test results depending on perl
version and operating system. My example in this mail is not a very widely used
module. Thus, the matrix is somewhat sparse, too:
http://matrix.cpantesters.org/?dist=PAR-Repository-Client+0.25. But it clearly
shows my module isn't compatible to really old versions of Perl (5.6). In some
other cases, I might learn that it isn't working well on some operating system
because its column is red or yellow. Here's an example of a more widely used and
installed distribution: http://matrix.cpantesters.org/?dist=Data-Dumper+2.125.
As an author, these tools help me identify weak points or portability problems
in my software. As a user, this can help me understand whether I really want to
rely on this piece of software for my business. Everyone wins.

Please don't take any of this the wrong way. I'm not trying to say "look what we
can do and you don't" at all. Not only do I have no idea what the python tools
look like, but in the previous two paragraphs, I am really just trying to point
out a few technical strong points of various CPAN-related services that are very
valuable to me as a user, developer and contributor.

Best regards,
Steffen