Allow require reason on storage changes (#93)

Author: XingY

CHANGE.txt

@@ -2,6 +2,12 @@
 LabKey Python Client API News
 +++++++++++
 
+What's New in the LabKey 4.3.0 package
+==============================
+
+*Release date: 06/29/2026*
+- Freezer Manager API - add `auditUserComment` to create/update/delete_storage_item
+
 What's New in the LabKey 4.2.0 package
 ==============================
 

docs/storage.md

@@ -110,10 +110,17 @@ else:
 box_id = result["data"]["rowId"]
 
 ###############
-# Update the location of a box in the freezer
+# Update the location of a box in the freezer. An optional "auditUserComment"
+# property may be included in the props dict; it is recorded as the "Reason"
+# on the resulting audit event.
 ###############
 result = api.storage.update_storage_item(
-    "Terminal Storage Location", {"rowId": box_id, "locationId": shelf2_row_id}
+    "Terminal Storage Location",
+    {
+        "rowId": box_id,
+        "locationId": shelf2_row_id,
+        "auditUserComment": "Relocated to make room for incoming samples from Lab B.",
+    },
 )
 if result is not None:
     print(result)
@@ -122,9 +129,14 @@ else:
     exit()
 
 ###############
-# Delete the freezer, which will delete the full hierarchy of non-terminal and terminal storage locations
+# Delete the freezer, which will delete the full hierarchy of non-terminal and terminal
+# storage locations. An optional audit_user_comment is supplied here for the audit log.
 ###############
-result = api.storage.delete_storage_item("Freezer", freezer_row_id)
+result = api.storage.delete_storage_item(
+    "Freezer",
+    freezer_row_id,
+    audit_user_comment="Decommissioning Freezer #1 per facilities request.",
+)
 if result is not None:
     print(result)
 else:

labkey/storage.py

@@ -64,7 +64,8 @@ def create_storage_item(
     Create a new LabKey Freezer Manager storage item that can be used in the creation of a storage hierarchy.
     :param server_context: A LabKey server context. See utils.create_server_context.
     :param type:
-    :param props:
+    :param props: a dict of property values for the storage item. Any storage item type also accepts an optional
+        "auditUserComment" (string) entry, which is recorded as the "Reason" on the resulting audit event.
     :param container_path:
     :return:
     """
@@ -82,7 +83,8 @@ def update_storage_item(
     For update_storage_item, the "rowId" primary key value is required to be set within the props.
     :param server_context: A LabKey server context. See utils.create_server_context.
     :param type:
-    :param props:
+    :param props: a dict of property values for the storage item. Any storage item type also accepts an optional
+        "auditUserComment" (string) entry, which is recorded as the "Reason" on the resulting audit event.
     :param container_path:
     :return:
     """
@@ -93,7 +95,7 @@ def update_storage_item(
 
 
 def delete_storage_item(
-    server_context: ServerContext, type: str, row_id: int, container_path: str = None
+    server_context: ServerContext, type: str, row_id: int, container_path: str = None, audit_user_comment: str = None
 ):
     """
     Delete an existing LabKey Freezer Manager storage item. Note that deletion of freezers, primary storage, or locations
@@ -103,10 +105,14 @@ def delete_storage_item(
     :param type:
     :param row_id:
     :param container_path:
+    :param audit_user_comment: optional reason text recorded as the "Reason" on the resulting audit event.
     :return:
     """
     url = server_context.build_url(STORAGE_CONTROLLER, "delete.api", container_path)
-    payload = {"type": type, "props": {"rowId": row_id}}
+    props = {"rowId": row_id}
+    if audit_user_comment is not None:
+        props["auditUserComment"] = audit_user_comment
+    payload = {"type": type, "props": props}
 
     return server_context.make_request(url, json=payload)
 
@@ -128,5 +134,5 @@ def update_storage_item(self, type: str, props: dict, container_path: str = None
         return update_storage_item(self.server_context, type, props, container_path)
 
     @functools.wraps(delete_storage_item)
-    def delete_storage_item(self, type: str, row_id: int, container_path: str = None):
-        return delete_storage_item(self.server_context, type, row_id, container_path)
+    def delete_storage_item(self, type: str, row_id: int, container_path: str = None, audit_user_comment: str = None):
+        return delete_storage_item(self.server_context, type, row_id, container_path, audit_user_comment)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name="labkey"
-version = "4.2.0"
+version = "4.3.0"
 description = "Python client API for LabKey Server"
 dependencies = ["requests>=2.32.5"]
 readme = "README.md"