feat(web-api): add slackLists methods

[srtaalej]

Summary

This PR adds the following slackLists methods to the slack_sdk:
access.delete, access.set, create, download.get, download.start,
items.create, items.delete, items.deleteMultiple, items.info,
items.list, items.update, update

---

Testing

▶️ expand test example

# create a new list
list_create_response = app.client.slackLists_create(
    name="Test List - SlackLists API",
    description_blocks=[
        {
            "type": "rich_text",
            "elements": [
                {
                    "type": "rich_text_section",
                    "elements": [
                        {"type": "text", "text": "List to keep track of tasks!"}
                    ],
                }
            ],
        }
    ],
    schema=[
        {
            "key": "task_name",
            "name": "Task Name",
            "type": "text",
            "is_primary_column": True,
        },
        {
            "key": "due_date",
            "name": "Due Date",
            "type": "date",
        },
        {
            "key": "status",
            "name": "Status",
            "type": "select",
            "options": {
                "choices": [
                    {"value": "not_started", "label": "Not Started", "color": "red"},
                    {"value": "in_progress", "label": "In Progress", "color": "yellow"},
                    {"value": "completed", "label": "Completed", "color": "green"},
                ]
            },
        },
        {
            "key": "assignee",
            "name": "Assignee",
            "type": "user",
        },
    ],
)

# retrieve column ids from create response
key_to_id = {
    col["key"]: col["id"]
    for col in list_create_response["list_metadata"]["schema"]
}
task_name_col_id = key_to_id["task_name"]
list_id = list_create_response["list_id"]

# set list access permissions
list_access = app.client.slackLists_access_set(
    list_id=list_id,
    access_level="write",
    user_ids=["U09G4FG3TRN"],
)

# create several list items
item_response_1 = app.client.slackLists_items_create(
    list_id=list_id,
    initial_fields=[
        {
            "column_id": task_name_col_id,
            "rich_text": [
                {
                    "type": "rich_text",
                    "elements": [
                        {
                            "type": "rich_text_section",
                            "elements": [{"type": "text", "text": "CLI app unlink command"}],
                        }
                    ],
                }
            ],
        }
    ],
)

item_response_2 = app.client.slackLists_items_create(list_id=list_id)
item_response_3 = app.client.slackLists_items_create(list_id=list_id)
item_response_4 = app.client.slackLists_items_create(list_id=list_id)
item_response_5 = app.client.slackLists_items_create(list_id=list_id)

item_id_1 = item_response_1["item"]["id"]
item_id_2 = item_response_2["item"]["id"]
item_id_3 = item_response_3["item"]["id"]
item_id_4 = item_response_4["item"]["id"]
item_id_5 = item_response_5["item"]["id"]

# delete specific list items
item_delete3_response = app.client.slackLists_items_delete(
    list_id=list_id,
    id=item_id_3,
)

item_delete4_5_response = app.client.slackLists_items_deleteMultiple(
    list_id=list_id,
    ids=[item_id_4, item_id_5],
)

# retrieve info for a single list item
item_info = app.client.slackLists_items_info(
    list_id=list_id,
    id=item_id_1,
    include_is_subscribed=True,
)

# retrieve all list items
items_list = app.client.slackLists_items_list(
    list_id=list_id,
    limit=50,
    archived=False,
)

# download list data
download_start_response = app.client.slackLists_download_start(
    list_id=list_id,
    include_archived=False,
)

download_get_response = app.client.slackLists_download_get(
    list_id=list_id,
    job_id=download_start_response["job_id"],
)

# update an existing list item
update_item_response = app.client.slackLists_items_update(
    list_id=list_id,
    cells=[
        {
            "column_id": task_name_col_id,
            "rich_text": [
                {
                    "type": "rich_text",
                    "elements": [
                        {
                            "type": "rich_text_section",
                            "elements": [{"type": "text", "text": "Updated text"}],
                        }
                    ],
                }
            ],
            "row_id": item_id_1,
        }
    ],
)

# update list metadata
update_list_response = app.client.slackLists_update(
    id=list_id,
    name="Test List - UPDATED",
    description_blocks=[
        {
            "type": "rich_text",
            "elements": [
                {
                    "type": "rich_text_section",
                    "elements": [
                        {"type": "text", "text": "This list has been updated via API"}
                    ],
                }
            ],
        }
    ],
    todo_mode=False,
)

# remove access for the test user
list_access_delete = app.client.slackLists_access_delete(
    list_id=list_id,
    user_ids=["U09G4FG3TRN"],
)

Category

• slack_sdk.web.WebClient (sync/async) (Web API client)

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.
• I've run python3 -m venv .venv && source .venv/bin/activate && ./scripts/run_validation.sh after making the changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.54%. Comparing base (e9e64d8) to head (86f56e3).
⚠️ Report is 11 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1772      +/-   ##
==========================================
- Coverage   85.15%   84.54%   -0.62%     
==========================================
  Files         115      115              
  Lines       13068    12543     -525     
==========================================
- Hits        11128    10604     -524     
+ Misses       1940     1939       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[WilliamBergamin]

Nice work working on this 💯

Would it be simple to add integration tests in integration_tests/web for these endpoints?

[zimeg]

@srtaalej Thanks so much for bringing these methods to the SDK! 🧰 ✨

I'm finding good responses from the server when using these changes so am hoping we can merge this soon, but also left comments around typing that I think are worth consideration.

Overall I'm hoping we can improve our models here in the SDK to expect the various list item schemas, similar to Block Kit. This might not be a blocker for python releases, but we might require such for java and I do think we should aim to keep SDKs aligned in featureset when possible!

Lots of rambles. Please let me know if the other comments seem alright! 👾

[zimeg]

🏷️ note: We should update this as well!