stouputils 1.6.1__tar.gz → 1.6.3__tar.gz

{stouputils-1.6.1 → stouputils-1.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.6.1
+Version: 1.6.3
 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.1 → stouputils-1.6.3}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.6.1"
+version = "1.6.3"
 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.1 → stouputils-1.6.3}/stouputils/io.py

@@ -5,6 +5,8 @@ This module provides utilities for file management.
 - relative_path: Get the relative path of a file relative to a given directory
 - super_json_dump: Writes the provided data to a JSON file with a specified indentation depth.
 - super_json_load: Load a JSON file from the given path
+- super_csv_dump: Writes data to a CSV file with customizable options
+- super_csv_load: Load a CSV file from the given path
 - super_copy: Copy a file (or a folder) from the source to the destination (always create the directory)
 - super_open: Open a file with the given mode, creating the directory if it doesn't exist (only if writing)
 - replace_tilde: Replace the "~" by the user's home directory
@@ -15,9 +17,11 @@ This module provides utilities for file management.
 """
 
 # Imports
+import csv
 import os
 import re
 import shutil
+from io import StringIO
 from typing import IO, Any
 
 import orjson
@@ -139,6 +143,155 @@ def super_json_load(file_path: str) -> Any:
 	with super_open(file_path, "r") as f:
 		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
+
+	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
+	Returns:
+		str: The CSV content as a string
+
+	Examples:
+
+		>>> super_csv_dump([["a", "b", "c"], [1, 2, 3], [4, 5, 6]])
+		'a,b,c\\r\\n1,2,3\\r\\n4,5,6\\r\\n'
+
+		>>> super_csv_dump([{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}])
+		'name,age\\r\\nAlice,30\\r\\nBob,25\\r\\n'
+	"""
+	if not data:
+		return ""
+	if isinstance(data, str | bytes | dict):
+		raise ValueError("Data must be a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame")
+	output = StringIO()
+
+	# Handle Polars DataFrame
+	try:
+		import polars as pl  # type: ignore  # noqa: F401
+		copy_kwargs = kwargs.copy()
+		copy_kwargs.setdefault("separator", delimiter)
+		copy_kwargs.setdefault("include_header", has_header)
+		copy_kwargs.setdefault("line_terminator", "\r\n")
+		data.write_csv(output, *args, **copy_kwargs)
+	except AttributeError:
+		pass
+
+	# Handle pandas DataFrame
+	try:
+		import pandas as pd  # type: ignore  # noqa: F401
+		copy_kwargs = kwargs.copy()
+		copy_kwargs.setdefault("index", index)
+		copy_kwargs.setdefault("sep", delimiter)
+		copy_kwargs.setdefault("header", has_header)
+		copy_kwargs.setdefault("lineterminator", "\r\n")
+		data.to_csv(output, *args, **copy_kwargs)
+	except AttributeError:
+		pass
+
+	# Handle list of dicts
+	if isinstance(data[0], dict):
+		fieldnames = list(data[0].keys())
+		kwargs.setdefault("fieldnames", fieldnames)
+		kwargs.setdefault("delimiter", delimiter)
+		kwargs.setdefault("lineterminator", "\r\n")
+		dict_writer = csv.DictWriter(output, *args, **kwargs)
+		if has_header:
+			dict_writer.writeheader()
+		dict_writer.writerows(data)  # type: ignore
+
+	# Handle list of lists
+	else:
+		kwargs.setdefault("delimiter", delimiter)
+		kwargs.setdefault("lineterminator", "\r\n")
+		list_writer = csv.writer(output, *args, **kwargs)
+		list_writer.writerows(data)
+
+	content: str = output.getvalue()
+	if file:
+		file.write(content)
+	output.close()
+	return content
+
+# CSV load from file path
+def super_csv_load(file_path: str, delimiter: str = ',', has_header: bool = True, as_dict: bool = False, as_dataframe: bool = False, use_polars: bool = False, *args: Any, **kwargs: Any) -> Any:
+	""" Load a CSV file from the given path
+
+	Args:
+		file_path (str): The path to the CSV file
+		delimiter (str): The delimiter used in the CSV (default: ',')
+		has_header (bool): Whether the CSV has a header row (default: True)
+		as_dict (bool): Whether to return data as list of dicts (default: False)
+		as_dataframe (bool): Whether to return data as a DataFrame (default: False)
+		use_polars (bool): Whether to use Polars instead of pandas for DataFrame (default: False, requires polars)
+		*args: Additional positional arguments to pass to the underlying CSV reader or DataFrame method
+		**kwargs: Additional keyword arguments to pass to the underlying CSV reader or DataFrame method
+	Returns:
+		list[list[str]] | list[dict[str, str]] | pd.DataFrame | pl.DataFrame: The content of the CSV file
+
+	Examples:
+
+		.. code-block:: python
+
+			> Assuming "test.csv" contains: a,b,c\\n1,2,3\\n4,5,6
+			> super_csv_load("test.csv")
+			[['1', '2', '3'], ['4', '5', '6']]
+
+			> super_csv_load("test.csv", as_dict=True)
+			[{'a': '1', 'b': '2', 'c': '3'}, {'a': '4', 'b': '5', 'c': '6'}]
+
+			> super_csv_load("test.csv", as_dataframe=True)
+			   a  b  c
+			0  1  2  3
+			1  4  5  6
+
+			> super_csv_load("test.csv", as_dataframe=True, use_polars=True)
+			shape: (2, 3)
+			┌─────┬─────┬─────┐
+			│ a   ┆ b   ┆ c   │
+			│ --- ┆ --- ┆ --- │
+			│ i64 ┆ i64 ┆ i64 │
+			╞═════╪═════╪═════╡
+			│ 1   ┆ 2   ┆ 3   │
+			│ 4   ┆ 5   ┆ 6   │
+			└─────┴─────┴─────┘
+	"""  # noqa: E101
+	# Handle DataFrame loading
+	if as_dataframe:
+		if use_polars:
+			import polars as pl  # type: ignore
+			if not os.path.exists(file_path):
+				return pl.DataFrame()
+			kwargs.setdefault("separator", delimiter)
+			kwargs.setdefault("has_header", has_header)
+			return pl.read_csv(file_path, *args, **kwargs)
+		else:
+			import pandas as pd  # type: ignore
+			if not os.path.exists(file_path):
+				return pd.DataFrame()
+			kwargs.setdefault("sep", delimiter)
+			kwargs.setdefault("header", 0 if has_header else None)
+			return pd.read_csv(file_path, *args, **kwargs) # type: ignore
+
+	# Handle dict or list
+	if not os.path.exists(file_path):
+		return []
+	with super_open(file_path, "r") as f:
+		if as_dict or has_header:
+			kwargs.setdefault("delimiter", delimiter)
+			reader = csv.DictReader(f, *args, **kwargs)
+			return list(reader)
+		else:
+			kwargs.setdefault("delimiter", delimiter)
+			reader = csv.reader(f, *args, **kwargs)
+			return list(reader)
+
 # For easy file copy
 def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = False) -> str:
 	""" Copy a file (or a folder) from the source to the destination

{stouputils-1.6.1 → stouputils-1.6.3}/stouputils/io.pyi

@@ -65,6 +65,70 @@ 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
+
+\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
+\tReturns:
+\t\tstr: The CSV content as a string
+
+\tExamples:
+
+\t\t>>> super_csv_dump([["a", "b", "c"], [1, 2, 3], [4, 5, 6]])
+\t\t\'a,b,c\\r\\n1,2,3\\r\\n4,5,6\\r\\n\'
+
+\t\t>>> super_csv_dump([{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}])
+\t\t\'name,age\\r\\nAlice,30\\r\\nBob,25\\r\\n\'
+\t'''
+def super_csv_load(file_path: str, delimiter: str = ',', has_header: bool = True, as_dict: bool = False, as_dataframe: bool = False, use_polars: bool = False, *args: Any, **kwargs: Any) -> Any:
+    ''' Load a CSV file from the given path
+
+\tArgs:
+\t\tfile_path (str): The path to the CSV file
+\t\tdelimiter (str): The delimiter used in the CSV (default: \',\')
+\t\thas_header (bool): Whether the CSV has a header row (default: True)
+\t\tas_dict (bool): Whether to return data as list of dicts (default: False)
+\t\tas_dataframe (bool): Whether to return data as a DataFrame (default: False)
+\t\tuse_polars (bool): Whether to use Polars instead of pandas for DataFrame (default: False, requires polars)
+\t\t*args: Additional positional arguments to pass to the underlying CSV reader or DataFrame method
+\t\t**kwargs: Additional keyword arguments to pass to the underlying CSV reader or DataFrame method
+\tReturns:
+\t\tlist[list[str]] | list[dict[str, str]] | pd.DataFrame | pl.DataFrame: The content of the CSV file
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> Assuming "test.csv" contains: a,b,c\\n1,2,3\\n4,5,6
+\t\t\t> super_csv_load("test.csv")
+\t\t\t[[\'1\', \'2\', \'3\'], [\'4\', \'5\', \'6\']]
+
+\t\t\t> super_csv_load("test.csv", as_dict=True)
+\t\t\t[{\'a\': \'1\', \'b\': \'2\', \'c\': \'3\'}, {\'a\': \'4\', \'b\': \'5\', \'c\': \'6\'}]
+
+\t\t\t> super_csv_load("test.csv", as_dataframe=True)
+\t\t\t   a  b  c
+\t\t\t0  1  2  3
+\t\t\t1  4  5  6
+
+\t\t\t> super_csv_load("test.csv", as_dataframe=True, use_polars=True)
+\t\t\tshape: (2, 3)
+\t\t\t┌─────┬─────┬─────┐
+\t\t\t│ a   ┆ b   ┆ c   │
+\t\t\t│ --- ┆ --- ┆ --- │
+\t\t\t│ i64 ┆ i64 ┆ i64 │
+\t\t\t╞═════╪═════╪═════╡
+\t\t\t│ 1   ┆ 2   ┆ 3   │
+\t\t\t│ 4   ┆ 5   ┆ 6   │
+\t\t\t└─────┴─────┴─────┘
+\t'''
 def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = False) -> str:
     """ Copy a file (or a folder) from the source to the destination