stouputils 1.6.5__tar.gz → 1.6.6__tar.gz

{stouputils-1.6.5 → stouputils-1.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.6.5
+Version: 1.6.6
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Project-URL: Homepage, https://github.com/Stoupy51/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues

{stouputils-1.6.5 → stouputils-1.6.6}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.6.5"
+version = "1.6.6"
 description = "Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more."
 readme = "README.md"
 requires-python = ">=3.10"

{stouputils-1.6.5 → stouputils-1.6.6}/stouputils/io.py

@@ -80,16 +80,22 @@ def relative_path(file_path: str, relative_to: str = "") -> str:
 		return file_path or "."
 
 # JSON dump with indentation for levels
-def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, indent: str | int = '\t', suffix: str = "\n") -> str:
+def super_json_dump(
+	data: Any,
+	file: IO[Any] | str | None = None,
+	max_level: int | None = 2,
+	indent: str | int = '\t',
+	suffix: str = "\n"
+) -> str:
 	r""" Writes the provided data to a JSON file with a specified indentation depth.
 	For instance, setting max_level to 2 will limit the indentation to 2 levels.
 
 	Args:
-		data (Any): 				The data to dump (usually a dict or a list)
-		file (IO[Any]): 			The file to dump the data to, if None, the data is returned as a string
-		max_level (int):			The depth of indentation to stop at (-1 for infinite)
-		indent (str | int):			The indentation character (default: '\t')
-		suffix (str):				The suffix to add at the end of the string (default: '\n')
+		data		(Any): 				The data to dump (usually a dict or a list)
+		file		(IO[Any] | str): 	The file object or path to dump the data to
+		max_level	(int | None):		The depth of indentation to stop at (-1 for infinite), None will default to 2
+		indent		(str | int):		The indentation character (default: '\t')
+		suffix		(str):				The suffix to add at the end of the string (default: '\n')
 	Returns:
 		str: The content of the file in every case
 
@@ -102,9 +108,11 @@ def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, in
 	>>> super_json_dump({"a": [[1,2,3]], "b": 2}, max_level = 3)
 	'{\n\t"a": [\n\t\t[\n\t\t\t1,\n\t\t\t2,\n\t\t\t3\n\t\t]\n\t],\n\t"b": 2\n}\n'
 	"""
-	# Normalize indentation to string
+	# Normalize indentation to string, and handle None values for max_level
 	if isinstance(indent, int):
 		indent = ' ' * indent
+	if max_level is None:
+		max_level = 2
 
 	# Dump content with 2-space indent and replace it with the desired indent
 	content: str = orjson.dumps(data, option=orjson.OPT_INDENT_2).decode("utf-8")
@@ -128,7 +136,11 @@ def super_json_dump(data: Any, file: IO[Any]|None = None, max_level: int = 2, in
 	# Final newline and write
 	content += suffix
 	if file:
-		file.write(content)
+		if isinstance(file, str):
+			with super_open(file, "w") as f:
+				f.write(content)
+		else:
+			file.write(content)
 	return content
 
 # JSON load from file path
@@ -144,17 +156,26 @@ def super_json_load(file_path: str) -> Any:
 		return orjson.loads(f.read())
 
 # CSV dump to file
-def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
-	""" Writes data to a CSV file with customizable options
+def super_csv_dump(
+	data: Any,
+	file: IO[Any] | str | None = None,
+	delimiter: str = ',',
+	has_header: bool = True,
+	index: bool = False,
+	*args: Any,
+	**kwargs: Any
+) -> str:
+	""" Writes data to a CSV file with customizable options and returns the CSV content as a string.
 
 	Args:
-		data (list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame): The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
-		file (IO[Any]): The file to dump the data to, if None, the data is returned as a string
-		delimiter (str): The delimiter to use (default: ',')
-		has_header (bool): Whether to include headers (default: True, applies to dict and DataFrame data)
-		index (bool): Whether to include the index (default: False, only applies to pandas DataFrame)
-		*args: Additional positional arguments to pass to the underlying CSV writer or DataFrame method
-		**kwargs: Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+		data		(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+						The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+		file		(IO[Any] | str): The file object or path to dump the data to
+		delimiter	(str): The delimiter to use (default: ',')
+		has_header	(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+		index		(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+		*args		(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+		**kwargs	(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
 	Returns:
 		str: The CSV content as a string
 
@@ -213,7 +234,11 @@ def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',',
 
 	content: str = output.getvalue()
 	if file:
-		file.write(content)
+		if isinstance(file, str):
+			with super_open(file, "w") as f:
+				f.write(content)
+		else:
+			file.write(content)
 	output.close()
 	return content
 
@@ -265,14 +290,14 @@ def super_csv_load(file_path: str, delimiter: str = ',', has_header: bool = True
 		if use_polars:
 			import polars as pl  # type: ignore
 			if not os.path.exists(file_path):
-				return pl.DataFrame()
+				return pl.DataFrame() # type: ignore
 			kwargs.setdefault("separator", delimiter)
 			kwargs.setdefault("has_header", has_header)
-			return pl.read_csv(file_path, *args, **kwargs)
+			return pl.read_csv(file_path, *args, **kwargs) # type: ignore
 		else:
 			import pandas as pd  # type: ignore
 			if not os.path.exists(file_path):
-				return pd.DataFrame()
+				return pd.DataFrame() # type: ignore
 			kwargs.setdefault("sep", delimiter)
 			kwargs.setdefault("header", 0 if has_header else None)
 			return pd.read_csv(file_path, *args, **kwargs) # type: ignore

{stouputils-1.6.5 → stouputils-1.6.6}/stouputils/io.pyi

@@ -35,16 +35,16 @@ def relative_path(file_path: str, relative_to: str = '') -> str:
 \t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some\\\\")
 \t\t\'random/path/stouputils/io.py\'
 \t'''
-def super_json_dump(data: Any, file: IO[Any] | None = None, max_level: int = 2, indent: str | int = '\t', suffix: str = '\n') -> str:
+def super_json_dump(data: Any, file: IO[Any] | str | None = None, max_level: int | None = 2, indent: str | int = '\t', suffix: str = '\n') -> str:
     ''' Writes the provided data to a JSON file with a specified indentation depth.
 \tFor instance, setting max_level to 2 will limit the indentation to 2 levels.
 
 \tArgs:
-\t\tdata (Any): \t\t\t\tThe data to dump (usually a dict or a list)
-\t\tfile (IO[Any]): \t\t\tThe file to dump the data to, if None, the data is returned as a string
-\t\tmax_level (int):\t\t\tThe depth of indentation to stop at (-1 for infinite)
-\t\tindent (str | int):\t\t\tThe indentation character (default: \'\\t\')
-\t\tsuffix (str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
+\t\tdata\t\t(Any): \t\t\t\tThe data to dump (usually a dict or a list)
+\t\tfile\t\t(IO[Any] | str): \tThe file object or path to dump the data to
+\t\tmax_level\t(int | None):\t\tThe depth of indentation to stop at (-1 for infinite), None will default to 2
+\t\tindent\t\t(str | int):\t\tThe indentation character (default: \'\\t\')
+\t\tsuffix\t\t(str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
 \tReturns:
 \t\tstr: The content of the file in every case
 
@@ -65,17 +65,18 @@ def super_json_load(file_path: str) -> Any:
 \tReturns:
 \t\tAny: The content of the JSON file
 \t"""
-def super_csv_dump(data: Any, file: IO[Any] | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
-    ''' Writes data to a CSV file with customizable options
+def super_csv_dump(data: Any, file: IO[Any] | str | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
+    ''' Writes data to a CSV file with customizable options and returns the CSV content as a string.
 
 \tArgs:
-\t\tdata (list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame): The data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
-\t\tfile (IO[Any]): The file to dump the data to, if None, the data is returned as a string
-\t\tdelimiter (str): The delimiter to use (default: \',\')
-\t\thas_header (bool): Whether to include headers (default: True, applies to dict and DataFrame data)
-\t\tindex (bool): Whether to include the index (default: False, only applies to pandas DataFrame)
-\t\t*args: Additional positional arguments to pass to the underlying CSV writer or DataFrame method
-\t\t**kwargs: Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+\t\tdata\t\t(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+\t\t\t\t\t\tThe data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+\t\tfile\t\t(IO[Any] | str): The file object or path to dump the data to
+\t\tdelimiter\t(str): The delimiter to use (default: \',\')
+\t\thas_header\t(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+\t\tindex\t\t(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+\t\t*args\t\t(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+\t\t**kwargs\t(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
 \tReturns:
 \t\tstr: The CSV content as a string