Merge pull request #7 from sebastienrousseauhsbc/main

Add unit tests and documentation for helper modules

Author: sebastienrousseauhsbc

encryption_helper/common/strings.py

@@ -1,3 +1,30 @@
-private_key_suffix = 'private-key.pem'
-public_key_suffix = 'public_key.pem'
-encrypted_file_suffix = '.bin'
+"""
+Strings module for the encryption_helper package.
+
+This module provides a collection of string constants used throughout the
+encryption_helper package. These constants include file suffixes for various
+key and encrypted file types.
+
+Attributes:
+    private_key_suffix (str): The file suffix for private key files.
+    public_key_suffix (str): The file suffix for public key files.
+    encrypted_file_suffix (str): The file suffix for encrypted files.
+"""
+
+private_key_suffix = "private-key.pem"
+"""
+str: The file suffix for private key files.
+"""
+
+public_key_suffix = "public_key.pem"
+"""
+str: The file suffix for public key files.
+"""
+
+encrypted_file_suffix = ".bin"
+"""
+str: The file suffix for encrypted files.
+"""
+
+# The module defines string constants for use in the encryption_helper package.
+# These constants help standardize file naming conventions across the package.

encryption_helper/context/context.py

@@ -1,8 +1,11 @@
 """
-context.py
+Context module for the encryption_helper package.
 
 This module provides a Context class for managing application-wide settings and logging.
 It implements the Singleton pattern to ensure only one instance of the context exists.
+
+Classes:
+    Context: A singleton class for managing application context and logging.
 """
 
 import logging

encryption_helper/utils/checks/checks.py

@@ -1,5 +1,41 @@
+"""
+Checks module for the encryption_helper package.
+
+This module provides utility functions to validate input strings. It includes 
+functions to check if strings are `None` or empty.
+
+Functions:
+    str_none_or_empty: Checks if one or more input strings are `None` or empty.
+"""
+
+
 def str_none_or_empty(*argv):
+    """
+    Check if one or more input strings are `None` or empty.
+
+    This function takes a variable number of string arguments and checks each
+    one to determine if it is either `None` or an empty string (including strings
+    that are only whitespace).
+
+    Args:
+        *argv: A variable number of string arguments to be checked.
+
+    Returns:
+        bool: `True` if any of the input strings is `None` or empty; otherwise `False`.
+
+    Examples:
+        >>> str_none_or_empty('test', 'hello', 'world')
+        False
+        >>> str_none_or_empty('test', None, 'world')
+        True
+        >>> str_none_or_empty('test', '', 'world')
+        True
+        >>> str_none_or_empty('test', '   ', 'world')
+        True
+        >>> str_none_or_empty()
+        False
+    """
     for arg in argv:
-        if arg is None or len(arg.strip()) == 0:
+        if arg is None or not isinstance(arg, str) or len(arg.strip()) == 0:
             return True
     return False

encryption_helper/utils/io/read_file.py

@@ -1,24 +1,77 @@
+"""
+Read File module for the encryption_helper package.
+
+This module provides functions to read text files in binary mode. It includes 
+functions to read files given a directory and file name or an absolute file path.
+
+Functions:
+    read_text_in_binary_mode: Reads a file in binary mode given a directory and file name.
+    read_text_in_binary_mode_abs: Reads a file in binary mode given an absolute file path.
+"""
+
 import os
-from rsa.utils.checks import checks
-from rsa.context import context
+from encryption_helper.utils.checks import checks
+from encryption_helper.context import context
 
 
 def read_text_in_binary_mode(directory, file_name):
-    logger = context.Context.getinstance().get_logger()
+    """
+    Read a file in binary mode given a directory and file name.
+
+    This function constructs the absolute file path from the given directory and file name,
+    checks if the inputs are valid, and reads the file in binary mode.
+
+    Args:
+        directory (str): The directory containing the file.
+        file_name (str): The name of the file to be read.
+
+    Returns:
+        bytes: The contents of the file in binary mode.
+
+    Raises:
+        Exception: If one or more arguments are empty.
+        OSError: If there is an error reading the file.
+
+    Examples:
+        >>> data = read_text_in_binary_mode('path/to/dir', 'file.txt')
+        >>> print(data)
+
+    """
+    logger = context.Context.get_instance().get_logger()
     if checks.str_none_or_empty(directory, file_name):
-        logger.exception('One or more arguments are empty')
-        raise Exception('One or more arguments are empty')
+        logger.exception("One or more arguments are empty")
+        raise Exception("One or more arguments are empty")
 
     absolute_file_path = os.path.join(directory, file_name)
     return read_text_in_binary_mode_abs(absolute_file_path)
 
 
 def read_text_in_binary_mode_abs(absolute_file_path):
-    logger = context.Context.getinstance().get_logger()
+    """
+    Read a file in binary mode given an absolute file path.
+
+    This function checks if the input is valid and reads the file in binary mode.
+
+    Args:
+        absolute_file_path (str): The absolute path to the file to be read.
+
+    Returns:
+        bytes: The contents of the file in binary mode.
+
+    Raises:
+        Exception: If the argument is empty.
+        OSError: If there is an error reading the file.
+
+    Examples:
+        >>> data = read_text_in_binary_mode_abs('/path/to/dir/file.txt')
+        >>> print(data)
+
+    """
+    logger = context.Context.get_instance().get_logger()
     if checks.str_none_or_empty(absolute_file_path):
-        logger.exception('One or more arguments are empty')
-        raise Exception('One or more arguments are empty')
+        logger.exception("One or more arguments are empty")
+        raise Exception("One or more arguments are empty")
 
-    logger.info('Reading from file : {0}'.format(absolute_file_path))
+    logger.info("Reading from file : {0}".format(absolute_file_path))
     with open(absolute_file_path, "rb") as f:
         return f.read()

encryption_helper/utils/io/write_file.py

@@ -1,27 +1,82 @@
-from rsa.utils.checks import checks
-from rsa.context import context
+"""
+Write File module for the encryption_helper package.
+
+This module provides functions to write text files in binary mode. It includes 
+functions to write files given a directory and file name or an absolute file path.
+
+Functions:
+    write_text_in_binary_mode: Writes text to a file in binary mode given a directory and file name.
+    write_text_in_binary_mode_abs: Writes text to a file in binary mode given an absolute file path.
+"""
+
 import os
+from encryption_helper.utils.checks import checks
+from encryption_helper.context import context
 
 
 def write_text_in_binary_mode(directory, file_name, text):
-    logger = context.Context.getinstance().get_logger()
+    """
+    Write text to a file in binary mode given a directory and file name.
+
+    This function constructs the absolute file path from the given directory and file name,
+    checks if the inputs are valid, and writes the text to the file in binary mode.
+
+    Args:
+        directory (str): The directory containing the file.
+        file_name (str): The name of the file to be written.
+        text (bytes): The text to be written to the file.
+
+    Returns:
+        str: The absolute file path of the written file.
+
+    Raises:
+        Exception: If one or more arguments are empty.
+        OSError: If there is an error writing to the file.
+
+    Examples:
+        >>> path = write_text_in_binary_mode('path/to/dir', 'file.txt', b'test data')
+        >>> print(path)
+
+    """
+    logger = context.Context.get_instance().get_logger()
     if checks.str_none_or_empty(directory, file_name, text):
-        logger.exception('One or more arguments are empty')
-        raise Exception('One or more arguments are empty')
+        logger.exception("One or more arguments are empty")
+        raise Exception("One or more arguments are empty")
 
     absolute_file_path = os.path.join(directory, file_name)
     return write_text_in_binary_mode_abs(absolute_file_path, text)
 
 
 def write_text_in_binary_mode_abs(absolute_file_path, text):
-    logger = context.Context.getinstance().get_logger()
+    """
+    Write text to a file in binary mode given an absolute file path.
+
+    This function checks if the inputs are valid and writes the text to the file in binary mode.
+
+    Args:
+        absolute_file_path (str): The absolute path to the file to be written.
+        text (bytes): The text to be written to the file.
+
+    Returns:
+        str: The absolute file path of the written file.
+
+    Raises:
+        Exception: If one or more arguments are empty.
+        OSError: If there is an error writing to the file.
+
+    Examples:
+        >>> path = write_text_in_binary_mode_abs('/path/to/dir/file.txt', b'test data')
+        >>> print(path)
+
+    """
+    logger = context.Context.get_instance().get_logger()
     if checks.str_none_or_empty(absolute_file_path, text):
-        logger.exception('One or more arguments are empty')
-        raise Exception('One or more arguments are empty')
+        logger.exception("One or more arguments are empty")
+        raise Exception("One or more arguments are empty")
 
-    logger.info('Writing to file : {0}'.format(absolute_file_path))
-    with open(absolute_file_path, 'wb') as f:
+    logger.info("Writing to file : {0}".format(absolute_file_path))
+    with open(absolute_file_path, "wb") as f:
         f.write(text)
-    logger.info('Writing to file complete')
+    logger.info("Writing to file complete")
 
     return absolute_file_path

pyproject.toml

@@ -25,6 +25,7 @@ pycryptodome = "^3.20.0"
 
 [tool.poetry.dev-dependencies]
 pytest = "^8.3.2"
+pytest-mock = "^3.14.0"
 
 [tool.poetry.scripts]
 encryption-helper = "encryption_helper.__main__:main"

tests/__init__.py

@@ -0,0 +1,4 @@
+# tests/__init__.py
+
+# This file can be left empty, but it must exist to make Python treat the
+# directory as a package, which is necessary for relative imports.

tests/common/__init__.py

@@ -0,0 +1,25 @@
+import unittest
+from encryption_helper.common.strings import (
+    private_key_suffix,
+    public_key_suffix,
+    encrypted_file_suffix,
+)
+
+
+class TestStrings(unittest.TestCase):
+
+    def test_private_key_suffix(self):
+        # Test the private key suffix
+        self.assertEqual(private_key_suffix, "private-key.pem")
+
+    def test_public_key_suffix(self):
+        # Test the public key suffix
+        self.assertEqual(public_key_suffix, "public_key.pem")
+
+    def test_encrypted_file_suffix(self):
+        # Test the encrypted file suffix
+        self.assertEqual(encrypted_file_suffix, ".bin")
+
+
+if __name__ == "__main__":
+    unittest.main()