# Streamlit State Attribute
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Contents**
- [Idea](#idea)
- [Advantages](#advantages)
- [Install](#install)
- [Examples](#examples)
- [Background](#background)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Idea
Instead of using `st.session_state["some_key"]`, define a typed attribute of some class which is automatically synced
with the session state.
```python
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
```bash
uv pip install streamlit-state-attribute
```
## Examples
```python
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](src/examples/counter.py) and [global_state.py](src/examples/counter.py).
## Background
Made to play around with [descriptors](https://docs.python.org/3/howto/descriptor.html) after a [workshop descriptors
at Pycon2025](https://pretalx.com/pyconde-pydata-2025/talk/WJPEQH/).
Raw data
{
"_id": null,
"home_page": null,
"name": "streamlit-state-attribute",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "streamlit, session state, state management, attributes, sync",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f4/dd/b8cdf95cc809fb8cddf1f02460f385b15d9257dd88811f0bc6c3d1710c41/streamlit_state_attribute-0.2.3.tar.gz",
"platform": null,
"description": "# Streamlit State Attribute\n\n<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n**Contents**\n\n- [Idea](#idea)\n- [Advantages](#advantages)\n- [Install](#install)\n- [Examples](#examples)\n- [Background](#background)\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n## Idea\nInstead of using `st.session_state[\"some_key\"]`, define a typed attribute of some class which is automatically synced\nwith the session state.\n\n```python\nfrom streamlit_state_attribute import StateAttribute\nimport streamlit as st\n\nclass SomeWidget:\n some_attribute: str = StateAttribute(default=\"test\")\n\nsome_widget = SomeWidget()\nsome_widget.some_attribute = \"3\"\nassert st.session_state[\"SomeWidget.some_attribute\"] == \"3\"\n```\n\n## Advantages\n * Handling `st.session_state` is abstracted away\n * Autosuggestions + type hints\n * Logging each state change (default logging level = debug, can be configured per-attribute)\n * Easily build Widgets with their own local state\n\n## Install\n```bash\nuv pip install streamlit-state-attribute\n```\n\n## Examples\n```python\nimport streamlit as st\nfrom streamlit_state_attribute import StateAttribute\n\nclass SomeWidgetWithKey:\n key: str\n some_attribute: str = StateAttribute(default=\"test\", unique_attribute=\"key\")\n\n def __init__(self, key: str) -> None:\n self.key = key\n\n\n# Each key will have a separate State\nother_widget = SomeWidgetWithKey(key=\"test\")\nother_widget.some_attribute = \"4\"\nassert st.session_state[\"SomeWidgetWithKey.test.some_attribute\"] == \"4\"\n```\nSee also [counter.py](src/examples/counter.py) and [global_state.py](src/examples/counter.py).\n\n## Background\nMade to play around with [descriptors](https://docs.python.org/3/howto/descriptor.html) after a [workshop descriptors\nat Pycon2025](https://pretalx.com/pyconde-pydata-2025/talk/WJPEQH/).\n",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight utility to bind class attributes directly to Streamlit's session state, making it easy to persist and share values across reruns.",
"version": "0.2.3",
"project_urls": null,
"split_keywords": [
"streamlit",
" session state",
" state management",
" attributes",
" sync"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "00a753f5c020447be214e89c5317a4b5cc61223b3295fe9baed9fd653c77f60c",
"md5": "b4548f4fee41809ca1dbc65873b81930",
"sha256": "72cc5e24bc8b79b6adc50affcd5c68d971f4938e70dfc46ee665294e665098ce"
},
"downloads": -1,
"filename": "streamlit_state_attribute-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4548f4fee41809ca1dbc65873b81930",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5446,
"upload_time": "2025-09-06T20:36:13",
"upload_time_iso_8601": "2025-09-06T20:36:13.026268Z",
"url": "https://files.pythonhosted.org/packages/00/a7/53f5c020447be214e89c5317a4b5cc61223b3295fe9baed9fd653c77f60c/streamlit_state_attribute-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f4ddb8cdf95cc809fb8cddf1f02460f385b15d9257dd88811f0bc6c3d1710c41",
"md5": "34a977920204df26abb043433800261d",
"sha256": "b4dd99eea375681bf55f8c284b2fbd0117b20a504412e4063a8843d4bb29adf3"
},
"downloads": -1,
"filename": "streamlit_state_attribute-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "34a977920204df26abb043433800261d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 5070,
"upload_time": "2025-09-06T20:36:14",
"upload_time_iso_8601": "2025-09-06T20:36:14.098351Z",
"url": "https://files.pythonhosted.org/packages/f4/dd/b8cdf95cc809fb8cddf1f02460f385b15d9257dd88811f0bc6c3d1710c41/streamlit_state_attribute-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 20:36:14",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "streamlit-state-attribute"
}
JSON