Accept a single file as input (#19)

* Return checksum for single file as input

* Add warning that ignore/include flags are ignored for single file input

* Tests for single file as input

* Update documentation to reflect single-file ability

* Ensure input to gather_file_paths is a directory

* Test directory requirement for gather_file_paths

---------

Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com>

Author: thompsonmj

README.md

@@ -1,6 +1,5 @@
 # sum-buddy
-Command-line package to generate a CSV with filepath, filename, and checksum for contents of given directory.
-
+Command-line package to generate a CSV with filepath, filename, and checksum for contents of a given directory or a single file.
 
 ## Requirements
 Python 3.7+
@@ -18,12 +17,12 @@ pip install git+https://github.com/Imageomics/sum-buddy
 ### Command Line Usage
 
 ```
-usage: sum-buddy [-h] [-o OUTPUT_FILE] [-i IGNORE_FILE | -H] [-a ALGORITHM] input_dir
+usage: sum-buddy [-h] [-o OUTPUT_FILE] [-i IGNORE_FILE | -H] [-a ALGORITHM] input_path
 
-Generate CSV with filepath, filename, and checksums for all files in a given directory
+Generate CSV with filepath, filename, and checksums for all files in a given directory (or a single file)
 
 positional arguments:
-  input_dir             Directory to traverse for files
+  input_path             File or directory to traverse for files
 
 options:
   -h, --help            show this help message and exit
@@ -34,6 +33,8 @@ options:
   -H, --include-hidden  Include hidden files
   -a ALGORITHM, --algorithm ALGORITHM
                         Hash algorithm to use (default: md5; available: ripemd160, sha3_224, sha512_224, blake2b, sha384, sha256, sm3, sha3_256, shake_256, sha512, sha1, sha224, md5, md5-sha1, sha3_384, sha3_512, sha512_256, shake_128, blake2s)
+  -l LENGTH, --length LENGTH
+                        Length of the digest for SHAKE (required) or BLAKE (optional) algorithms in bytes
 ```
 
 > Note: The available algorithms are determined by those available to `hashlib` and may vary depending on your system and OpenSSL version, so the set shown on your system with `sum-buddy -h` may be different from above. At a minimum, it should include: `{blake2s, blake2b, md5, sha1, sha224, sha256, sha384, sha512, sha3_224, sha3_256, sha3_384, sha3_512, shake_128, shake_256}`, which is given by `hashlib.algorithms_guaranteed`.
@@ -136,24 +137,24 @@ We expose three functions to be used in your Python code:
 ```python
 from sumbuddy import get_checksums, gather_file_paths, checksum_file
 
-input_dir = "examples/example_content"
+input_path = "examples/example_content"
 output_file = "examples/checksums.csv"
 include_hidden = True        # Optional
 ignore_file = "examples/.sbignore_except_txt"   # Optional
 alg = "md5"           # Optional, possible inputs include list elements returned by hashlib.algorithms_available
 
 # To generate checksums and save to a CSV file
-get_checksums(input_dir, output_file, ignore_file=ignore_file, algorithm=alg)
-# or get_checksums(input_dir, output_file, ignore_hidden=ignore_hidden)
-# or get_checksums(input_dir, output_file)
+get_checksums(input_path, output_file, ignore_file=ignore_file, algorithm=alg)
+# or get_checksums(input_path, output_file, ignore_hidden=ignore_hidden)
+# or get_checksums(input_path, output_file)
 
 # outputs status bar followed by
 # Checksums written to examples/checksums.csv
 
 # To gather a list of file paths according to ignore/include patterns
-file_paths = gather_file_paths(input_dir, ignore_file=ignore_file)
-# or file_paths = gather_file_paths(input_dir, include_hidden=include_hidden)
-# or file_paths = gather_file_paths(input_dir)
+file_paths = gather_file_paths(input_path, ignore_file=ignore_file)
+# or file_paths = gather_file_paths(input_path, include_hidden=include_hidden)
+# or file_paths = gather_file_paths(input_path)
 
 # To calculate the checksum of a single file
 sum = checksum_file("examples/example_content/file.txt", algorithm=alg)

src/sumbuddy/__main__.py

@@ -9,24 +9,32 @@
 import sys
 import os
 
-def get_checksums(input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm='md5', length=None):
+def get_checksums(input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm='md5', length=None):
     """
     Generate a CSV file with the filepath, filename, and checksum of all files in the input directory according to patterns to ignore. Checksum column is labeled by the selected algorithm (e.g., 'md5' or 'sha256').
     
     Parameters:
     ------------
-    input_directory - String. Directory to traverse for files.
+    input_path - String. File or directory to traverse for files.
     output_filepath - String [optional]. Filepath for the output CSV file. Defaults to None, i.e. output will be to stdout.
     ignore_file - String [optional]. Filepath for the ignore patterns file.
     include_hidden - Boolean [optional]. Whether to include hidden files. Default is False.
     algorithm - String. Algorithm to use for checksums. Default: 'md5', see options with 'hashlib.algorithms_available'.
     length - Integer [conditionally optional]. Length of the digest for SHAKE (required) and BLAKE (optional) algorithms in bytes.
     """
     mapper = Mapper()
-    try:
-        file_paths = mapper.gather_file_paths(input_directory, ignore_file=ignore_file, include_hidden=include_hidden)
-    except (EmptyInputDirectoryError, NoFilesAfterFilteringError) as e:
-        sys.exit(str(e))
+
+    if os.path.isfile(input_path):
+        file_paths = [input_path]
+        if ignore_file:
+            print("Warning: --ignore-file (-i) flag is ignored when input is a single file.")
+        if include_hidden:
+            print("Warning: --include-hidden (-H) flag is ignored when input is a single file.")
+    else:
+        try:
+            file_paths = mapper.gather_file_paths(input_path, ignore_file=ignore_file, include_hidden=include_hidden)
+        except (EmptyInputDirectoryError, NoFilesAfterFilteringError) as e:
+            sys.exit(str(e))
 
     # Exclude the output file from being hashed
     if output_filepath:
@@ -41,7 +49,7 @@ def get_checksums(input_directory, output_filepath=None, ignore_file=None, inclu
         writer.writerow(["filepath", "filename", f"{algorithm}"])
 
         disable_tqdm = output_filepath is None
-        for file_path in tqdm(file_paths, desc=f"Calculating {algorithm} checksums on {input_directory}", disable=disable_tqdm):
+        for file_path in tqdm(file_paths, desc=f"Calculating {algorithm} checksums on {input_path}", disable=disable_tqdm):
             checksum = hasher.checksum_file(file_path, algorithm=algorithm, length=length)
             writer.writerow([file_path, os.path.basename(file_path), checksum])
 
@@ -50,14 +58,14 @@ def get_checksums(input_directory, output_filepath=None, ignore_file=None, inclu
             output_stream.close()
 
     if output_filepath:     
-        print(f"{algorithm} checksums for {input_directory} written to {output_filepath}")
+        print(f"{algorithm} checksums for {input_path} written to {output_filepath}")
 
 def main():
 
     available_algorithms = ', '.join(hashlib.algorithms_available)
-        
-    parser = argparse.ArgumentParser(description="Generate CSV with filepath, filename, and checksums for all files in a given directory")
-    parser.add_argument("input_dir", help="Directory to traverse for files")
+    
+    parser = argparse.ArgumentParser(description="Generate CSV with filepath, filename, and checksums for all files in a given directory (or a single file)")
+    parser.add_argument("input_path", help="File or directory to traverse for files")
     parser.add_argument("-o", "--output-file", help="Filepath for the output CSV file; defaults to stdout", default=None)
     group = parser.add_mutually_exclusive_group()
     group.add_argument("-i", "--ignore-file", help="Filepath for the ignore patterns file")
@@ -76,7 +84,7 @@ def main():
             sys.exit("Exited without executing")
 
     try:
-        get_checksums(args.input_dir, args.output_file, args.ignore_file, args.include_hidden, args.algorithm, args.length)
+        get_checksums(args.input_path, args.output_file, args.ignore_file, args.include_hidden, args.algorithm, args.length)
     except (LengthUsedForFixedLengthHashError) as e:
         sys.exit(str(e))
 

src/sumbuddy/exceptions.py

@@ -3,6 +3,11 @@ def __init__(self, input_directory):
         message = f"The directory {input_directory} and subdirectories (if any) contain no files. \nPlease provide a directory with files."
         super().__init__(message)
 
+class NotADirectoryError(Exception):
+    def __init__(self, input_directory):
+        message = f"The input path '{input_directory}' is not a directory. \nPlease provide a directory with files."
+        super().__init__(message)
+
 class NoFilesAfterFilteringError(Exception):
     def __init__(self, input_directory, ignore_file):
         message = f"The directory {input_directory} contains files, but all are filtered out. \nCheck patterns in your {ignore_file} file and/or hidden files settings."

src/sumbuddy/mapper.py

@@ -1,6 +1,6 @@
 import os
 from sumbuddy.filter import Filter
-from sumbuddy.exceptions import EmptyInputDirectoryError, NoFilesAfterFilteringError
+from sumbuddy.exceptions import EmptyInputDirectoryError, NoFilesAfterFilteringError, NotADirectoryError
 
 class Mapper:
     def __init__(self):
@@ -39,6 +39,10 @@ def gather_file_paths(self, input_directory, ignore_file=None, include_hidden=Fa
         ---------
         file_paths - List. Files in input_directory that are not ignored.
         """
+
+        if not os.path.isdir(input_directory):
+            raise NotADirectoryError(input_directory)
+        
         self.reset_filter(ignore_file=ignore_file, include_hidden=include_hidden)
 
         file_paths = []

tests/test_getChecksums.py

@@ -10,20 +10,43 @@
 class TestGetChecksums(unittest.TestCase):
 
     def setUp(self):
-        self.input_directory = 'input_dir'
+        self.input_path = 'input_path'
         self.output_filepath = 'output.csv'
         self.ignore_file = 'ignore_patterns.txt'
         self.mock_file_paths = ['file1.txt', 'file2.txt', '.hidden_file']
         self.algorithm = 'md5'
         self.dummy_checksum = 'dummychecksum'
 
+    @patch('os.path.isfile', return_value=True)
+    @patch('builtins.open', new_callable=mock_open)
+    @patch('sumbuddy.Hasher.checksum_file', return_value='dummychecksum')
+    def test_get_checksums_single_file_to_file(self, mock_checksum, mock_open, mock_isfile):
+        get_checksums(self.input_path, self.output_filepath, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
+        
+        mock_open.assert_called_with(self.output_filepath, 'w', newline='')
+        handle = mock_open()
+        handle.write.assert_any_call('filepath,filename,md5\r\n')
+        handle.write.assert_any_call(f'{self.input_path},{os.path.basename(self.input_path)},dummychecksum\r\n')
+
+    @patch('os.path.isfile', return_value=True)
+    @patch('builtins.open', new_callable=mock_open)
+    @patch('sumbuddy.Hasher.checksum_file', return_value='dummychecksum')
+    def test_get_checksums_single_file_to_stdout(self, mock_checksum, mock_open, mock_isfile):
+        output_stream = StringIO()
+        with patch('sys.stdout', new=output_stream):
+            get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
+            
+        output = output_stream.getvalue()
+        self.assertIn('filepath,filename,md5', output)
+        self.assertIn(f'{self.input_path},{os.path.basename(self.input_path)},dummychecksum', output)
+
     @patch('os.path.abspath', side_effect=lambda x: x)
     @patch('os.path.exists', return_value=True)
     @patch('builtins.open', new_callable=mock_open)
     @patch('sumbuddy.Mapper.gather_file_paths', return_value=['file1.txt', 'file2.txt'])
     @patch('sumbuddy.Hasher.checksum_file', side_effect=lambda x, **kwargs: 'dummychecksum')
     def test_get_checksums_to_file(self, mock_checksum, mock_gather, mock_open, mock_exists, mock_abspath):
-        get_checksums(self.input_directory, self.output_filepath, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
+        get_checksums(self.input_path, self.output_filepath, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
 
         mock_open.assert_called_with(self.output_filepath, 'w', newline='')
         handle = mock_open()
@@ -39,7 +62,7 @@ def test_get_checksums_to_file(self, mock_checksum, mock_gather, mock_open, mock
     def test_get_checksums_to_stdout(self, mock_checksum, mock_gather, mock_open, mock_exists, mock_abspath):
         output_stream = StringIO()
         with patch('sys.stdout', new=output_stream):
-            get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
+            get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
 
         output = output_stream.getvalue()
         self.assertIn('filepath,filename,md5', output)
@@ -52,17 +75,17 @@ def test_get_checksums_to_stdout(self, mock_checksum, mock_gather, mock_open, mo
     @patch('sumbuddy.Mapper.gather_file_paths', return_value=['file1.txt', 'file2.txt'])
     @patch('sumbuddy.Hasher.checksum_file', side_effect=lambda x, **kwargs: 'dummychecksum')
     def test_get_checksums_with_ignore_file(self, mock_checksum, mock_gather, mock_open, mock_exists, mock_abspath):
-        get_checksums(self.input_directory, output_filepath=None, ignore_file=self.ignore_file, include_hidden=False, algorithm=self.algorithm)
-        mock_gather.assert_called_with(self.input_directory, ignore_file=self.ignore_file, include_hidden=False)
+        get_checksums(self.input_path, output_filepath=None, ignore_file=self.ignore_file, include_hidden=False, algorithm=self.algorithm)
+        mock_gather.assert_called_with(self.input_path, ignore_file=self.ignore_file, include_hidden=False)
 
     @patch('os.path.abspath', side_effect=lambda x: x)
     @patch('os.path.exists', return_value=True)
     @patch('builtins.open', new_callable=mock_open)
     @patch('sumbuddy.Mapper.gather_file_paths', return_value=['file1.txt', 'file2.txt', '.hidden_file'])
     @patch('sumbuddy.Hasher.checksum_file', side_effect=lambda x, **kwargs: 'dummychecksum')
     def test_get_checksums_include_hidden(self, mock_checksum, mock_gather, mock_open, mock_exists, mock_abspath):
-        get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=True, algorithm=self.algorithm)
-        mock_gather.assert_called_with(self.input_directory, ignore_file=None, include_hidden=True)
+        get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=True, algorithm=self.algorithm)
+        mock_gather.assert_called_with(self.input_path, ignore_file=None, include_hidden=True)
 
     @patch('os.path.abspath', side_effect=lambda x: x)
     @patch('os.path.exists', return_value=True)
@@ -71,11 +94,11 @@ def test_get_checksums_include_hidden(self, mock_checksum, mock_gather, mock_ope
     @patch('sumbuddy.Hasher.checksum_file', side_effect=lambda x, **kwargs: 'dummychecksum')
     def test_get_checksums_different_algorithm(self, mock_checksum, mock_gather, mock_open, mock_exists, mock_abspath):
         algorithm = 'sha256'
-        get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=algorithm)
+        get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=algorithm)
 
         output_stream = StringIO()
         with patch('sys.stdout', new=output_stream):
-            get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=algorithm)
+            get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=algorithm)
 
         output = output_stream.getvalue()
         self.assertIn(f'filepath,filename,{algorithm}', output)
@@ -89,7 +112,7 @@ def test_get_checksums_different_algorithm(self, mock_checksum, mock_gather, moc
     def test_get_checksums_empty_directory(self, mock_gather, mock_open, mock_exists, mock_abspath):
         output_stream = StringIO()
         with patch('sys.stdout', new=output_stream):
-            get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
+            get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm=self.algorithm)
 
         output = output_stream.getvalue()
         self.assertIn('filepath,filename,md5', output)
@@ -100,7 +123,7 @@ def test_get_checksums_empty_directory(self, mock_gather, mock_open, mock_exists
     @patch('sumbuddy.Mapper.gather_file_paths', return_value=['file1.txt', 'file2.txt'])
     def test_get_checksums_invalid_algorithm(self, mock_gather, mock_open, mock_exists, mock_abspath):
         with self.assertRaises(ValueError):
-            get_checksums(self.input_directory, output_filepath=None, ignore_file=None, include_hidden=False, algorithm='invalid_alg')
+            get_checksums(self.input_path, output_filepath=None, ignore_file=None, include_hidden=False, algorithm='invalid_alg')
 
 if __name__ == '__main__':
     unittest.main()

tests/test_mapper.py

@@ -4,7 +4,7 @@
 from unittest.mock import patch, mock_open, MagicMock
 from sumbuddy.mapper import Mapper
 from sumbuddy.filter import Filter
-from sumbuddy.exceptions import EmptyInputDirectoryError, NoFilesAfterFilteringError
+from sumbuddy.exceptions import EmptyInputDirectoryError, NoFilesAfterFilteringError, NotADirectoryError
 
 class TestMapper(unittest.TestCase):
     @patch('sumbuddy.filter.open', new_callable=mock_open, read_data="# This is a sample ignore file\n")
@@ -90,6 +90,12 @@ def test_gather_file_paths_filtered_files(self):
 
             with self.assertRaises(NoFilesAfterFilteringError):
                 mapper.gather_file_paths(temp_dir, ignore_file=ignore_file_path)
+    
+    def test_gather_file_paths_input_not_a_directory(self):
+        mapper = Mapper()
+        with tempfile.NamedTemporaryFile() as temp_file:
+            with self.assertRaises(NotADirectoryError):
+                mapper.gather_file_paths(temp_file.name)
 
 
 if __name__ == '__main__':