fix(models): type CardBlock icon/hero_image as image element (not str) by zimeg · Pull Request #1937 · slackapi/python-slack-sdk · GitHub

Summary

The card block reference specifies that icon and hero_image are image element objects ({"type": "image", "image_url": ..., "alt_text": ...}), not plain URL strings. But CardBlock typed both as Optional[str], so passing an ImageElement — the correct, accessible form (it carries alt_text) — raised a mypy [arg-type] error and forced callers to use # type: ignore.

This widens both parameters to Optional[Union[str, dict, ImageElement]], matching how title/subtitle/body already accept Union[str, dict, TextObject].

Details

slack_sdk/models/blocks/blocks.py — CardBlock.__init__: hero_image/icon typed Optional[Union[str, dict, ImageElement]]; docstrings updated to the reference wording (incl. the max-length notes).
Runtime behavior is unchanged — serialization already handled all three forms: str → bare URL (back-compat, still covered by test_document), dict/ImageElement → the object shape. This is a type-widening only.
Adds test_image_element_icon_and_hero_image asserting the ImageElement form round-trips to the documented object.

Testing

pytest tests/slack_sdk/models/test_blocks.py — 85 passed (incl. the new test; no regressions).
mypy slack_sdk/models/blocks/blocks.py — clean.

Motivation

Downstream: the Bolt bolt-python-examples card/carousel examples build icon/hero_image with ImageElement (docs-correct) and currently need # type: ignore[arg-type] because of this mis-typing. This fix lets those examples drop the suppression.

🤖 Generated with Claude Code

Per the card block reference, `icon` and `hero_image` are image element objects (`type`/`image_url`/`alt_text`), not plain URL strings — but CardBlock typed them as Optional[str], so passing an ImageElement (the correct, accessible form with alt_text) tripped mypy [arg-type]. Widen both to Optional[Union[str, dict, ImageElement]], matching how title/subtitle/body already accept Union[str, dict, TextObject]. Runtime serialization is unchanged (str -> bare URL, dict/ImageElement -> object); this only broadens the accepted/typed input. Docstrings updated to the reference wording. Adds a test asserting the ImageElement form round-trips. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Examples should not carry type-checker suppressions. Remove the # type: ignore[arg-type] added for the ImageElement icon/hero_image args. Until slackapi/python-slack-sdk#1937 lands (widening CardBlock.icon / hero_image to accept an image element), mypy reports [arg-type] here by design — the honest signal that slack_sdk mis-types these fields as str. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Examples should not carry type-checker suppressions. Remove the # type: ignore[arg-type] on the ImageElement icon/hero_image args. Until slackapi/python-slack-sdk#1937 lands (widening CardBlock.icon / hero_image to accept an image element), mypy reports [arg-type] here by design — the honest signal that slack_sdk mis-types these fields as str. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Note on keeping str in the type

The card block reference documents icon/hero_image as image-element objects only — it never shows a bare URL string. So one could argue for typing these as Union[dict, ImageElement] (object-only).

This PR deliberately keeps str (Union[str, dict, ImageElement]) because:

The string form is already shipped and tested (CardBlockTests.test_document passes icon/hero_image as URL strings and round-trips them). Dropping str would be a breaking change (semver:major) and would fail that test.
This change is purely additive — it widens the accepted/typed input to include the docs-correct object form, without removing the existing behavior. That keeps it semver:minor.

If maintainers prefer to make these object-only, that'd be a separate major-version change (update test_document, drop str). Happy to follow up if that's the preference.

Slack's card block schema (and the docs reference) define icon/hero_image as image element objects — a bare URL string is not a valid payload and is rejected by the API. CardBlock previously typed them as Optional[str], modeling a form that does not actually work end to end. Type both as Optional[Union[dict, ImageElement]] (object-only), matching title/subtitle/body's object-based typing. Update test_document to the documented object form (it previously passed bare-string icons). Runtime serialization of an ImageElement/dict was already correct; this drops the never-valid str form. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.17%. Comparing base (c2eacc2) to head (bb2a6a1).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1937   +/-   ##
=======================================
  Coverage   84.17%   84.17%           
=======================================
  Files         118      118           
  Lines       13425    13425           
=======================================
  Hits        11301    11301           
  Misses       2124     2124

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

Leaving a callout on the breaking change that I'm marking as a patch update 📣

⚠️ note: The str option is removed which typechecking might complain about but this matches what's valid with the API itself:

https://app.slack.com/block-kit-builder#%7B%22blocks%22:%5B%7B%22type%22:%22card%22,%22icon%22:%22https://picsum.photos/36/36%22,%22title%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22Lumon%20Industries%22,%22verbatim%22:false%7D,%22subtitle%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22Committed%20to%20work-life%20balance%22,%22verbatim%22:false%7D,%22hero_image%22:%22https://picsum.photos/400/300%22,%22body%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22Please%20enjoy%20each%20card%20equally.%22,%22verbatim%22:false%7D,%22actions%22:%5B%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22Action%20Button%22,%22emoji%22:false%7D,%22action_id%22:%22button_action%22%7D%5D%7D%5D%7D

Interesting 🤔 lets do a minor for this and point it out in the release notes ❤️

Thanks for working on this 💯

Interesting 🤔 lets do a minor for this and point it out in the release notes ❤️

@WilliamBergamin And thanks for a review and note on versioning for this change 🔏 I'll merge this now after confirming once more the error following with prior string values:

invalid_blocks

zimeg requested a review from a team as a code owner August 4, 2026 23:05

zimeg added bug M-T: A confirmed bug report. Issues are confirmed when the reproduction steps are documented semver:minor python Pull requests that update Python code Version: 3x labels Aug 4, 2026

zimeg self-assigned this Aug 4, 2026

zimeg added this to the 3.x milestone Aug 4, 2026

This was referenced Aug 4, 2026

feat(block-kit): add carousel block example slack-samples/bolt-python-examples#97

Draft

feat(block-kit): add card block example slack-samples/bolt-python-examples#102

Draft

zimeg changed the title fix(models): CardBlock icon/hero_image accept an image element fix(models): type CardBlock icon/hero_image as image element (not str) Aug 4, 2026

zimeg added semver:major and removed semver:minor labels Aug 4, 2026

zimeg modified the milestones: 3.x, 3.44.0 Aug 4, 2026

zimeg added semver:patch and removed semver:major labels Aug 4, 2026

zimeg commented Aug 4, 2026

View reviewed changes

WilliamBergamin approved these changes Aug 5, 2026

View reviewed changes

zimeg added semver:minor and removed semver:patch labels Aug 5, 2026

zimeg merged commit ae87985 into main Aug 6, 2026
18 checks passed

zimeg deleted the feat/card-block-image-element-typing branch August 6, 2026 04:02

fix(models): type CardBlock icon/hero_image as image element (not str) by zimeg · Pull Request #1937 · slackapi/python-slack-sdk · GitHub

Uh oh!

fix(models): type CardBlock icon/hero_image as image element (not str) - #1937

fix(models): type CardBlock icon/hero_image as image element (not str)#1937
zimeg merged 2 commits into
mainfrom
feat/card-block-image-element-typing

zimeg commented Aug 4, 2026

Uh oh!

zimeg commented Aug 4, 2026

Uh oh!

codecov Bot commented Aug 4, 2026

Uh oh!

zimeg left a comment

Uh oh!

zimeg Aug 4, 2026

Uh oh!

WilliamBergamin Aug 5, 2026

Uh oh!

WilliamBergamin left a comment

Uh oh!

WilliamBergamin Aug 5, 2026

Uh oh!

zimeg commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		hero_image: Optional[str] = None,
		icon: Optional[str] = None,

fix(models): type CardBlock icon/hero_image as image element (not str) by zimeg · Pull Request #1937 · slackapi/python-slack-sdk · GitHub

Uh oh!

fix(models): type CardBlock icon/hero_image as image element (not str) - #1937

fix(models): type CardBlock icon/hero_image as image element (not str)#1937zimeg merged 2 commits intomainslackapi/python-slack-sdk:mainfrom feat/card-block-image-element-typingslackapi/python-slack-sdk:feat/card-block-image-element-typingCopy head branch name to clipboard

Conversation

zimeg commented Aug 4, 2026

Summary

Details

Testing

Motivation

Uh oh!

zimeg commented Aug 4, 2026

Uh oh!

codecov Bot commented Aug 4, 2026

Codecov Report

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

zimeg Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin left a comment

Choose a reason for hiding this comment

Uh oh!

WilliamBergamin Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

zimeg commented Aug 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fix(models): type CardBlock icon/hero_image as image element (not str)#1937
zimeg merged 2 commits into
mainfrom
feat/card-block-image-element-typing