From 3e8852c0504dc1d9c2e6f75fdfbbc1fc6943ed68 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Wed, 7 May 2025 12:37:06 -0700 Subject: [PATCH 1/9] docs: correcting docstring and updating return signature Function does not actually return `bool` Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index 122cbbcc..091dbc5d 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -21,7 +21,7 @@ log = logging.getLogger(__name__) -def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]): +def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]) -> None: """ Ensure that a path has one of the specified extensions. @@ -33,11 +33,6 @@ def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]): extensions: Iterable[str] The valid extensions to test against. - Returns - ------- - bool - True if `path` is a file with one of the specified extensions. - Raises ------ TypeError From d5e36b3230cd05e4033700151b01370b9c9def15 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Wed, 7 May 2025 14:06:39 -0700 Subject: [PATCH 2/9] docs: adding type annotations to save_open_write_binary Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/codebasin/util.py b/codebasin/util.py index 091dbc5d..a98e9d48 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -7,6 +7,7 @@ - Checking paths """ +from io import TextIOWrapper import json import logging import os @@ -54,7 +55,7 @@ def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]) -> None: raise ValueError(f"{path} does not have a valid extension: f{exts}") -def safe_open_write_binary(fname): +def safe_open_write_binary(fname: os.PathLike[str]) -> TextIOWrapper: """Open fname for (binary) writing. Truncate if not a symlink.""" fpid = os.open( fname, From fdb71133fd49b26607e57c41c1078527c13b4969 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Wed, 7 May 2025 14:09:48 -0700 Subject: [PATCH 3/9] docs: added docstring and type annotations to valid_path Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index a98e9d48..14a17db5 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -65,8 +65,40 @@ def safe_open_write_binary(fname: os.PathLike[str]) -> TextIOWrapper: return os.fdopen(fpid, "wb") -def valid_path(path): - """Return true if the path passed in is valid""" +def valid_path(path: os.PathLike[str]) -> bool: + """ + Check if a given file path is valid. + + This function ensures that the file path does not contain + potentially dangerous characters such as null bytes (`\x00`) + or carriage returns/line feeds (`\n`, `\r`). These characters + can pose security risks, particularly in file handling operations. + + Parameters + ---------- + path : os.PathLike[str] + The file path to be validated. + + Returns + ------- + bool + A boolean value indicating whether the path is valid + (`True`) or invalid (`False`). + + Notes + ----- + - This function is useful for validating file paths before performing + file I/O operations to prevent security vulnerabilities. + + Examples + -------- + >>> valid_path("/home/user/file.txt") + True + >>> valid_path("/home/user/\x00file.txt") + False + >>> valid_path("/home/user/file\n.txt") + False + """ valid = True # Check for null byte character(s) From ad6579cf748b572e6bbc4871560e4f64eb8d2b87 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Wed, 7 May 2025 14:10:23 -0700 Subject: [PATCH 4/9] chore: bumping copyright year Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/codebasin/util.py b/codebasin/util.py index 14a17db5..2bfb3305 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -1,4 +1,4 @@ -# Copyright (C) 2019-2024 Intel Corporation +# Copyright (C) 2019-2025 Intel Corporation # SPDX-License-Identifier: BSD-3-Clause """ Contains utility functions for common operations, including: From 29e55307a67582cbeb5665e7469da8256d28323c Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Thu, 8 May 2025 10:01:24 -0700 Subject: [PATCH 5/9] docs: making _load_toml type hint specific `tomllib.load` signature returns a dict; this change matches what is ultimately returned by `tomllib.load`. Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index 2bfb3305..72468524 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -229,7 +229,7 @@ def _load_json(file_object: typing.TextIO, schema_name: str) -> object: return json_object -def _load_toml(file_object: typing.TextIO, schema_name: str) -> object: +def _load_toml(file_object: typing.TextIO, schema_name: str) -> dict[str, typing.Any]: """ Load TOML from file and validate it against a schema. @@ -243,8 +243,9 @@ def _load_toml(file_object: typing.TextIO, schema_name: str) -> object: Returns ------- - Object - The loaded TOML. + dict[str, Any] + The loaded TOML object, represented as a Python + dict with str key/value mappings. Raises ------ From 72b4e9ba70a785ccadb9bf6decc11fd56eec35bb Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Thu, 8 May 2025 10:04:16 -0700 Subject: [PATCH 6/9] style: ran pre-commit workflows on module Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index 72468524..ab4cefaa 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -7,7 +7,6 @@ - Checking paths """ -from io import TextIOWrapper import json import logging import os @@ -15,6 +14,7 @@ import tomllib import typing from collections.abc import Iterable +from io import TextIOWrapper from pathlib import Path import jsonschema @@ -69,7 +69,7 @@ def valid_path(path: os.PathLike[str]) -> bool: """ Check if a given file path is valid. - This function ensures that the file path does not contain + This function ensures that the file path does not contain potentially dangerous characters such as null bytes (`\x00`) or carriage returns/line feeds (`\n`, `\r`). These characters can pose security risks, particularly in file handling operations. @@ -82,12 +82,12 @@ def valid_path(path: os.PathLike[str]) -> bool: Returns ------- bool - A boolean value indicating whether the path is valid + A boolean value indicating whether the path is valid (`True`) or invalid (`False`). Notes ----- - - This function is useful for validating file paths before performing + - This function is useful for validating file paths before performing file I/O operations to prevent security vulnerabilities. Examples @@ -229,7 +229,10 @@ def _load_json(file_object: typing.TextIO, schema_name: str) -> object: return json_object -def _load_toml(file_object: typing.TextIO, schema_name: str) -> dict[str, typing.Any]: +def _load_toml( + file_object: typing.TextIO, + schema_name: str, +) -> dict[str, typing.Any]: """ Load TOML from file and validate it against a schema. From 77e47a1254cebe17fe465d6433d0cb1afd80dea0 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Fri, 9 May 2025 07:38:36 -0700 Subject: [PATCH 7/9] refactor: replacing TextIOWrapper typehint in favor of BinaryIO Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index ab4cefaa..bd2fec78 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -14,7 +14,6 @@ import tomllib import typing from collections.abc import Iterable -from io import TextIOWrapper from pathlib import Path import jsonschema @@ -55,7 +54,7 @@ def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]) -> None: raise ValueError(f"{path} does not have a valid extension: f{exts}") -def safe_open_write_binary(fname: os.PathLike[str]) -> TextIOWrapper: +def safe_open_write_binary(fname: os.PathLike[str]) -> typing.BinaryIO: """Open fname for (binary) writing. Truncate if not a symlink.""" fpid = os.open( fname, From f34029188969c386201e74be3a99129d26470156 Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Fri, 9 May 2025 07:45:42 -0700 Subject: [PATCH 8/9] fix: removing redundant f in f-string Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/codebasin/util.py b/codebasin/util.py index bd2fec78..2074220c 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -51,7 +51,7 @@ def ensure_ext(path: os.PathLike[str], extensions: Iterable[str]) -> None: extension = "".join(path.suffixes) if extension not in extensions: exts = ", ".join([f"'{ext}'" for ext in extensions]) - raise ValueError(f"{path} does not have a valid extension: f{exts}") + raise ValueError(f"{path} does not have a valid extension: {exts}") def safe_open_write_binary(fname: os.PathLike[str]) -> typing.BinaryIO: From dca480760abcae75cb9978f1e376b4f232b7446c Mon Sep 17 00:00:00 2001 From: Kin Long Kelvin Lee Date: Fri, 9 May 2025 07:47:41 -0700 Subject: [PATCH 9/9] docs: removing unnecessary commentary from docstrings Signed-off-by: Kin Long Kelvin Lee --- codebasin/util.py | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/codebasin/util.py b/codebasin/util.py index 2074220c..e12220fa 100644 --- a/codebasin/util.py +++ b/codebasin/util.py @@ -70,8 +70,7 @@ def valid_path(path: os.PathLike[str]) -> bool: This function ensures that the file path does not contain potentially dangerous characters such as null bytes (`\x00`) - or carriage returns/line feeds (`\n`, `\r`). These characters - can pose security risks, particularly in file handling operations. + or carriage returns/line feeds (`\n`, `\r`). Parameters ---------- @@ -84,11 +83,6 @@ def valid_path(path: os.PathLike[str]) -> bool: A boolean value indicating whether the path is valid (`True`) or invalid (`False`). - Notes - ----- - - This function is useful for validating file paths before performing - file I/O operations to prevent security vulnerabilities. - Examples -------- >>> valid_path("/home/user/file.txt")