Metadata-Version: 2.4
Name: path2success
Version: 4.8
Summary: The "path2success" library, is a multi-OS compatible python library, that includes advanced path-related functions.
Author: Joel Horensma
License-Expression: Apache-2.0
Keywords: path,paths,filter,convert bytes,copy,progress bar,ETA
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

The **path2success** library, is a multi-OS compatible python library, that includes advanced path-related functions.

## **The "is_safely_quoted()" Function:**

### **Description:**
**1.)** Checks if the supplied path, is OS-appropriately quoted and has no extra quotes\
**2.)** Returns True, if the supplied path is appropriately quoted (Or appropriately not), otherwise returns False

### **Example Usage:**
import path2success

try:\
    PATH = input('Enter a path: ')\
    print(f'Is safely quoted?: {path2success.is_safely_quoted(PATH)}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "filter_path()" Function:**

### **Description:**
**1.)** Uses path2success' "appropriate_quotes()" function, to remove any prepended and matching quotes, at the end of the supplied path, as well as, replace any OS-inappropriate quotes, in the supplied path, with OS-appropriate ones\
**2.)** The "appropriate_quotes()" function, checks if the supplied path contains a space, if it does,\
the OS-appropriate quotes are added, to the beginning and end of the path, and the OS-appropriately quoted path, is returned to the "filter_path()" function\
**3.)** Uses path2success' "unquote_path()" function, to remove the beginning and end quotes, added by the "appropriate_quotes()" function (if the supplied path contained a space), then returns the unquoted path, to the "filter_path()" function\
**4.)** Converts any OS-specific environment variables, in the supplied path, using the "os" module\
**5.)** Converts any dot-sequences, in the supplied path, and replaces OS-inappropriate slashes, with OS-appropriate slashes, using the "pathlib" module\
**6.)** Returns a filtered and converted path

### **Example Usage:**
import path2success

try:\
    PATH = input('Enter a path: ')\
    FILTERED = path2success.filter_path(PATH)\
    print(f'Filtered path: {FILTERED}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "appropriate_quotes()" Function:**

### **Description:**
**1.)** Removes any prepended quotes, from the supplied path, as well as matching ones, at the end of the path\
**2.)** Replaces any OS-inappropriate quotes, with OS-appropriate ones\
**3.)** Checks if the supplied path contains a space, if it does, the OS-appropriate quotes are added to the beginning and end, of the supplied path\
**4.)** Returns an appropriately quoted path

### **Example Usage:**
import path2success

try:\
    PATH = input('Enter a path: ')\
    if path2success.is_safely_quoted(PATH):\
        print(f'Correct: {path2success.appropriate_quotes(PATH)}')\
    else:\
        print(f'Incorrectly quoted path: {PATH}')\
        print(f'Changed to: {path2success.appropriate_quotes(PATH)}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "unquote_path()" Function:**

### **Description:**
**1.)** If the first and last characters, in the supplied path, are matching quotes, they are removed\
**2.)** Returns an unquoted path

### **Example Usage:**
import path2success

try:\
    PATH = input('Enter a path: ')\
    print(f'Unquoted path: {path2success.unquote_path(PATH)}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "recursive_files_and_bytes_total()" Function:**

### **Description:**
**1.)** Uses path2success' "filter_path()" function, to filter the supplied path\
**2.)** Recursively scans, for the total number of files and bytes, of data, with the help of the "os" module\
**3.)** Returns the total number of files and bytes, of data\
**Note:** path2success' "convert_bytes()" function, can convert the total bytes return value, to kilobytes, megabytes, gigabytes, or even terabytes

### **Example Usage:**
import path2success

try:\
    PATH = input('Enter a path: ')\
    FILES_TOTAL, BYTES_TOTAL = path2success.recursive_files_and_bytes_total(PATH)\
    print(f'Total files: {FILES_TOTAL}')\
    print(f'Total amount of data: {path2success.convert_bytes(BYTES_TOTAL)}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "convert_bytes()" Function:**

### **Description:**
**1.)** Accepts a number of bytes\
**2.)** Returns the converted b, Kb, Mb, Gb, or Tb (Max) value

### **Example Usage:**
import path2success

try:\
    BYTES = input('Enter a number, of bytes: ')\
    print(f'Converted: {path2success.convert_bytes(BYTES)}')\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

## **The "recursive_copy_with_progress()" Function:**

### **Description:**
**1.)** Uses path2success' "filter_path()" function, to filter the supplied source and destination paths\
**2.)** Calculates and displays the total number of files and bytes, of data, to be copied, from the source path, using path2success' "recursive_files_and_bytes_total()" function and it's internal "convert_bytes()" function, along with the help, of the "os" module\
**3.)** Creates a new directory, in the destination path, matching the source path's folder name, using the "os" module, if the folder does not already exist in the destination path, however,\
if the folder does already exist in the destination path, a new directory with a new name is created, in the destination path\
**4.)** Recursively copies all files and folders within the supplied source path, to the supplied destination path, while displaying a live progress bar and ETA until finished, with the help of the "sys" and "time" modules

### **Example Usage:**
import path2success
    
try:\
    SOURCE_PATH = input('Enter a source path: ')\
    DESTINATION_PATH = input('Enter a destination path: ')\
    path2success.recursive_copy_with_progress(SOURCE_PATH, DESTINATION_PATH)\
except Exception as ERROR:\
    print(ERROR)\
input('Press Enter: ')

### **The "recursive_copy_with_progress()" function, CLI Usage:**
python -m path2success recursive_copy_with_progress SOURCE_PATH DESTINATION_PATH
