From 0f02ef9bacd78aac787dfeb223829f797ade8090 Mon Sep 17 00:00:00 2001 From: luarss Date: Wed, 20 May 2026 09:31:56 +0800 Subject: [PATCH 1/2] feat(items): add per-type column value helpers (email/phone/link/checkbox/dropdown) Fills in the missing `change_*_column_value` siblings to match the existing pattern of `change_status_column_value` and `change_date_column_value`. Each new helper wraps the correct JSON shape expected by Monday's column_values API: change_email_column_value -> {"email": ..., "text": ...} change_phone_column_value -> {"phone": ..., "countryShortName": ...} change_link_column_value -> {"url": ..., "text": ...} change_checkbox_column_value -> {"checked": "true"} or {} change_dropdown_column_value -> {"labels": [...]} Before this change, callers either had to memorize the JSON shapes and pass them to `change_custom_column_value` directly, or look them up in Monday's API reference each time. The docstring on `change_custom_column_value` is updated to point at the type-specific helpers and now serves as the escape hatch for column types that don't have one yet (country, location, people, tags). --- src/monday_sdk/modules/items.py | 72 ++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/src/monday_sdk/modules/items.py b/src/monday_sdk/modules/items.py index 35265ba..b54393f 100644 --- a/src/monday_sdk/modules/items.py +++ b/src/monday_sdk/modules/items.py @@ -18,11 +18,21 @@ def __init__(self, graphql_client: MondayGraphQL): def change_custom_column_value( self, board_id: Union[str, int], item_id: Union[str, int], column_id: str, value: Dict[str, Any] ): - """ - for text columns, use change_simple_column_value - for status columns, use change_status_column_value - for date columns, use change_date_column_value - for other columns, use this method, for example, for checkbox columns pass {'checked': True} + """Change any column by passing the raw value dict. + + Prefer the type-specific helpers when one exists: + text -> change_simple_column_value + status -> change_status_column_value + date -> change_date_column_value + email -> change_email_column_value + phone -> change_phone_column_value + link -> change_link_column_value + checkbox -> change_checkbox_column_value + dropdown -> change_dropdown_column_value + + Use this method directly only for column types without a dedicated + helper (country, location, people, tags, etc.) where you already + know the correct value shape. """ query = change_column_value_query(board_id, item_id, column_id, value) return self.client.execute(query) @@ -45,6 +55,58 @@ def change_date_column_value( dict_value = {"date": timestamp.strftime("%Y-%m-%d"), "time": timestamp.strftime("%H:%M:%S")} return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + def change_email_column_value( + self, + board_id: Union[str, int], + item_id: Union[str, int], + column_id: str, + email: str, + text: Optional[str] = None, + ): + dict_value = {"email": email, "text": text if text is not None else email} + return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + + def change_phone_column_value( + self, + board_id: Union[str, int], + item_id: Union[str, int], + column_id: str, + phone: str, + country_short_name: str = "", + ): + dict_value = {"phone": phone, "countryShortName": country_short_name} + return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + + def change_link_column_value( + self, + board_id: Union[str, int], + item_id: Union[str, int], + column_id: str, + url: str, + text: Optional[str] = None, + ): + dict_value = {"url": url, "text": text if text is not None else url} + return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + + def change_checkbox_column_value( + self, board_id: Union[str, int], item_id: Union[str, int], column_id: str, checked: bool + ): + """Setting checked=False unchecks the box by sending an empty object, + which is how Monday's API clears a checkbox column.""" + dict_value = {"checked": "true"} if checked else {} + return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + + def change_dropdown_column_value( + self, + board_id: Union[str, int], + item_id: Union[str, int], + column_id: str, + labels: List[str], + ): + """Set the dropdown's selected labels. Pass an empty list to clear.""" + dict_value = {"labels": list(labels)} + return self.change_custom_column_value(board_id, item_id, column_id, dict_value) + def create_item( self, board_id: Union[str, int], From de6dd4921dc675edfa45842509ad21bbce53641d Mon Sep 17 00:00:00 2001 From: luarss Date: Wed, 20 May 2026 10:18:59 +0800 Subject: [PATCH 2/2] chore(items): align new helpers with existing docstring convention Existing change_*_column_value helpers (simple/status/date) have no docstrings; match that for the new ones. Reverts the change_custom_column_value docstring to the original informal 'for X columns, use Y' list format, just extended with the new helpers. --- src/monday_sdk/modules/items.py | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/src/monday_sdk/modules/items.py b/src/monday_sdk/modules/items.py index b54393f..3d95844 100644 --- a/src/monday_sdk/modules/items.py +++ b/src/monday_sdk/modules/items.py @@ -18,21 +18,16 @@ def __init__(self, graphql_client: MondayGraphQL): def change_custom_column_value( self, board_id: Union[str, int], item_id: Union[str, int], column_id: str, value: Dict[str, Any] ): - """Change any column by passing the raw value dict. - - Prefer the type-specific helpers when one exists: - text -> change_simple_column_value - status -> change_status_column_value - date -> change_date_column_value - email -> change_email_column_value - phone -> change_phone_column_value - link -> change_link_column_value - checkbox -> change_checkbox_column_value - dropdown -> change_dropdown_column_value - - Use this method directly only for column types without a dedicated - helper (country, location, people, tags, etc.) where you already - know the correct value shape. + """ + for text columns, use change_simple_column_value + for status columns, use change_status_column_value + for date columns, use change_date_column_value + for email columns, use change_email_column_value + for phone columns, use change_phone_column_value + for link columns, use change_link_column_value + for checkbox columns, use change_checkbox_column_value + for dropdown columns, use change_dropdown_column_value + for other columns, use this method """ query = change_column_value_query(board_id, item_id, column_id, value) return self.client.execute(query) @@ -91,8 +86,6 @@ def change_link_column_value( def change_checkbox_column_value( self, board_id: Union[str, int], item_id: Union[str, int], column_id: str, checked: bool ): - """Setting checked=False unchecks the box by sending an empty object, - which is how Monday's API clears a checkbox column.""" dict_value = {"checked": "true"} if checked else {} return self.change_custom_column_value(board_id, item_id, column_id, dict_value) @@ -103,7 +96,6 @@ def change_dropdown_column_value( column_id: str, labels: List[str], ): - """Set the dropdown's selected labels. Pass an empty list to clear.""" dict_value = {"labels": list(labels)} return self.change_custom_column_value(board_id, item_id, column_id, dict_value)