slackblocks

Licence: MIT Licence: BSD-3-Clause Python Versions PyPI Downloads Build Status Docs

Build Slack messages in Python — without writing JSON by hand.

slackblocks is a typed, validating Python wrapper around the Slack Block Kit API. It exists because Block Kit JSON is verbose, easy to get subtly wrong, and unpleasant to maintain in source control.

This release conforms to the shared cross-language slackblocks specification.

Why slackblocks?

  • Concise — SectionBlock("Hello, *world*!") instead of a 10-line JSON object.
  • Validated — character limits, required fields, mutually-exclusive options, and element-type restrictions are enforced at construction time, so you find out before hitting Slack's API.
  • Drop-in compatible with both the official slack-sdk and the legacy slackclient — unpack a Message directly into client.chat_postMessage(**message).
  • Typed — full type hints; ships py.typed.
  • Zero runtime dependencies.

Installation

pip install slackblocks

slackblocks 2.x requires Python 3.10 or newer. Users on Python 3.8 / 3.9 should pin to the 1.x line — see the Compatibility page.

Quickstart

from slackblocks import (
    ActionsBlock,
    Button,
    DividerBlock,
    HeaderBlock,
    Message,
    SectionBlock,
)

message = Message(
    channel="#general",
    text="Build #482 passed",  # plain-text fallback for notifications
    blocks=[
        HeaderBlock("Build #482 passed :white_check_mark:"),
        SectionBlock(
            fields=[
                "*Branch*\n`main`",
                "*Author*\n@nick",
                "*Duration*\n3m 12s",
                "*Tests*\n1,247 passed",
            ],
        ),
        DividerBlock(),
        ActionsBlock(
            elements=[
                Button(text="View build", action_id="view", url="https://ci.example.com/482"),
                Button(text="Re-run", action_id="rerun", value="482", style="primary"),
            ],
        ),
    ],
)

message can be sent in one line with the official Slack SDK:

import os
from slack_sdk import WebClient

client = WebClient(token=os.environ["SLACK_API_TOKEN"])
client.chat_postMessage(**message)

The ** operator unpacks slackblocks Message objects directly into the SDK call — no to_dict() boilerplate required.

A simple Slack message rendered in Slack

What's supported

Surface Status
Blocks ✅ All current block types, including Alert, Card, Carousel, Container, Context Actions, Data Table, Data Visualization, Plan, and Task Card
Elements ✅ Buttons, all select menus, date/time pickers, checkboxes, radio groups, all input types, overflow menus, workflow buttons
Composition Objects ✅ Text (+ PlainText / Markdown aliases), Option, Confirm, Conversation/Dispatch filters, Workflow, Trigger
Rich Text ✅ Sections, lists, quotes, code blocks, inline links/users/channels/emoji
Modals & Home Tabs ✅ Full views API
Messages ✅ chat.postMessage, webhook messages, slash-command/interaction responses, threaded replies, ephemeral messages
Attachments ⚠️ Supported but deprecated by Slack
Round-tripping ✅ Block.from_dict(data) and per-class from_dict for parsing incoming Slack JSON back into objects

What's new in 2.0

slackblocks 2.x is the first major release in the modernised line. Highlights:

  • Two new block types: MarkdownBlock (GitHub-flavored Markdown) and VideoBlock.
  • PlainText and Markdown thin aliases for Text(type_=...).
  • block_kit_builder_url(payload) — turn any block, message, or view into a Block Kit Builder URL for browser preview.
  • Workflow.from_url(url, **params) — one-line workflow construction.
  • Block.from_dict(data) + per-class from_dict parsers — round-trip incoming Slack JSON back into slackblocks objects.
  • Typed exception subclasses of InvalidUsageError (LengthError, RangeError, TypeMismatchError, MutualExclusivityError, MissingRequiredError) — existing except InvalidUsageError blocks continue to work.
  • Tighter type signatures: Literal narrowing on Button.style, ColumnSettings.align, ConversationFilter.include; @overload on Text.to_text so the return type narrows on allow_none.
  • Modern annotation syntax (list[X], X | Y) throughout.

Existing 1.x code continues to work unchanged; see the Migration Guide for the full diff.

Documentation

Comparison with slack-sdk block classes

The official slack-sdk ships its own block classes. slackblocks predates them and offers a more concise API, stricter up-front validation, and independent versioning. They produce equivalent JSON; pick whichever you find more ergonomic.

# slackblocks
SectionBlock("Hello, *world*!")

# slack-sdk equivalent
from slack_sdk.models.blocks import SectionBlock as SDKSectionBlock
from slack_sdk.models.blocks.basic_components import MarkdownTextObject
SDKSectionBlock(text=MarkdownTextObject(text="Hello, *world*!"))

Licensing

slackblocks is dual-licensed under MIT and BSD-3-Clause. Use whichever fits your project — this makes it safe to vendor into projects under either license.

Contributing

Contributions are welcome. Quick start (the project uses uv for dependency management):

git clone https://github.com/nicklambourne/slackblocks.git
cd slackblocks/python
uv sync --all-groups

uv run pytest test/unit test/conformance test/docs
uv run ruff format --check slackblocks test
uv run ruff check slackblocks test
uv run mypy slackblocks

Preview the documentation from the repository root with pnpm --filter @slackblocks/docs start.

For the full development guide — testing conventions, validation patterns, docstring style, release process, and a PR checklist — see the Contributing page.

Bug reports and feature requests: https://github.com/nicklambourne/slackblocks/issues.

Project links

Data verified by PyPI on Aug 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nicklambourne from gravatar.com nicklambourne

Credits

Author/Maintainer: Nicholas Lambourne

GitHub Statistics

Data verified by PyPI on Aug 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD License, MIT License (MIT)

Requires

Python >=3.10

Tags

blocks message generation messaging slack slack blocks slackblocks

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

slackblocks-2.2.0.tar.gz (189.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

slackblocks-2.2.0-py3-none-any.whl (58.2 kB view details)

Uploaded Python 3

File details

Details for the file slackblocks-2.2.0.tar.gz.

File metadata

  • Download URL: slackblocks-2.2.0.tar.gz
  • Upload date:
  • Size: 189.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for slackblocks-2.2.0.tar.gz
Algorithm Hash digest
SHA256 e38155551c7423853511dd7619a3854fad6ee05aebec8ba756ddd247ed13c5a6
MD5 a4dc9a2b1f50ce084a84fb47446115da
BLAKE2b-256 84c15ef276d81932413e0ac1734db189caa2416f3e86ddb285f2e2308ecdcc1e

See more details on using hashes here.

File details

Details for the file slackblocks-2.2.0-py3-none-any.whl.

File metadata

  • Download URL: slackblocks-2.2.0-py3-none-any.whl
  • Upload date:
  • Size: 58.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for slackblocks-2.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d8a37f1f8d613a65dafbc6b5b5465e448c107f2fe55c195848e3f759497ac855
MD5 4b9f6319cbfc5391a7c3b6d2f2b88ded
BLAKE2b-256 2e5528c3d045b8bbbbd233f512b433641b5e7f4da481c2146ab57e1c544102f7

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

2.2.0 This release

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

Yanked

2.0.0rc1

2 files

Yanked reason: Removed in favour of the official 2.0.0 release

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.1.1

2 files

1.0.16

2 files

1.0.15

2 files

1.0.14

2 files

1.0.13

2 files

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.13

2 files

0.9.12

2 files

0.9.11

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.3.1

2 files

0.2.5

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page