From 5c9209b12e868ac1e43d5c2789344aec1d343cd0 Mon Sep 17 00:00:00 2001 From: Joscha Date: Wed, 23 Nov 2022 23:48:17 +0100 Subject: [PATCH] Document path formatting functions --- PFERD/utils.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/PFERD/utils.py b/PFERD/utils.py index 7c7b6f4..8efc797 100644 --- a/PFERD/utils.py +++ b/PFERD/utils.py @@ -92,17 +92,32 @@ def url_set_query_params(url: str, params: Dict[str, str]) -> str: def str_path(path: PurePath) -> str: + """ + Turn a path into a string, in a platform-independent way. + + This function always uses "/" as path separator, even on Windows. + """ if not path.parts: return "." return "/".join(path.parts) def fmt_path(path: PurePath) -> str: + """ + Turn a path into a delimited string. + + This is useful if file or directory names contain weird characters like + newlines, leading/trailing whitespace or unprintable characters. This way, + they are escaped and visible to the user. + """ return repr(str_path(path)) def fmt_real_path(path: Path) -> str: - return repr(str(path.absolute())) + """ + Like fmt_path, but resolves the path before converting it to a string. + """ + return fmt_path(path.absolute()) class ReusableAsyncContextManager(ABC, Generic[T]):