streamlit-state-attribute 0.2.3

A lightweight utility to bind class attributes directly to Streamlit's session state, making it easy to persist and share values across reruns.

Streamlit State Attribute

Contents

• Idea
• Advantages
• Install
• Examples
• Background

Idea

Instead of using st.session_state["some_key"], define a typed attribute of some class which is automatically synced with the session state.

from streamlit_state_attribute import StateAttribute
import streamlit as st

class SomeWidget:
    some_attribute: str = StateAttribute(default="test")

some_widget = SomeWidget()
some_widget.some_attribute = "3"
assert st.session_state["SomeWidget.some_attribute"] == "3"

Advantages

• Handling st.session_state is abstracted away
• Autosuggestions + type hints
• Logging each state change (default logging level = debug, can be configured per-attribute)
• Easily build Widgets with their own local state

Install

uv pip install streamlit-state-attribute

Examples

import streamlit as st
from streamlit_state_attribute import StateAttribute

class SomeWidgetWithKey:
    key: str
    some_attribute: str = StateAttribute(default="test", unique_attribute="key")

    def __init__(self, key: str) -> None:
        self.key = key


# Each key will have a separate State
other_widget = SomeWidgetWithKey(key="test")
other_widget.some_attribute = "4"
assert st.session_state["SomeWidgetWithKey.test.some_attribute"] == "4"

See also counter.py and global_state.py.

Background

Made to play around with descriptors after a workshop descriptors at Pycon2025.