New PEP: Quality Guidelines For Standard Modules

[Roman Suzi]

On Sun, 1 Jul 2001, Carlos Ribeiro wrote:

> PEP: Unnumbered
> Title: Quality Guidelines For Standard Modules
> Version: $Revision: 0.1$
> Author: cribeiro at mail.inet.com.br (Carlos Ribeiro)
> Status: Draft
> Type: Informational
> Created: 01-Jul-2001
> Post-History:
> 
> 
> Abstract
> 
>      This PEP describes the minimum quality guidelines for modules
>      to be included as part of the Standard Library. The main
>      focus is to define a minimum quality level, making the use
>      of the module as easy, consistent and predictable as possible.
>      These recommendations are not meant to be enforced as absolute
>      rules, and should not prevent non-compliant modules from being
>      included in any Python Distribution.
> 
>      This proposal does not try to enforce rigid rules on
>      controversial issues such as source code style and attribute
>      names. There are no absolute rules for these issues.  However,
>      we feel that some general advice is applicable to most
>      instances, and so included some guidelines on this topic.
> 
>      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.
> 
> 
> 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.

> What is "quality"?
> 
>      This question is as old as philosophy, and as such, there are
>      no absolute answers. Our definition of quality, as applied to
>      the modules in the Standard Library, is based on the folowing
>      atributes:
> 
>      - Consistence. All modules in the Standard Library follow
>        similar structure. Similar objects or attributes always lead
>        to similar results.

Maybe there could be 2-3 different structures, because modules are so
different and to force similar behaviour from them could be
coounter-productive.

>      - Predictability. By means of a consistent interface, all
>        the modules provide highly predictable behavior. Subtle
>        surprises must be avoided.

realistically surprises are always present because they 
depend on the knowledge of the user.
 
>      - Readability. Both the documentation and the code must be
>        easy to read, making the learning process much easier.
> 
> 
> Documentation and naming guidelines
> 
>      1. By definition, Standard Library modules MUST be documented
>         in the main Python Library Reference.
> 
>      2. The module author SHALL supply the documentation as part
>         of the process for module acceptance in the Standard
>         Library, as covered in PEP-2.
> 
>      3. All the classes and functions exported by the module MUST
>         have PEP-256 compliant docstrings.
> 
>      4. Class names SHOULD be written in mixed case.

Why? Again, in some situation class names are dictated by
the problem domain...
 
>      5. Attributes whose value is expected to be constant SHOULD
>         have their names written in uppercase.

So, I will need to rewrite my programs to use 

math.PI instead of math.pi ?

Something about compatibility must be said here...

I am sure there are other examples where constants need to
be used "as is" to avoid "surprises".

Maybe, better define cases when these rules could be broken?

I think, that it's enough to be near the Style Guide when writing a
standard library module. But not to take it dogmatically, of course.
 
> Module structure guidelines
> 
>      1. Standard Modules MUST not rely on global variables to keep
>         state information, except when it is absolutely required.
>         Whenever it does need to save state information, the use
>         of a instance object is suggested.
> 
>      2. In the case that the module is expected to support only a
>         single instance, a singleton MUST be used, instead of
>         global variables.
> 
>      3. Python source code MUST be written using only spaces. Tabs
>         are not allowed on source code files.
> 
> 
> 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.
> 
>      3. OS-DEPENDENT modules SHOULD only be included to support
>         functionality required to use Python in the target platform.
> 
>      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.
> 
> 
> Remarks
> 
>      This draft was inspired by the discussions regarding Python
>      development, and PEPs in particular. After following the
>      discussion it became clear that one of the main topics of the
>      debate was the need to improve the library. However, we did
>      lack some definitions on this, and this PEP is being addressed
>      at this particular problem.
> 
>      We did chose to use the Python Library Reference documentation
>      as the basis for our definition, because we felt that no other
>      definition would as clearly embrace the set of modules that
>      the community regards as the standard one.
> 
> 
> References
> 
>      (still incomplete; please help me!)
> 
>      [1] PEP 2 - Procedure for Adding New Modules
> 
>      [2] PEP 256 - Docstring Processing System Framework
> 
>      [3] (...there a more to come, please be patient...)

        Style Guide?
 
> Copyright
> 
>      This document has been placed in the public domain.
> 

Probably this PEP also need to mention directory structure 
of standard library?

Anyway, it seems that probably you need to submit it as PEP
and let wide discussion to make this doc nearly perfect.

Sincerely yours, Roman A.Suzi
-- 
 - Petrozavodsk - Karelia - Russia - mailto:rnd at onego.ru -