New PEP: Quality Guidelines For Standard Modules

[Malcolm Tredinnick]

Some quick initial impressions to get the ball rolling (hopefully this
won't degenerate into a repeat of some previous threads).

Mostly, these are critical comments, but that's not because I'm a
negative bastard (well, I am, but...). Rather, some resolution would be
nice to these discussions, so if somebody throws out a PEP like this,
let's hammer it out and then it either survives and becomes policy or it
becomes clear that we don't really need.

I'm glad some people have taken the time to write down come conclusions
from the earlier discussions.

On Sun, Jul 01, 2001 at 09:45:23PM -0300, Carlos Ribeiro wrote:
>      Last but not least, this proposal must be understood as a
>      broad set of recommendations. It is not meant to be read as
>      a set of rules to be enforced. Non-compliant modules may be
>      still be accepted as part of the standard library for several
>      reasons. Common sense and community acceptance are still the
>      best judges on this.

This last bit pretty much guarantees that everytime somebody proposes a
slightly border-line case, we will revisit the same tired old arguments
again and again. In fact, it's a bit worse than that: since there are a
whole bunch of modules in the current distribution which fail to meet
you recommendations, there's scope for "discussion" aplenty without
further delay. :-)

More seriously, this caveat is useful, since it is a response to all of
my complaints below: anything that falls between the cracks becomes a
source of discussion and then something like a BDFL pronouncement to
settle it.

> What is the Standard Library?
> 
>      The Standard Library is comprised of the modules that are
>      referenced in the Python Library Reference manual. Standard
>      Python Distributions MUST support all modules from the
>      Standard Library, with the exception of OS-dependant ones.

This seems loosely phrased. What do you mean by "support all modules"?
Do they have to compile? Do they have to return sensible answers when
they run? Can they just say "Not supported on this platform"?

It may be tempting to change this to "must include all modules from the
standard library". However, this is tricky for a couple of reasons: this
PEP hasn't really discussed why the concept of a Standard Library is
required, and I'm not convinced it's a good idea to keep making the
Python "distribution" larger and larger. My modem already starts to
complain if I have to do a full download (thank heavens for CVS
updates).

That last paragraph possibly sows the seed for a whole discussion on the
merits of including every standard component under the sun, or just
having a system for saying "component ZZ is required" and having a place
to download it (a la CPAN in that other world). I'm also not sure this
PEP is necessarily the place for also defining things like "what is a
distribution" (I don't even think that's a useful concept to formalise).

[...]
> OS-dependency guidelines
> 
>      1. There are three main categories of modules regarding the
>         dependency on some particular OS or hardware platform:
> 
>         * OS-DEPENDENT modules are, for intrinsec reasons, supported
>           only on some particular platforms and/or hardware
>           platforms. They may not be ported to other platforms
>           without substantial investment or changes to the
>           underlying environment.
> 
>         * OS-LIMITED modules are supported only on some particular
>           platforms. They are not inherently limited to the
>           supported platforms, but for some reason the code cannot
>           be easily ported (or supported) on other platforms.
> 
>         * OS-INDEPENDENT modules are supported on many platforms.
>           Some particular platforms may not support the module,
>           because of severe limitations on the platform itself.
>           These limitations are easily recognizable, specially if
>           the module is already supported on all major platforms.
> 
>      2. OS-LIMITED modules SHOULD NOT be included in the Standard
>         Library. The module author MUST rewrite the module in such
>         a way to make possible to port it to other platforms as a
>         OS-INDEPENDENT module.

The OS-LIMITED concept was a bit confusing to me the first couple of
times I read this. Basically, you are saying "write portable code", as
far as I can tell. If there were other obstacles, wouldn't that make the
module OS-DEPENDENT? If I'm missing something here, perhaps you can give
an example of something that is portable code, but OS-LIMITED and not
OS-DEPENDENT.

>      3. OS-DEPENDENT modules SHOULD only be included to support
>         functionality required to use Python in the target platform.

This is again a little loosely phrased. I can "use" Python with only a
handful of modules. Of course, it becomes reasonably functionality-free
at that point and I'd probably prefer C or Perl or shell scripting
instead. :-(

It is quite reasonable to have modules in the "standard library" that
are only supported on a wide range of platforms (not all platforms). For
example, there are already various things that are Unix specific and are
awkward at best on Redmond-based operating systems. The set of
Unix-like systems is quite large and if module X runs well on those, why
should it not be included just because Windows is broken (to pick but
one example)?

Similarly, the current stuff for supporting the Macintosh finder tools
and the like are fairly narrowly targeted, but they touch a large user
base.

>      4. OS-INDEPENDENT modules that rely on specific code in Python
>         for every platform supported MUST import a separate module
>         that implements the platform specific code. This (sub)module
>         SHOULD preferably be part of the main package. In this case
>         the module name should reflect the platform it supports.

Lest I sound too negative above, I think this categorisation scheme is
somewhat useful (it also exists already, since the library reference
already identifies the platform availability). Particularly for module
writers, who should be thinking about where their target is (does the
module really have to be platform dependent, or can they design it so
that somebody else can come along and add the bits to make it run on a
Palm Pilot and a Cray and a Space Shuttle, etc).

Cheers,
Malcolm

-- 
A clear conscience is usually the sign of a bad memory.