docstring

README.md

@@ -33,7 +33,7 @@ Features:
 * Handle files and directories
 * Allow to symlink dotfiles
 * Associate an action to the deployment of specific dotfiles
-* Associate transformations that allow to store encrypted dotfiles
+* Associate transformations for storing encrypted dotfiles
 * Provide different solutions for handling dotfiles containing sensitive information
 
 Check also the [blog post](https://deadc0de.re/articles/dotfiles.html), the [example](#example) or how [people are using dotdrop](#people-using-dotdrop) for more.

dotdrop/action.py

@@ -16,6 +16,10 @@ from dotdrop.logger import Logger
 class Cmd:
 
     def __init__(self, key, action):
+        """constructor
+        @key: action key
+        @action: action string
+        """
         self.key = key
         self.action = action
         self.log = Logger()
@@ -33,6 +37,12 @@ class Cmd:
 class Action(Cmd):
 
     def __init__(self, key, kind, action, *args):
+        """constructor
+        @key: action key
+        @kind: type of action (pre or post)
+        @action: action string
+        @args: action arguments
+        """
         super(Action, self).__init__(key, action)
         self.kind = kind
         self.args = args

dotdrop/comparator.py

@@ -16,6 +16,10 @@ import dotdrop.utils as utils
 class Comparator:
 
     def __init__(self, diffopts='', debug=False):
+        """constructor
+        @diffopts: cli switches to pass to unix diff
+        @debug: enable debug
+        """
         self.diffopts = diffopts
         self.debug = debug
         self.log = Logger()

dotdrop/config.py

@@ -78,11 +78,16 @@ class Cfg:
     default_link_by_default = False
     default_workdir = '~/.config/dotdrop'
 
-    def __init__(self, cfgpath):
+    def __init__(self, cfgpath, debug=False):
+        """constructor
+        @cfgpath: path to the config file
+        @debug: enable debug
+        """
         if not os.path.exists(cfgpath):
             raise ValueError('config file does not exist: {}'.format(cfgpath))
         # make sure to have an absolute path to config file
         self.cfgpath = os.path.abspath(cfgpath)
+        self.debug = debug
 
         # init the logger
         self.log = Logger()

dotdrop/dotdrop.py

@@ -430,7 +430,8 @@ def main():
     args = docopt(USAGE, version=VERSION)
 
     try:
-        conf = Cfg(os.path.expanduser(args['--cfg']))
+        conf = Cfg(os.path.expanduser(args['--cfg']),
+                   debug=args['--verbose'])
     except ValueError as e:
         LOG.err('Config format error: {}'.format(str(e)))
         return False
@@ -439,6 +440,7 @@ def main():
     opts['dry'] = args['--dry']
     opts['profile'] = args['--profile']
     opts['safe'] = not args['--force']
+    opts['debug'] = args['--verbose']
     opts['installdiff'] = not args['--nodiff']
     opts['link'] = LinkTypes.NOLINK
     if opts['link_by_default']:
@@ -450,7 +452,6 @@ def main():
     if args['--inv-link'] and opts['link'] == LinkTypes.PARENTS:
         opts['link'] = LinkTypes.NOLINK
 
-    opts['debug'] = args['--verbose']
     opts['variables'] = conf.get_variables(opts['profile'],
                                            debug=opts['debug'])
     opts['showdiff'] = opts['showdiff'] or args['--showdiff']

dotdrop/dotfile.py

@@ -14,25 +14,27 @@ class Dotfile:
                  actions={}, trans_r=None, trans_w=None,
                  link=LinkTypes.NOLINK, cmpignore=[], noempty=False,
                  upignore=[]):
-        # key of dotfile in the config
+        """constructor
+        @key: dotfile key
+        @dst: dotfile dst (in user's home usually)
+        @src: dotfile src (in dotpath)
+        @actions: dictionary of actions to execute for this dotfile
+        @trans_r: transformation to change dotfile before it is installed
+        @trans_w: transformation to change dotfile before updating it
+        @link: link behavior
+        @cmpignore: patterns to ignore when comparing
+        @noempty: ignore empty template if True
+        @upignore: patterns to ignore when updating
+        """
         self.key = key
-        # path where to install this dotfile
         self.dst = dst
-        # path where this dotfile is stored in dotdrop
         self.src = src
-        # if it is a link
         self.link = link
-        # list of actions
         self.actions = actions
-        # read transformation
         self.trans_r = trans_r
-        # write transformation
         self.trans_w = trans_w
-        # pattern to ignore when comparing
         self.cmpignore = cmpignore
-        # do not deploy empty file
         self.noempty = noempty
-        # pattern to ignore when updating
         self.upignore = upignore
 
     def __str__(self):

dotdrop/installer.py

@@ -21,6 +21,18 @@ class Installer:
     def __init__(self, base='.', create=True, backup=True,
                  dry=False, safe=False, workdir='~/.config/dotdrop',
                  debug=False, diff=True, totemp=None, showdiff=False):
+        """constructor
+        @base: directory path where to search for templates
+        @create: create directory hierarchy if missing when installing
+        @backup: backup existing dotfile when installing
+        @dry: just simulate
+        @safe: ask for any overwrite
+        @workdir: where to install template before symlinking
+        @debug: enable debug
+        @diff: diff when installing if True
+        @totemp: deploy to this path instead of dotfile dst if not None
+        @showdiff: show the diff before overwriting (or asking for)
+        """
         self.create = create
         self.backup = backup
         self.dry = dry

dotdrop/jhelpers.py

@@ -9,5 +9,5 @@ import os
 
 
 def exists(path):
-    '''return true when path exists'''
+    """return true when path exists"""
     return os.path.exists(path)

dotdrop/templategen.py

@@ -24,6 +24,11 @@ COMMENT_END = '@@#}'
 class Templategen:
 
     def __init__(self, base='.', variables={}, debug=False):
+        """constructor
+        @base: directory path where to search for templates
+        @variables: dictionary of variables for templates
+        @debug: enable debug
+        """
         self.base = base.rstrip(os.sep)
         self.debug = debug
         self.log = Logger()

dotdrop/updater.py

@@ -22,6 +22,18 @@ class Updater:
 
     def __init__(self, conf, dotpath, profile, variables, dry, safe,
                  iskey=False, debug=False, ignore=[], showpatch=False):
+        """constructor
+        @conf: configuration
+        @dotpath: path where dotfiles are stored
+        @profile: profile selected
+        @variables: dictionary of variables for the templates
+        @dry: simulate
+        @safe: ask for overwrite if True
+        @iskey: will the update be called on keys or path
+        @debug: enable debug
+        @ignore: pattern to ignore when updating
+        @showpatch: show patch if dotfile to update is a template
+        """
         self.conf = conf
         self.dotpath = dotpath
         self.profile = profile

tests/helpers.py

@@ -18,7 +18,7 @@ TMPSUFFIX = '.dotdrop'
 
 
 def clean(path):
-    '''Delete file or directory.'''
+    """Delete file or directory"""
     if not os.path.exists(path):
         return
     if os.path.islink(path):
@@ -30,19 +30,19 @@ def clean(path):
 
 
 def get_string(length):
-    '''Get a random string of length "length".'''
+    """Get a random string of length 'length'"""
     alpha = string.ascii_uppercase + string.digits
     return ''.join(random.choice(alpha) for _ in range(length))
 
 
 def get_tempdir():
-    '''Get a temporary directory'''
+    """Get a temporary directory"""
     return tempfile.mkdtemp(suffix=TMPSUFFIX)
 
 
 def create_random_file(directory, content=None,
                        binary=False, template=False):
-    '''Create a new file in directory with random content.'''
+    """Create a new file in directory with random content"""
     fname = get_string(8)
     mode = 'w'
     if binary:
@@ -65,7 +65,7 @@ def create_random_file(directory, content=None,
 
 
 def edit_content(path, newcontent, binary=False):
-    '''edit file content'''
+    """edit file content"""
     mode = 'w'
     if binary:
         mode = 'wb'
@@ -74,14 +74,14 @@ def edit_content(path, newcontent, binary=False):
 
 
 def create_dir(path):
-    '''Create a directory'''
+    """Create a directory"""
     if not os.path.exists(path):
         os.mkdir(path)
     return path
 
 
 def load_config(confpath, profile):
-    '''Load the config file from path'''
+    """Load the config file from path"""
     conf = Cfg(confpath)
     opts = conf.get_settings()
     opts['dry'] = False
@@ -97,14 +97,14 @@ def load_config(confpath, profile):
 
 
 def get_path_strip_version(path):
-    '''Return the path of a file as stored in yaml config'''
+    """Return the path of a file as stored in yaml config"""
     path = strip_home(path)
     path = path.lstrip('.' + os.sep)
     return path
 
 
 def get_dotfile_from_yaml(dic, path):
-    '''Return the dotfile from the yaml dictionary'''
+    """Return the dotfile from the yaml dictionary"""
     # path is not the file in dotpath but on the FS
     dotfiles = dic['dotfiles']
     src = get_path_strip_version(path)
@@ -113,7 +113,7 @@ def get_dotfile_from_yaml(dic, path):
 
 def create_fake_config(directory, configname='config.yaml',
                        dotpath='dotfiles', backup=True, create=True):
-    '''Create a fake config file'''
+    """Create a fake config file"""
     path = os.path.join(directory, configname)
     workdir = os.path.join(directory, 'workdir')
     with open(path, 'w') as f:

tests/test_compare.py

@@ -50,7 +50,7 @@ class TestCompare(unittest.TestCase):
         return results
 
     def test_compare(self):
-        '''Test the compare function'''
+        """Test the compare function"""
         # setup some directories
         fold_config = os.path.join(os.path.expanduser('~'), '.config')
         create_dir(fold_config)

tests/test_config.py

@@ -24,7 +24,7 @@ class TestConfig(unittest.TestCase):
     CONFIG_NAME = 'config.yaml'
 
     def test_config(self):
-        '''Test the config class'''
+        """Test the config class"""
         tmp = get_tempdir()
         self.assertTrue(os.path.exists(tmp))
         self.addCleanup(clean, tmp)

tests/test_import.py

@@ -27,7 +27,7 @@ class TestImport(unittest.TestCase):
     CONFIG_NAME = 'config.yaml'
 
     def load_yaml(self, path):
-        '''Load yaml to dict'''
+        """Load yaml to dict"""
         self.assertTrue(os.path.exists(path))
         content = ''
         with open(path, 'r') as f:
@@ -35,14 +35,14 @@ class TestImport(unittest.TestCase):
         return content
 
     def assert_file(self, path, conf, profile):
-        '''Make sure "path" has been inserted in "conf" for "profile"'''
+        """Make sure path has been inserted in conf for profile"""
         strip = get_path_strip_version(path)
         self.assertTrue(strip in [x.src for x in conf.get_dotfiles(profile)])
         dsts = [os.path.expanduser(x.dst) for x in conf.get_dotfiles(profile)]
         self.assertTrue(path in dsts)
 
     def assert_in_yaml(self, path, dic, link=False):
-        '''Make sure "path" is in the "dic" representing the yaml file'''
+        """Make sure "path" is in the "dic" representing the yaml file"""
         strip = get_path_strip_version(path)
         self.assertTrue(strip in [x['src'] for x in dic['dotfiles'].values()])
         dsts = [os.path.expanduser(x['dst']) for x in dic['dotfiles'].values()]
@@ -51,7 +51,7 @@ class TestImport(unittest.TestCase):
         self.assertTrue(path in dsts)
 
     def test_import(self):
-        '''Test the import function'''
+        """Test the import function"""
         # on filesystem
         src = get_tempdir()
         self.assertTrue(os.path.exists(src))

tests/test_install.py

@@ -39,7 +39,7 @@ exec bspwm
 
     def fake_config(self, path, dotfiles, profile,
                     dotpath, actions, trans):
-        '''Create a fake config file'''
+        """Create a fake config file"""
         with open(path, 'w') as f:
             f.write('actions:\n')
             for action in actions:
@@ -74,7 +74,7 @@ exec bspwm
         return path
 
     def test_install(self):
-        '''Test the install function'''
+        """Test the install function"""
 
         # dotpath location
         tmp = get_tempdir()

tests/test_listings.py

@@ -26,7 +26,7 @@ class TestListings(unittest.TestCase):
     CONFIG_NAME = 'config.yaml'
 
     def test_listings(self):
-        '''Test the compare function'''
+        """Test the compare function"""
         # setup some directories
         fold_config = os.path.join(os.path.expanduser('~'), '.config')
         create_dir(fold_config)

tests/test_update.py

@@ -23,7 +23,7 @@ class TestUpdate(unittest.TestCase):
     CONFIG_NAME = 'config.yaml'
 
     def test_update(self):
-        '''Test the update function'''
+        """Test the update function"""
         # setup some directories
         fold_config = os.path.join(os.path.expanduser('~'), '.config')
         create_dir(fold_config)