From cafd006be30bdaba51df733c39eb52369fdf0c34 Mon Sep 17 00:00:00 2001 From: Scott Gasch Date: Tue, 13 Jun 2023 10:12:34 -0700 Subject: [PATCH] Adding docs. --- src/pyutils/files/file_utils.py | 57 ++++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 4 deletions(-) diff --git a/src/pyutils/files/file_utils.py b/src/pyutils/files/file_utils.py index 16b71ab..45feb34 100644 --- a/src/pyutils/files/file_utils.py +++ b/src/pyutils/files/file_utils.py @@ -91,6 +91,9 @@ def remove(path: str) -> None: Args: path: the path of the file to delete + Raises: + FileNotFoundError: the path to remove does not exist + >>> import os >>> filename = '/tmp/file_utils_test_file' >>> os.system(f'touch {filename}') @@ -100,6 +103,11 @@ def remove(path: str) -> None: >>> remove(filename) >>> does_file_exist(filename) False + + >>> remove("/tmp/23r23r23rwdfwfwefgdfgwerhwrgewrgergerg22r") + Traceback (most recent call last): + ... + FileNotFoundError: [Errno 2] No such file or directory: '/tmp/23r23r23rwdfwfwefgdfgwerhwrgewrgergerg22r' """ os.remove(path) @@ -310,16 +318,15 @@ def create_path_if_not_exist( Args: path: the path to attempt to create - on_error: If set, it's invoked on error conditions and passed then - path and OSError that it caused. + on_error: if provided, this is invoked on error conditions and + passed the path and OSError that it caused Raises: - OSError: an exception occurred and on_error not set. + OSError: an exception occurred and on_error was not set. See also :meth:`does_file_exist`. .. warning:: - Files are created with mode 0o0777 (i.e. world read/writeable). >>> import uuid @@ -355,6 +362,13 @@ def does_file_exist(filename: str) -> bool: Returns: True if filename exists and is a normal file. + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`create_path_if_not_exist`, :meth:`is_readable`. >>> does_file_exist(__file__) @@ -391,6 +405,13 @@ def is_writable(filename: str) -> bool: True if file exists, is a normal file and is writable by the current process. False otherwise. + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`is_readable`, :meth:`does_file_exist`. """ return os.access(filename, os.W_OK) @@ -406,6 +427,13 @@ def is_executable(filename: str) -> bool: True if file exists, is a normal file and is executable by the current process. False otherwise. + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`does_file_exist`, :meth:`is_readable`, :meth:`is_writable`. """ @@ -457,6 +485,13 @@ def is_normal_file(filename: str) -> bool: Returns: True if filename is a normal file. + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`is_directory`, :meth:`does_file_exist`, :meth:`is_symlink`. >>> is_normal_file(__file__) @@ -474,6 +509,13 @@ def is_directory(filename: str) -> bool: Returns: True if filename is a directory + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`does_directory_exist`, :meth:`is_normal_file`, :meth:`is_symlink`. @@ -492,6 +534,13 @@ def is_symlink(filename: str) -> bool: Returns: True if filename is a symlink, False otherwise. + .. note:: + A Python core philosophy is: it's easier to ask forgiveness + than permission (https://docs.python.org/3/glossary.html#term-EAFP). + That is, code that just tries an operation and handles the set of + Exceptions that may arise is the preferred style. That said, this + function can still be useful in some situations. + See also :meth:`is_directory`, :meth:`is_normal_file`. >>> is_symlink('/tmp') -- 2.45.0