Merge pull request #3 from BumblebeeMan/0.4.x-dev

0.4.0 to main

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+#Pycharm
+.idea/
+
 # Distribution / packaging
 .Python
 build/

CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-All important changes to this vrfy will be documented here.
+All important changes to vrfy will be documented here.
+
+## [0.4.0]
+
+### Added
+- Added command line help menu "vrfy -h".
+
+### Changed
+- Code refactor: Separate CLI and core functionality, introduce data type for result post-processing, and code simplification.
+- Moved cli from vrfy into own class.
+- Cli option: vrfy /path/of/master /path/of/backup no longer supported.
+- Renamed "clone" to "backup" for improved clarity.
+- Changed direction verification option -c to -b.
+- [+] and [-] cli indicators are now based on status of backup directory
+
+### Fixed
+- Fixed bug where directories may be dropped in directory verification.
 
 ## [0.3.1]
 

README.md

@@ -16,19 +16,15 @@ Install **vrfy** using pip:
 pip install vrfy --user
 ```
 
-## Usage
+## Usage the CLI
 ### 1. Verifing that two directories are identical
-Verifing that the contents of '/path/of/clone' are identical to those of '/path/of/master'. For example, '/path/of/master' might be a local backup, whereas '/path/of/clone' might be loaded from cloud storage. 
+Verifing that the contents of '/path/of/backup' are identical to those of '/path/of/master'. For example, '/path/of/master' might be a local backup, whereas '/path/of/backup' might be loaded from cloud storage.
 ```bash
-vrfy /path/of/master /path/of/clone
+vrfy -m /path/of/master -b /path/of/backup -r
 ```
-or
+or (mismatched checksums are printed to console)
 ```bash
-vrfy -m /path/of/master -c /path/of/clone -r
-```
-or (checksums are printed to console)
-```bash
-vrfy -m /path/of/master -c /path/of/clone -r -p
+vrfy -m /path/of/master -b /path/of/backup -r -p
 ```
 
 ### 2. Storing checksums for future verification
@@ -50,7 +46,7 @@ Using option **-r** (recursive) all sub-directories are verified as well:
 ```bash
 vrfy -r -v /path/of/data
 ```
-Using option **-p** (print) all checksums are printed to console for further inspection:
+Using option **-p** (print) all mismatched checksums are printed to console for further inspection:
 ```bash
 vrfy -p -r -v /path/of/data
 ```
@@ -70,9 +66,47 @@ Where "expectedChecksum" can be one of the following:
 ### 4. Other CLI options
 Display version of vrfy:
 ```bash
-vrfy -version
+vrfy --version
 ```
 Display checksum for given file:
 ```bash
 vrfy -p -f /path/of/file/filename
 ```
+Display help:
+```bash
+vrfy -h
+```
+
+## Using the python package
+### Getting started
+```python
+from vrfy.vrfy import vrfy
+vf = vrfy()
+
+# Get version string
+versionStr = vf.GetVersion()
+
+# Verify a single file to an expected checksum
+Result = vf.VerifyFile("/path/and/fileName.xyz", "expectedChecksum")
+
+# Verify contents of a directory to stored checksums
+Result = VerifyFilesAgainstChecksums("path/to/directory")
+
+# Create/store checksum file for later file verification
+Result = WriteChecksumFile("path/to/directory")
+
+# Verify that files within master and backup directories are identical
+Result = VerifyFiles("path/to/directory/master", "path/to/directory/backup")
+```
+where
+```python
+class Result:
+    self.Result: bool            # Determines whether operation was successful (True) or not (False).
+    self.Path: str               # Path the result object corresponds to. 
+    self.PathError: bool         # True: Path is a valid directory, False otherwise.
+    self.MissingFiles: list      # Missing files in (backup) directory that are included in master directory / checksum list.
+    self.AdditionalFiles: list   # Additional files in (backup) directory that are NOT included in master directory / checksum list.
+    self.ChecksumMismatch: list  # List of files with mismachting checksums.
+    self.MasterChecksums: dict   # Dictionary of files within master directory and their checksums.
+    self.BackupChecksums: dict   # Dictionary of files within backup directory and their checksums.
+```

setup.py

@@ -7,24 +7,21 @@
     long_description = file.read()
 
 setup(
-    name = 'vrfy',
-    version = '0.3.1',
-    description = 'Verify with VRFY: Ensure the integrity of your file copies, hash by hash!',
-    long_description = long_description,
+    name='vrfy',
+    version='0.4.0',
+    description='Verify with VRFY: Ensure the integrity of your file copies, hash by hash!',
+    long_description=long_description,
     long_description_content_type='text/markdown',
 
-    py_modules = ["vrfy"],
-    package_dir = {'': 'vrfy'},
+    packages=['vrfy', 'vrfy.cli'],
 
-    author="BumblebeeMan (Dennis Koerner)", 
-    author_email="dennis@bumblebeeman.dev",     
+    author="BumblebeeMan (Dennis Koerner)",
+    author_email="dennis@bumblebeeman.dev",
     url="https://github.com/BumblebeeMan/vrfy",
 
-    #install_requires=["requests >= 2.30.0", "psutil >= 5.9.0"],
-
     entry_points={
         'console_scripts': [
-            'vrfy = vrfy:main',
+            'vrfy = vrfy.cli.vrfyCli:main',
         ],
     },
 
@@ -48,5 +45,6 @@
                  "Programming Language :: Python :: 3.9",
                  "Programming Language :: Python :: 3.10",
                  "Programming Language :: Python :: 3.11",
-                 ]  
+                 "Programming Language :: Python :: 3.12",
+                 ]
 )

vrfy/__init__.py

@@ -1,3 +1 @@
-#!/usr/bin/env python3
 
-from vrfy import vrfy

vrfy/cli/__init__.py

@@ -0,0 +1 @@
+