From c27ff3ce07de79215b58f5fd10ff175424cba7cb Mon Sep 17 00:00:00 2001
From: "Yaakov M. Nemoy" <loupgaroublond@gmail.com>
Date: Thu, 8 Jan 2009 16:43:14 -0500
Subject: adds 135 kilocraps of documentation

135 kilocraps = 1 metric craptonne
---
 modules/directory.py | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'modules/directory.py')

diff --git a/modules/directory.py b/modules/directory.py
index 139a2c9..16e5a58 100644
--- a/modules/directory.py
+++ b/modules/directory.py
@@ -29,8 +29,17 @@ from base.util import pwd, copytree
 
 from modules.dirfactory import DirFactory
 class Directory(Module):
+    '''a generic base class for any module that has to maintain state 
+    on the file system in a directory
+    '''
     _type = 'directory'
     def __init__(self, name=None):
+        ''' initializer
+        
+        name is a path to the directory we are loading, if not given
+            name is gleaned by assuming the current directory is the
+            package desired
+        '''
         if not name:
             log.debug('no name with directory')
             cwd = getcwd()
@@ -50,6 +59,8 @@ class Directory(Module):
                 self.make_dir(dir)
 
     def is_sysdir_dir(self, dir):
+        '''given a directory, determine if the system directory is
+        already a directory or not'''
         with pwd(dir):
             cfg = ConfigObj('.devshell')
             try:
@@ -62,6 +73,7 @@ class Directory(Module):
                 return False
 
     def load_dir(self, dir):
+        '''presuming dir is a directory, load it's state'''
         log.debug('directory.load_dir')
         with pwd(dir):
             parent, name = split(getcwd())
@@ -75,10 +87,12 @@ class Directory(Module):
                 pass
 
     def make_dir(self, dir):
+        '''since dir is not a directory, make it into one'''
         log.debug('directory.make_dir')
         with pwd(dir):
             self.cfg = ConfigObj('.devshell')
             parent, name = split(getcwd())
+            # type is defined by the subclass
             self.cfg['type'] = self._type
             self.cfg['name'] = name
             self.parent = parent
@@ -86,34 +100,55 @@ class Directory(Module):
 
     @property
     def name(self):
+        ''' the name of the directory/module as defined by the user
+        '''
         return self.cfg['name']
 
     @property
     def parent(self):
+        ''' the parent directory holding the directory on the file system
+
+        this is determined at run time, and used to build absolute path names
+        out of elements of the directory
+        '''
         return self.cfg['parent']
 
     @property
     def dir(self):
+        '''absolute pathname to the directory where it is held on the file system'''
         return join(self.parent, self.name)
 
     def close(self):
+        '''called by devshell, closes the open objects'''
         log.debug('writing self.cfg for directory')
         with pwd(self.dir):
             self.cfg.write()
 
     def rename(self, new_name):
+        '''renames the directory internally, assuming it's been renamed 
+        on the file system
+
+        subclass authors take note, this must be reimplemented, and the 
+        superclass version called when any property or state depends on
+        self.name in any way shape or form.
+        '''
         self.cfg['name'] = new_name
 
     def move(self, new_loc):
+        '''given a new location, moves everything there, and renames'''
         new_loc = abspath(new_loc)
         new_parent, new_name = split(new_loc)
         old_dir = self.dir
         copytree(self.dir, new_loc)
         self.parent = new_parent
         self.rename(new_name)
+        with pwd(self.dir):
+            self.cfg.write()
         rm(old_dir)
 
     def copy(self, new_loc):
+        '''makes a copy of the contents in a new location, renames, 
+        and returns a reference to a new object rpresenting the new directory'''
         new_loc = abspath(new_loc)
         new_parent, new_name = split(new_loc)
         copytree(self.dir, new_loc)
-- 
cgit