From a76b0df5436e9f28d4fb32e61f8b14541da3dd18 Mon Sep 17 00:00:00 2001 From: Dan Puttick Date: Mon, 17 Apr 2017 17:22:14 -0500 Subject: [PATCH] Add more docstrings to filecheck.py --- bin/filecheck.py | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/bin/filecheck.py b/bin/filecheck.py index 0817663..8e66ca7 100644 --- a/bin/filecheck.py +++ b/bin/filecheck.py @@ -119,6 +119,12 @@ class Config: class File(FileBase): + """ + Main file object + + Created for each file that is processed by KittenGroomer. Contains all + filetype-specific processing methods. + """ def __init__(self, src_path, dst_path, logger): super(File, self).__init__(src_path, dst_path) @@ -204,6 +210,12 @@ class File(FileBase): self.make_dangerous('Extension does not match expected extensions for this mimetype') def _check_filename(self): + """ + Verify the filename + + If the filename contains any dangerous or specific characters, handle + them appropriately. + """ if self.filename[0] is '.': # TODO: handle dotfiles here pass @@ -214,6 +226,11 @@ class File(FileBase): # TODO: change self.filename and'filename' property? Or should those reflect the values on the source key def check(self): + """ + Main file processing method + + Delegates to various helper methods including filetype-specific checks. + """ if self.main_type in Config.ignored_mimes: self.should_copy = False self.mime_processing_options.get(self.main_type, self.unknown)() @@ -228,6 +245,7 @@ class File(FileBase): self.mime_processing_options.get(self.main_type, self.unknown)() def write_log(self): + """Pass information about the file to self.logger""" props = self.get_all_props() if not self.is_archive: if os.path.exists(self.tempdir_path): @@ -557,7 +575,7 @@ class GroomerLogger(object): self.log_debug_out = os.devnull def _make_log_dir(self, root_dir_path): - """Make the directory in the dest dir that will hold the logs""" + """Create the directory in the dest dir that will hold the logs""" log_dir_path = os.path.join(root_dir_path, 'logs') if os.path.exists(log_dir_path): shutil.rmtree(log_dir_path) @@ -565,6 +583,7 @@ class GroomerLogger(object): return log_dir_path def _add_root_dir(self, root_path): + """Add the root directory to the log""" dirname = os.path.split(root_path)[1] + '/' with open(self.log_path, mode='ab') as lf: lf.write(bytes(dirname, 'utf-8')) @@ -599,12 +618,14 @@ class GroomerLogger(object): self._write_line_to_log(file_string, depth) def add_dir(self, dir_path): + """Add a directory to the log""" path_depth = self._get_path_depth(dir_path) dirname = os.path.split(dir_path)[1] + '/' log_line = '+- ' + dirname self._write_line_to_log(log_line, path_depth) def _format_file_size(self, size): + """Returns a string with the file size and appropriate unit""" file_size = size for unit in ('B', 'KB', 'MB', 'GB'): if file_size < 1024: @@ -614,6 +635,7 @@ class GroomerLogger(object): return str(int(file_size)) + 'GB' def _get_path_depth(self, path): + """Returns the relative path depth compared to root directory""" if self._dst_root_path in path: base_path = self._dst_root_path elif self._src_root_path in path: @@ -623,6 +645,11 @@ class GroomerLogger(object): return path_depth def _write_line_to_log(self, line, indentation_depth): + """ + Write a line to the log + + Pad the line according to the `indentation_depth`. + """ padding = b' ' padding += b'| ' * indentation_depth line_bytes = os.fsencode(line) @@ -703,6 +730,11 @@ class KittenGroomerFileCheck(KittenGroomerBase): return True def list_files_dirs(self, root_dir_path): + """ + Returns a list of all files and directories + + Performs a depth-first traversal of the file tree. + """ queue = [] for path in sorted(os.listdir(root_dir_path), key=lambda x: str.lower(x)): full_path = os.path.join(root_dir_path, path)