[gentoo-commits] proj/R_overlay:master commit in: roverlay/overlay/pkgdir/distroot/, roverlay/overlay/pkgdir/, roverlay/overlay/

[André Erdmann]

commit:     97b236b9c2deecb109a7bf484f1d795eb9ad74fd
Author:     André Erdmann <dywi <AT> mailerd <DOT> de>
AuthorDate: Thu Aug 29 13:52:57 2013 +0000
Commit:     André Erdmann <dywi <AT> mailerd <DOT> de>
CommitDate: Thu Aug 29 13:52:57 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=97b236b9

roverlay/overlay: comments

---
 roverlay/overlay/base.py                     | 27 +++++++++++++----
 roverlay/overlay/pkgdir/distroot/distroot.py | 45 +++++++++++++++++++++++-----
 roverlay/overlay/pkgdir/packagedir_base.py   |  2 +-
 3 files changed, 60 insertions(+), 14 deletions(-)

diff --git a/roverlay/overlay/base.py b/roverlay/overlay/base.py
index b380e8f..74ab29e 100644
--- a/roverlay/overlay/base.py
+++ b/roverlay/overlay/base.py
@@ -9,8 +9,15 @@ import logging
 import roverlay.util.objects
 
 class OverlayObject ( roverlay.util.objects.ReferenceTree ):
+   """Base object for overlay objects (Overlay, Category, PackageDir) that
+   provides some basic functionality:
 
-   # always keep a (weak) reference to self:
+   * common data variables: name, logger, physical_location, parent_ref
+   * self-referencing: get_ref() (cached unless CACHE_REF is set to False)
+   * back-referencing: get_parent()/get_upper(), set_parent()
+   """
+
+   # by default, keep a (weak) reference to self:
    # (a) Overlay: multiple Category objects use this ref
    # (b) Category: ^ PackageDir ...
    # (c) PackageDir: ^ PackageInfo ...
@@ -18,6 +25,19 @@ class OverlayObject ( roverlay.util.objects.ReferenceTree ):
    CACHE_REF = True
 
    def __init__ ( self, name, logger, directory, parent ):
+      """OverlayObject constructor. Sets up common variables.
+
+      arguments:
+      * name      -- name of the overlay/category/package dir/...
+      * logger    -- parent logger. Passing None results in using the root
+                     logger. The object's logger is then
+                      <parent logger>.getChild ( <name> )
+      * directory -- filesystem location of the object
+      * parent    -- parent object (object that "owns" this object)
+                     This would be None when initializing the overlay's root,
+                     the overlay's root when creating a category and the
+                     category when creating a package dir.
+      """
       super ( OverlayObject, self ).__init__ ( parent )
       self.name   = name
       self.logger = (
@@ -26,9 +46,4 @@ class OverlayObject ( roverlay.util.objects.ReferenceTree ):
       self.physical_location = directory
    # --- end of __init__ (...) ---
 
-   # inherited:
-   #def get_parent
-   #def get_upper
-   #def get_ref
-
 # --- end of OverlayObject ---

diff --git a/roverlay/overlay/pkgdir/distroot/distroot.py b/roverlay/overlay/pkgdir/distroot/distroot.py
index 34f61d9..e38fccd 100644
--- a/roverlay/overlay/pkgdir/distroot/distroot.py
+++ b/roverlay/overlay/pkgdir/distroot/distroot.py
@@ -73,11 +73,21 @@ class DistrootBase ( object ):
    # --- end of __init__ (...) ---
 
    def _atexit_run ( self ):
+      """Performs at-exit actions unless already done."""
       if self.finalize_at_exit:
          self.finalize()
    # --- end of _atexit_run (...) ---
 
    def finalize ( self, backup_distmap=True ):
+      """Finalizes this object, that is
+      (a) disable at-exit behavior
+      (b) clean up the distroot
+      (c) write the distmap (if any)
+
+      arguments:
+      * backup_distmap -- whether to create a copy of the old distmap before
+                          writing the new one
+      """
       # disable finalize_at_exit first so that exceptions cannot trigger
       # _atexit_run()->this function
       #
@@ -225,7 +235,7 @@ class DistrootBase ( object ):
    # --- end of iter_distfiles (...) ---
 
    def _remove_broken_symlinks ( self ):
-      """Recursively remove broken/dead symlinks."""
+      """Recursively removes broken/dead symlinks."""
 
       def recursive_remove ( dirpath, rel_dirpath, rmdir ):
          for item in os.listdir ( dirpath ):
@@ -256,16 +266,22 @@ class DistrootBase ( object ):
    # --- end of _remove_broken_symlinks (...) ---
 
    def _try_remove ( self, dest ):
+      """Tries to remove a file (from the distmap and the filesystem)
+      and suppresses "file does not exist" exceptions.
+
+      arguments:
+      * dest -- file to remove (absolute path)
+      """
       try:
          os.unlink ( dest )
-         if self.distmap is not None:
-            relpath = os.path.relpath ( dest, self.get_root() )
-
       except OSError as e:
-         if e.errno == errno.ENOENT:
-            pass
-         else:
+         if e.errno != errno.ENOENT:
             raise
+      else:
+         if self.distmap is not None:
+            self.distmap.try_remove (
+               os.path.relpath ( dest, self.get_root() )
+            )
    # --- end of _try_remove (...) ---
 
    def get_distdir ( self, ebuild_name ):
@@ -288,14 +304,28 @@ class DistrootBase ( object ):
    # --- end of get_distdir (...) ---
 
    def get_root ( self ):
+      """Returns the filesystem path to this distroot (as str)."""
       return str ( self._root )
    # --- end of get_root (...) ---
 
    def distmap_register ( self, p_info ):
+      """Adds a new entry for the given PackageInfo instance to the distmap.
+
+      arguments:
+      p_info --
+      """
       return self.distmap.add_entry_for ( p_info )
    # --- end of distmap_register (...) ---
 
    def check_integrity ( self ):
+      """Verifies (and regenerates) the distmap:
+
+      (a) creates checksums for all files in the distroot [threaded]
+      (b) compares the checksums with the distmap's entries
+      -> create entries for missing files
+      -> drop entries if checksums do not match
+      (c) drop distmap entries whose file do not exist
+      """
       if self.distmap is not None:
          root      = self.get_root()
          distfiles = set()
@@ -365,6 +395,7 @@ class DistrootBase ( object ):
 
 
 class TemporaryDistroot ( DistrootBase ):
+   # TODO/FIXME: remove this class, it's not used
 
    def __init__ ( self, logger=None ):
       # temporary distroots always use the non-flat distdir layout

diff --git a/roverlay/overlay/pkgdir/packagedir_base.py b/roverlay/overlay/pkgdir/packagedir_base.py
index e8567b9..5196815 100644
--- a/roverlay/overlay/pkgdir/packagedir_base.py
+++ b/roverlay/overlay/pkgdir/packagedir_base.py
@@ -183,7 +183,7 @@ class PackageDirBase ( roverlay.overlay.base.OverlayObject ):
          physical_only=True, pvr=pvr, ebuild_file=efile, name=self.name
       )
 
-      # link distfiles to distmap
+      # link distfiles to the distmap
       for distfile in p.parse_ebuild_distfiles ( self.get_parent().name ):
          self.DISTROOT.set_distfile_owner ( self.get_ref(), distfile )