stouputils 1.18.0__py3-none-any.whl → 1.18.1__py3-none-any.whl

stouputils/collections.py

@@ -132,16 +132,45 @@ def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool =
 def upsert_in_dataframe(
 	df: "pl.DataFrame",
 	new_entry: dict[str, Any],
-	primary_keys: dict[str, Any] | None = None
+	primary_keys: list[str] | dict[str, Any] | None = None
 ) -> "pl.DataFrame":
 	""" Insert or update a row in the Polars DataFrame based on primary keys.
 
 	Args:
 		df				(pl.DataFrame):		The Polars DataFrame to update.
 		new_entry		(dict[str, Any]):	The new entry to insert or update.
-		primary_keys	(dict[str, Any]):	The primary keys to identify the row (default: empty).
+		primary_keys	(list[str] | dict[str, Any] | None):	The primary keys to identify the row (for updates).
 	Returns:
 		pl.DataFrame: The updated Polars DataFrame.
+	Examples:
+		>>> import polars as pl
+		>>> df = pl.DataFrame({"id": [1, 2], "value": ["a", "b"]})
+		>>> new_entry = {"id": 2, "value": "updated"}
+		>>> updated_df = upsert_in_dataframe(df, new_entry, primary_keys=["id"])
+		>>> print(updated_df)
+		shape: (2, 2)
+		┌─────┬─────────┐
+		│ id  ┆ value   │
+		│ --- ┆ ---     │
+		│ i64 ┆ str     │
+		╞═════╪═════════╡
+		│ 1   ┆ a       │
+		│ 2   ┆ updated │
+		└─────┴─────────┘
+
+		>>> new_entry = {"id": 3, "value": "new"}
+		>>> updated_df = upsert_in_dataframe(updated_df, new_entry, primary_keys=["id"])
+		>>> print(updated_df)
+		shape: (3, 2)
+		┌─────┬─────────┐
+		│ id  ┆ value   │
+		│ --- ┆ ---     │
+		│ i64 ┆ str     │
+		╞═════╪═════════╡
+		│ 1   ┆ a       │
+		│ 2   ┆ updated │
+		│ 3   ┆ new     │
+		└─────┴─────────┘
 	"""
 	# Imports
 	import polars as pl
@@ -155,6 +184,10 @@ def upsert_in_dataframe(
 		new_row_df = pl.DataFrame([new_entry])
 		return pl.concat([df, new_row_df], how="diagonal_relaxed")
 
+	# If primary keys are provided as a list, convert to dict with values from new_entry
+	if isinstance(primary_keys, list):
+		primary_keys = {key: new_entry[key] for key in primary_keys if key in new_entry}
+
 	# Build mask based on primary keys
 	mask: pl.Expr = pl.lit(True)
 	for key, value in primary_keys.items():

stouputils/collections.pyi

@@ -69,16 +69,45 @@ def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool =
 \t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3, \'d\': 4}, order=["c", "b"])
 \t\t{\'c\': 3, \'b\': 2, \'a\': 1, \'d\': 4}
 \t'''
-def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: dict[str, Any] | None = None) -> pl.DataFrame:
-    """ Insert or update a row in the Polars DataFrame based on primary keys.
+def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: list[str] | dict[str, Any] | None = None) -> pl.DataFrame:
+    ''' Insert or update a row in the Polars DataFrame based on primary keys.
 
 \tArgs:
 \t\tdf\t\t\t\t(pl.DataFrame):\t\tThe Polars DataFrame to update.
 \t\tnew_entry\t\t(dict[str, Any]):\tThe new entry to insert or update.
-\t\tprimary_keys\t(dict[str, Any]):\tThe primary keys to identify the row (default: empty).
+\t\tprimary_keys\t(list[str] | dict[str, Any] | None):\tThe primary keys to identify the row (for updates).
 \tReturns:
 \t\tpl.DataFrame: The updated Polars DataFrame.
-\t"""
+\tExamples:
+\t\t>>> import polars as pl
+\t\t>>> df = pl.DataFrame({"id": [1, 2], "value": ["a", "b"]})
+\t\t>>> new_entry = {"id": 2, "value": "updated"}
+\t\t>>> updated_df = upsert_in_dataframe(df, new_entry, primary_keys=["id"])
+\t\t>>> print(updated_df)
+\t\tshape: (2, 2)
+\t\t┌─────┬─────────┐
+\t\t│ id  ┆ value   │
+\t\t│ --- ┆ ---     │
+\t\t│ i64 ┆ str     │
+\t\t╞═════╪═════════╡
+\t\t│ 1   ┆ a       │
+\t\t│ 2   ┆ updated │
+\t\t└─────┴─────────┘
+
+\t\t>>> new_entry = {"id": 3, "value": "new"}
+\t\t>>> updated_df = upsert_in_dataframe(updated_df, new_entry, primary_keys=["id"])
+\t\t>>> print(updated_df)
+\t\tshape: (3, 2)
+\t\t┌─────┬─────────┐
+\t\t│ id  ┆ value   │
+\t\t│ --- ┆ ---     │
+\t\t│ i64 ┆ str     │
+\t\t╞═════╪═════════╡
+\t\t│ 1   ┆ a       │
+\t\t│ 2   ┆ updated │
+\t\t│ 3   ┆ new     │
+\t\t└─────┴─────────┘
+\t'''
 def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, more_data: NDArray[Any] | zarr.Array | None = None) -> tuple['zarr.Array', str, int]:
     """ Easily handle large numpy arrays on disk using zarr for efficient storage and access.
 

{stouputils-1.18.0.dist-info → stouputils-1.18.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.18.0
+Version: 1.18.1
 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.
 Keywords: utilities,tools,helpers,development,python
 Author: Stoupy51

{stouputils-1.18.0.dist-info → stouputils-1.18.1.dist-info}/RECORD

@@ -21,8 +21,8 @@ stouputils/archive.py,sha256=uDrPFxbY_C8SwUZRH4FWnYSoJKkFWynCx751zP9AHaY,12144
 stouputils/archive.pyi,sha256=Z2BbQAiErRYntv53QC9uf_XPw3tx3Oy73wB0Bbil11c,3246
 stouputils/backup.py,sha256=AE5WKMLiyk0VkRUfhmNfO2EUeUbZY5GTFVIuI5z7axA,20947
 stouputils/backup.pyi,sha256=-SLVykkR5U8479T84zjNPVBNnV193s0zyWjathY2DDA,4923
-stouputils/collections.py,sha256=jUNJQaMhmgLetVyZrYm0FFiaU0RkBfuXeJEvJ7wyGzU,9815
-stouputils/collections.pyi,sha256=naOr5vsvu2SOW-IUFLaoyxYXVv0Vk5pC9zD_mmT0dg8,4297
+stouputils/collections.py,sha256=73799uJ5ryQoNBo7N4Cz41Q992QP_kSsw_hy33ZpDyw,11121
+stouputils/collections.pyi,sha256=jPzyaeesz1IqutuT69Bt4DFOguURjXbcYO2l2sifXRA,5448
 stouputils/continuous_delivery/__init__.py,sha256=JqPww29xZ-pp6OJDGhUj2dxyV9rgTTMUz0YDDVr9RaA,731
 stouputils/continuous_delivery/__init__.pyi,sha256=_Sz2D10n1CDEyY8qDFwXNKdr01HVxanY4qdq9aN19cc,117
 stouputils/continuous_delivery/cd_utils.py,sha256=fkaHk2V3j66uFAUsM2c_UddNhXW2KAQcrh7jVsH79pU,8594
@@ -156,7 +156,7 @@ stouputils/typing.py,sha256=TwvxrvxhBRkyHkoOpfyXebN13M3xJb8MAjKXiNIWjew,2205
 stouputils/typing.pyi,sha256=U2UmFZausMYpnsUQROQE2JOwHcjx2hKV0rJuOdR57Ew,1341
 stouputils/version_pkg.py,sha256=Jsp-s03L14DkiZ94vQgrlQmaxApfn9DC8M_nzT1SJLk,7014
 stouputils/version_pkg.pyi,sha256=QPvqp1U3QA-9C_CC1dT9Vahv1hXEhstbM7x5uzMZSsQ,755
-stouputils-1.18.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-stouputils-1.18.0.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.18.0.dist-info/METADATA,sha256=OrIKAYzFOAG8DIJjpNj2UQzc2QW7iRSH_PS3yc6EnMQ,14011
-stouputils-1.18.0.dist-info/RECORD,,
+stouputils-1.18.1.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+stouputils-1.18.1.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.18.1.dist-info/METADATA,sha256=PWMcVUM25QN5JXf9cDGGl-xPQQc3evJlWk8QX6FliFQ,14011
+stouputils-1.18.1.dist-info/RECORD,,