New PEP: Quality Guidelines For Standard Modules

[Carlos Ribeiro]

This is a small draft of mine, still unnumbered. It deals with some of the 
issues associated with PEP 2, namely:

- the definition of the "Standard Library";

- some considerations about OS independency and its relation to the 
Standard Library;

- and finally, some fairly broad guidelines for standard modules.

I've decided to submit it to the group before sending it Barry Warsaw. I 
think that this subject still deserves some public discussion before fixing 
the PEP format. I also believe that the main issue with PEP 2 is that it is 
too big to be tackled as a single PEP; it is better for us to have a 
"framework" for the Standard Library and modules in general, comprised of 
several PEPs. Too many cats for a single bag.

p.s. That's probably my first formal document in English. I'm not used to 
write such documents in English, and I don't think that I'm going to win a 
Pulitzer on it anytime soon :-) Critics are welcome.


Carlos Ribeiro
----

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.

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

     - 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.

     5. Attributes whose value is expected to be constant SHOULD
        have their names written in uppercase.


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...)


Copyright

     This document has been placed in the public domain.


Acknowledgements

     This PEP would be impossible without the help of the Python
     community. In special, Martijn Faassen and Paul Prescod helped
     a lot to bring the issue to our attention.

     (please help me here also; I dont want to step on anybody's
     toes, but I'm having a terrible time to find all the past
     references on my mailbox)




Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: