Added comments to every function

Former-commit-id: 6b8f15be379d51af5ced2449b1db7749d528dcf4 [formerly 87ae61ae30]
Former-commit-id: f5919588095deb509e899cff4e024dd76affbbce

bin/sshync.py

@@ -10,7 +10,7 @@ from sys import exit as s_exit
 
 # utility functions
 
-def get_titles_mods(_directory, _destination, _user_data):
+def get_titles_mods(_directory, _destination, _user_data):  # fetches and returns lists of titles and their mod times
     _title_list, _mod_list = [], []
     Path(path.expanduser('~/.config/sshync')).mkdir(0o700, parents=True, exist_ok=True)  # create config directory
     # local fetching
@@ -37,7 +37,8 @@ def get_titles_mods(_directory, _destination, _user_data):
     return _title_list, _mod_list
 
 
-def sort_titles_mods(_list_1, _list_2):
+def sort_titles_mods(_list_1, _list_2):  # creates and returns two lists (of titles and mod times) generated by sorting
+    # information from two different, provided lists
     _title_list_2_sorted, _mod_list_2_sorted = [], []
     # title sorting
     for _title in _list_1[0]:
@@ -52,12 +53,12 @@ def sort_titles_mods(_list_1, _list_2):
     return _title_list_2_sorted, _mod_list_2_sorted
 
 
-def make_profile(_profile_dir, _local_dir, _remote_dir, _identity, _ip, _port, _user):
+def make_profile(_profile_dir, _local_dir, _remote_dir, _identity, _ip, _port, _user):  # creates a sshync job profile
     open(_profile_dir, 'w').write(_user + '\n' + _ip + '\n' + _port + '\n' + _local_dir + '\n' + _remote_dir + '\n' +
                                   _identity + '\n')
 
 
-def get_profile(_profile_dir):
+def get_profile(_profile_dir):  # returns a list of data read from a sshync job profile
     try:
         _profile_data = open(_profile_dir).readlines()
     except (FileNotFoundError, IndexError):
@@ -74,7 +75,7 @@ def get_profile(_profile_dir):
     return _user, _ip, _port, _local_dir, _remote_dir, _identity
 
 
-def run_profile(_profile_dir):
+def run_profile(_profile_dir):  # runs a sshync job profile
     _user_data = get_profile(_profile_dir)
     _remote_titles_mods_saver = get_titles_mods(_user_data[4], 'r', _user_data)  # saved to prevent re-walking directory
     _index_l = sort_titles_mods(_remote_titles_mods_saver, get_titles_mods(_user_data[3], 'l', _user_data))

bin/sshyp.py

@@ -13,7 +13,7 @@ from sys import argv, exit as s_exit
 from textwrap import fill
 
 
-# utility functions
+# BELOW - utility functions
 
 def entry_list_gen(_directory=path.expanduser('~/.local/share/sshyp/')):  # generates and prints full entry list
     print('\n\u001b[38;5;0;48;5;15msshyp entries:\u001b[0m\n')
@@ -59,7 +59,7 @@ def entry_list_gen(_directory=path.expanduser('~/.local/share/sshyp/')):  # gene
                 print('\u001b[38;5;9m-empty directory-\u001b[0m\n')
 
 
-def entry_reader(_decrypted_entry):
+def entry_reader(_decrypted_entry):  # displays the contents of an entry in a readable format
     _entry_lines, _notes_flag = open(_decrypted_entry, 'r').readlines(), 0
     print()
     for _num in range(len(_entry_lines)):
@@ -91,7 +91,7 @@ def replace_line(file_name, line_num, text):  # replaces text in a given line wi
     open(file_name, 'w').writelines(_lines)
 
 
-def entry_name_fetch(_entry_name_location):
+def entry_name_fetch(_entry_name_location):  # fetches and returns entry name from user input or from provided argument
     if type(_entry_name_location) == str:
         entry_list_gen()
         _entry_name = str(input(_entry_name_location))
@@ -105,7 +105,7 @@ def entry_name_fetch(_entry_name_location):
         return _entry_name
 
 
-def shm_gen(_tmp_dir=path.expanduser('~/.config/sshyp/tmp/')):
+def shm_gen(_tmp_dir=path.expanduser('~/.config/sshyp/tmp/')):  # creates a temporary directory for entry editing
     _shm_folder_gen = ''.join(SystemRandom().choice(string.ascii_letters + string.digits)
                               for _ in range(randint(10, 30)))
     _shm_entry_gen = ''.join(SystemRandom().choice(string.ascii_letters + string.digits)
@@ -114,7 +114,7 @@ def shm_gen(_tmp_dir=path.expanduser('~/.config/sshyp/tmp/')):
     return _shm_folder_gen, _shm_entry_gen
 
 
-def pass_gen():
+def pass_gen():  # generates and returns a random password based on user-specified options
     def _pass_gen_function(__complexity, __length):
         if __complexity.lower() == 's':
             __character_pool = string.ascii_letters + string.digits
@@ -142,13 +142,14 @@ def pass_gen():
     return _gen
 
 
-def encrypt(_shm_folder, _shm_entry, _location):
+def encrypt(_shm_folder, _shm_entry, _location):  # encrypts an entry and cleans up the temporary files
     system(f"{gpg} -qr {str(gpg_id)} -e '{tmp_dir}{_shm_folder}/{_shm_entry}'")
     move(f"{tmp_dir}{_shm_folder}/{_shm_entry}.gpg", f"{directory}{_location}.gpg")
     rmtree(f"{tmp_dir}{_shm_folder}")
 
 
 def decrypt(_entry_dir, _shm_folder, _shm_entry, _gpg_command, _tmp_dir=path.expanduser('~/.config/sshyp/tmp/')):
+    # decrypts an entry to a temporary directory
     if _shm_folder == 0 and _shm_entry == 0:
         _command = f"{_gpg_command} -qd --output /dev/null {path.expanduser('~/.config/sshyp/lock.gpg')}"
     else:
@@ -160,7 +161,7 @@ def decrypt(_entry_dir, _shm_folder, _shm_entry, _gpg_command, _tmp_dir=path.exp
         s_exit(1)
 
 
-def edit_note(_shm_folder, _shm_entry):
+def edit_note(_shm_folder, _shm_entry):  # edits the note attached to an entry
     lines = open(f"{tmp_dir}{_shm_folder}/{_shm_entry}").readlines()
     open(f"{tmp_dir}{_shm_folder}/{_shm_entry}", 'w').writelines(lines[0:3])
     open(f"{tmp_dir}{_shm_folder}/{_shm_entry}-n", 'w').writelines(lines[3:])
@@ -170,6 +171,7 @@ def edit_note(_shm_folder, _shm_entry):
 
 
 def copy_name_check(_port, _username_ssh, _ip, _client_device_name):
+    # attempts to connect to the user's server via ssh to register the device for syncing
     _command = f"ssh -o ConnectTimeout=3 -i '{path.expanduser('~/.ssh/sshyp')}' -p {_port} {_username_ssh}@{_ip} " \
                f"\"touch '/home/{_username_ssh}/.config/sshyp/devices/{_client_device_name}'\""
     try:
@@ -183,7 +185,7 @@ def copy_name_check(_port, _username_ssh, _ip, _client_device_name):
     open(path.expanduser('~/.config/sshyp/ssh-error'), 'w').write('0')
     return 0
 
-# argument-specific functions
+# BELOW - argument-specific functions
 
 
 def tweak():  # runs configuration wizard

bin/sshypRemote.py

@@ -9,7 +9,7 @@ from shutil import rmtree
 
 # utility functions
 
-def delete(_file_path):
+def delete(_file_path):  # deletes an entry or folder, should be run remotely via ssh
     if _file_path.endswith('/'):
         try:
             rmtree(f"{expanduser('~/.local/share/sshyp/')}{_file_path}")
@@ -24,7 +24,7 @@ def delete(_file_path):
         open(f"{expanduser('~/.config/sshyp/deleted/')}{_file_path.replace('/', '@')}^&*{_device_name}", 'w')
 
 
-def deletion_check(_client_device_name):
+def deletion_check(_client_device_name):  # creates a list of entries and folders to be deleted from a local machine
     open(expanduser('~/.config/sshyp/deletion_database'), 'w').write('')
     for _file in listdir(expanduser('~/.config/sshyp/deleted')):
         _file_path = _file.replace('@', '/').split('^&*')[0]
@@ -37,7 +37,7 @@ def deletion_check(_client_device_name):
             open(expanduser('~/.config/sshyp/deletion_database'), 'a').write(_file_path + '\n')
 
 
-def folder_check():
+def folder_check():  # creates a list of folders to be compared with those of a local machine
     open(expanduser('~/.config/sshyp/folder_database'), 'w').write('')
     for _root, _directories, _files in walk(expanduser('~/.local/share/sshyp')):
         for _dir in _directories: