From 2a84ca5a8c75eb7db556b962c645bed79736887b Mon Sep 17 00:00:00 2001
From: Scott <scott@wannabe.house>
Date: Sun, 23 Jan 2022 10:08:17 -0800
Subject: [PATCH] Added some helpers to file_utils and improved the
 docs/doctests.

---
 file_utils.py | 155 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 151 insertions(+), 4 deletions(-)

diff --git a/file_utils.py b/file_utils.py
index 176b0da..e40a9f5 100644
--- a/file_utils.py
+++ b/file_utils.py
@@ -2,6 +2,7 @@
 
 """Utilities for working with files."""
 
+from dataclasses import dataclass
 import datetime
 import errno
 import hashlib
@@ -13,14 +14,136 @@ import time
 from typing import Optional
 import glob
 from os.path import isfile, join, exists
+from typing import List
 from uuid import uuid4
 
 
 logger = logging.getLogger(__name__)
 
 
-# os.remove(file) you fuckwit.
-# os.path.basename too.
+def remove(path: str) -> None:
+    """Deletes a file.  Raises if path refers to a directory or a file
+    that doesn't exist.
+
+    >>> import os
+    >>> filename = '/tmp/file_utils_test_file'
+    >>> os.system(f'touch {filename}')
+    0
+    >>> does_file_exist(filename)
+    True
+    >>> remove(filename)
+    >>> does_file_exist(filename)
+    False
+
+    """
+    os.remove(path)
+
+
+def delete(path: str) -> None:
+    os.remove(path)
+
+
+def without_extension(path: str) -> str:
+    """Remove one extension from a file or path.
+
+    >>> without_extension('foobar.txt')
+    'foobar'
+
+    >>> without_extension('/home/scott/frapp.py')
+    '/home/scott/frapp'
+
+    >>> without_extension('a.b.c.tar.gz')
+    'a.b.c.tar'
+
+    >>> without_extension('foobar')
+    'foobar'
+
+    """
+    return os.path.splitext(path)[0]
+
+
+def without_all_extensions(path: str) -> str:
+    """Removes all extensions from a path; handles multiple extensions
+    like foobar.tar.gz -> foobar.
+
+    >>> without_all_extensions('/home/scott/foobar.1.tar.gz')
+    '/home/scott/foobar'
+
+    """
+    while '.' in path:
+        path = without_extension(path)
+    return path
+
+
+def get_extension(path: str) -> str:
+    """Extract and return one extension from a file or path.
+
+    >>> get_extension('this_is_a_test.txt')
+    '.txt'
+
+    >>> get_extension('/home/scott/test.py')
+    '.py'
+
+    >>> get_extension('foobar')
+    ''
+
+    """
+    return os.path.splitext(path)[1]
+
+
+def get_all_extensions(path: str) -> List[str]:
+    """Return the extensions of a file or path in order.
+
+    >>> get_all_extensions('/home/scott/foo.tar.gz.1')
+    ['.tar', '.gz', '.1']
+
+    """
+    ret = []
+    while True:
+        ext = get_extension(path)
+        path = without_extension(path)
+        if ext:
+            ret.append(ext)
+        else:
+            ret.reverse()
+            return ret
+
+
+def without_path(filespec: str) -> str:
+    """Returns the base filename without any leading path.
+
+    >>> without_path('/home/scott/foo.py')
+    'foo.py'
+
+    >>> without_path('foo.py')
+    'foo.py'
+
+    """
+    return os.path.split(filespec)[1]
+
+
+def get_path(filespec: str) -> str:
+    """Returns just the path of the filespec by removing the filename and
+    extension.
+
+    >>> get_path('/home/scott/foobar.py')
+    '/home/scott'
+
+    >>> get_path('~scott/frapp.txt')
+    '~scott'
+
+    """
+    return os.path.split(filespec)[0]
+
+
+def get_canonical_path(filespec: str) -> str:
+    """Returns a canonicalized absolute path.
+
+    >>> get_canonical_path('/home/scott/../../home/lynn/../scott/foo.txt')
+    '/usr/home/scott/foo.txt'
+
+    """
+    return os.path.realpath(filespec)
 
 
 def create_path_if_not_exist(path, on_error=None):
@@ -100,14 +223,35 @@ def is_directory(filename: str) -> bool:
 
 
 def is_symlink(filename: str) -> bool:
+    """True if filename is a symlink, False otherwise.
+
+    >>> is_symlink('/tmp')
+    False
+
+    >>> is_symlink('/home')
+    True
+
+    """
     return os.path.islink(filename)
 
 
 def is_same_file(file1: str, file2: str) -> bool:
+    """Returns True if the two files are the same inode.
+
+    >>> is_same_file('/tmp', '/tmp/../tmp')
+    True
+
+    >>> is_same_file('/tmp', '/home')
+    False
+
+    """
     return os.path.samefile(file1, file2)
 
 
 def get_file_raw_timestamps(filename: str) -> Optional[os.stat_result]:
+    """Stats the file and returns an os.stat_result or None on error.
+
+    """
     try:
         return os.stat(filename)
     except Exception as e:
@@ -135,6 +279,9 @@ def get_file_raw_ctime(filename: str) -> Optional[float]:
 
 
 def get_file_md5(filename: str) -> str:
+    """Hashes filename's contents and returns an MD5.
+
+    """
     file_hash = hashlib.md5()
     with open(filename, "rb") as f:
         chunk = f.read(8192)
@@ -249,8 +396,8 @@ def describe_file_mtime(filename: str, *, brief=False) -> Optional[str]:
     return describe_file_timestamp(filename, lambda x: x.st_mtime, brief=brief)
 
 
-def touch_file(filename: str) -> bool:
-    return pathlib.Path(filename).touch()
+def touch_file(filename: str, *, mode: Optional[int] = 0o666) -> bool:
+    return pathlib.Path(filename, mode=mode).touch()
 
 
 def expand_globs(in_filename: str):
-- 
2.45.2