[Python-checkins] python/nondist/peps pep-0008.txt,1.20,1.21

Sat Mar 20 01:42:31 EST 2004

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9079
Modified Files:
	pep-0008.txt 
Log Message:
Patch 919256
Clarify and standardize the format for names of modules, functions, 
methods, and instance variables.
Consistent, I hope, with discussion on python-dev
http://mail.python.org/pipermail/python-dev/2004-March/043257.html
http://mail.python.org/pipermail/python-dev/2004-March/043259.html
Index: pep-0008.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0008.txt,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** pep-0008.txt	27 Sep 2003 02:53:59 -0000	1.20
--- pep-0008.txt	20 Mar 2004 06:42:29 -0000	1.21
***************
*** 425,457 ****
 Module Names

! Module names can be either CapWords or lowercase. There is no
! unambiguous convention to decide which to use. Modules that
! export a single class (or a number of closely related classes,
! plus some additional support) are often named in CapWords, with
! the module name being the same as the class name (e.g. the
! standard StringIO module). Modules that export a bunch of
! functions are usually named in all lowercase.

! Since module names are mapped to file names, and some file
! systems are case insensitive and truncate long names, it is
! important that module names be chosen to be fairly short and not
! in conflict with other module names that only differ in the case
! -- this won't be a problem on Unix, but it may be a problem when
! the code is transported to Mac or Windows.

! There is an emerging convention that when an extension module
! written in C or C++ has an accompanying Python module that
! provides a higher level (e.g. more object oriented) interface,
! the Python module's name CapWords, while the C/C++ module is
! named in all lowercase and has a leading underscore
 (e.g. _socket).

! Python packages generally have a short all lowercase name.

 Class Names

! Almost without exception, class names use the CapWords
! convention. Classes for internal use have a leading underscore
! in addition.

 Exception Names
--- 425,448 ----
 Module Names

! Modules should have short, lowercase names, without underscores.

! Since module names are mapped to file names, and some file systems
! are case insensitive and truncate long names, it is important that
! module names be chosen to be fairly short -- this won't be a
! problem on Unix, but it may be a problem when the code is
! transported to Mac or Windows.

! When an extension module written in C or C++ has an accompanying
! Python module that provides a higher level (e.g. more object
! oriented) interface, the C/C++ module has a leading underscore
 (e.g. _socket).

! Python packages should have short, all-lowercase names, without
! underscores.

 Class Names

! Almost without exception, class names use the CapWords convention.
! Classes for internal use have a leading underscore in addition.

 Exception Names
***************
*** 465,474 ****
 Function Names

! Plain functions exported by a module can either use the CapWords
! style or lowercase (or lower_case_with_underscores). There is
! no strong preference, but it seems that the CapWords style is
! used for functions that provide major functionality
! (e.g. nstools.WorldOpen()), while lowercase is used more for
! "utility" functions (e.g. pathhack.kos_root()).

 Global Variable Names
--- 456,463 ----
 Function Names

! Function names should be lowercase, possibly with underscores to
! improve readability. mixedCase is allowed only in contexts where
! that's already the prevailing style (e.g. threading.py), to retain
! backwards compatibility.

 Global Variable Names
***************
*** 476,484 ****
 (Let's hope that these variables are meant for use inside one
 module only.) The conventions are about the same as those for
! exported functions. Modules that are designed for use via "from
! M import *" should prefix their globals (and internal functions
! and classes) with an underscore to prevent exporting them.

! Method Names

 The story is largely the same as for functions. Use lowercase
--- 465,473 ----
 (Let's hope that these variables are meant for use inside one
 module only.) The conventions are about the same as those for
! functions. Modules that are designed for use via "from M import *"
! should prefix their globals (and internal functions and classes)
! with an underscore to prevent exporting them.

! Method Names and Instance Variables

 The story is largely the same as for functions. Use lowercase