3c7f8656752e3c4560fa51950504b57acc31932f
mmaddren
  Mon Oct 31 15:35:40 2011 -0700
trackInfo now supports the bam/bai comma separated filenames, style guide updated
diff --git python/style.txt python/style.txt
index 4ceb853..242e334 100644
--- python/style.txt
+++ python/style.txt
@@ -1,43 +1,69 @@
 Style Guide for Python Code
 
 Documentation Conventions
 
 Use """ doc strings to embed comments for automated documentation generator:
     http://epydoc.sourceforge.net/
 
 Naming Conventions
 
 Packages and Modules
-    All lowercase names, no spaces. Underscores if it would improve
-readability in modules, but not for use in packages. Need to discuss how
-classes are organized in packages and files and where programs are stored.
+    In Python, a package is represented as a directory with an __init__.py
+file in it, and contains some number of modules, which are represented as
+files with a .py extension. A module may in turn contain any number of related
+classes and methods. This differs from Java, where one file correlates to one
+class: in Python it is correct to treat one module similar to a whole
+namespace in Java.
+    Packages and modules should have short names in lowercase, with no spaces or
+underscores. An good example of this style is the ucscgenomics package:
+
+    ucscgenomics/
+        __init__.py
+        ra.py
+        cv.py
+        ...
+
+    For more information:
+        http://docs.python.org/tutorial/modules.html
+
+Imports
+    The most correct way to import something in Python is so that must be
+identified by its containing module:
+        import os
+        from ucscgenomics import ra
+
+    Then, the qualified name can be used:
+        somera = ra.RaFile()
+
+    For more information, see the "Imports" section:
+        http://www.python.org/dev/peps/pep-0008/
 
 Classes
     CapitalCase names. Note the leading captial letter to distinguish between a
 ClassName and a functionName. Underscores are not used, except for private
 internal classes, where the name is preceded by double underscores which
 Python recognizes as private.
 
 Methods
     mixedCase names. The leading character is not captialized, but all
 successive words are capitalized. Underscores are not used, except for private
 internal methods, where the name is preceded by double underscores which
 Python recognizes as private.
 
 Variables
-    mixedCase names. Underscores are not used, except for private
+    lowercase names. Underscores are not used, except for private
 internal variables, where the name is preceded by double underscores which
 Python recognizes as private.
 
 Testing
     Testing is carried out using the unittest module in python. This module
 allows for self-running scripts which only need the following lines at the
 bottom of the script:
     if __name__ == '__main__':
         unittest.main()
 
     The scripts themselves are composed of one or more classes, all of which
 inherit from unittest.TestCase and contain one or more methods which use
 various asserts or failure checks to determine whether a test passes or not.
 Testing is self-contained, and should provide its own input and output
 directories and files.