voussoir/voussoirkit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Docstring updates for many functions.

Browse source
This commit is contained in:
voussoir 2021-05-18 17:48:57 -07:00
parent 375b00bfd5
commit 2d8d51a4f1
No known key found for this signature in database
GPG key ID: 5F7554F8C26DACCB
1 changed files with 28 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
voussoirkit/spinal.py
View file

@ -205,7 +205,7 @@ def copy_dir(
thread catch ctrl+c to set the stop_event, so the copy can stop cleanly. thread catch ctrl+c to set the stop_event, so the copy can stop cleanly.
validate_hash: validate_hash:
Passed directly into each `copy_file`. Passed into each `copy_file` as `validate_hash`.
Returns a dotdict containing at least `source`, `destination`, Returns a dotdict containing at least `source`, `destination`,
and `written_bytes`. (Written bytes is 0 if all files already existed.) and `written_bytes`. (Written bytes is 0 if all files already existed.)
@ -570,7 +570,7 @@ def copy_file(
def do_nothing(*args, **kwargs): def do_nothing(*args, **kwargs):
''' '''
Used by other functions as the default callback. Used by other functions as the default callback. It does nothing!
''' '''
return return
@ -621,6 +621,11 @@ def hash_file(
hash_class: hash_class:
Should be a hashlib class or a callable that returns an instance of one. Should be a hashlib class or a callable that returns an instance of one.
bytes_per_second:
Restrict file hashing to this many bytes per second. Can be an integer,
an existing Ratelimiter object, or a string parseable by bytestring.
The bytestring BYTE, KIBIBYTE, etc constants may help.
callback_progress: callback_progress:
A function that takes three parameters: A function that takes three parameters:
path object, bytes ingested so far, bytes total path object, bytes ingested so far, bytes total
@ -676,6 +681,10 @@ def is_xor(*args):
return [bool(a) for a in args].count(True) == 1 return [bool(a) for a in args].count(True) == 1
def limiter_or_none(value): def limiter_or_none(value):
'''
Returns a Ratelimiter object if the argument can be normalized to one,
or None if the argument is None. Saves the caller from having to if.
'''
if isinstance(value, ratelimiter.Ratelimiter): if isinstance(value, ratelimiter.Ratelimiter):
return value return value
@ -694,8 +703,8 @@ def limiter_or_none(value):
def new_root(filepath, root): def new_root(filepath, root):
''' '''
Prepend `root` to `filepath`, drive letter included. For example: Prepend `root` to `filepath`, drive letter included. For example:
"C:\\folder\\subfolder\\file.txt" and "C:\\backups" becomes "C:\\folder\\subfolder\\file.txt" and "D:\\backups" becomes
"C:\\backups\\C\\folder\\subfolder\\file.txt" "D:\\backups\\C\\folder\\subfolder\\file.txt"
I use this so that my G: drive can have backups from my C: and D: drives I use this so that my G: drive can have backups from my C: and D: drives
while preserving directory structure in G:\\D and G:\\C. while preserving directory structure in G:\\D and G:\\C.
@ -721,6 +730,20 @@ def verify_hash(
known_size=None, known_size=None,
**hash_kwargs, **hash_kwargs,
): ):
'''
Calculate the file's hash and compare it against a previous known hash.
Raises ValidationError if they differ, returns None if they match.
hash_class:
Should be a hashlib class or a callable that returns an instance of one.
known_hash:
Should be the hexdigest string from the previously calculated hash.
known_size:
Optional, should be the previously known integer number of bytes.
This makes failing the file much easier if the sizes differ.
'''
path = pathclass.Path(path) path = pathclass.Path(path)
path.assert_is_file() path.assert_is_file()