# Streamlit State Model
I love Streamlit, but working with `st.session_state` can be tedious. Coming from an OOP background, I cringe at managing each key in `st.session_state` individually, checking if it exists, and losing intellisense for names and types.
So I made `streamlit-state-model` which offers a base class `StateModel` that you can subclass to push your class' attribute I/O directly into `st.session_state`. This means you define what should exist in `st.session_state` once in the form of a normal python class, and then access those values anywhere in your Streamlit app with the expected statefulness of `st.session_state`.
## Features
- **Persistence:** Class instance storage is pushed to `st.session_state` so class attribute values are retained across page refreshes and switches (in multi-page apps).
- **Easy Setup:** `StateModel` can be used with existing or new class definitions.
- **Default Values:** Define the default state of `st.session_state` with normal class' default annotations and gain the ability to reset them all to defaults with a single function call.
- **Debugging:** When debugging, you can now see the current values in `st.session_state` by inspecting your class' attribute values.
- **Intellisense Support:** Retain normal docstrings and type intellisense that you normally lose when working with `st.session_state`.
- **Inline Integration:** Declare your class instance inline with the rest of your code and eliminate spaghetti `if` checks around current state of `st.session_state`.
- **Docstring Access:** Retrieve attribute docstrings via the `docstrings` dictionary within your app.
## Getting Started
Install the package using pip:
```bash
pip install streamlit-state-model
```
Take your existing class and subclass `StateModel`:
```python
import streamlit_state_model as ssm
class Session(ssm.StateModel):
favorite_color: str = "#252D3D"
"The user's favorite color as a hex string."
favorite_number: int = 0
"The user's favorite number."
```
At the entry point of your app, initialize your class in "build" mode.
```python
# streamlit_app.py
session = Session(mode="build")
st.write(session.favorite_number) # outputs default value of 0
session.favorite_number = 1 # set to a new value
```
Anywhere else in your app you can initialize in lazy (default) mode to access current values:
```python
# pages/page_1.py
session = Session() # init in lazy mode
st.write(session.favorite_number) # outputs 1 as set in streamlit_app.py
""
```
## Example
Explore our demo Streamlit app in the `/demo_app` directory for an example of integrating `StateModel` into a multipage app on Streamlit Community Cloud. Check out: [state-model-demo-app](https://state-model-demo-app.streamlit.app/).
We're also working on generating API docs for `StateModel` since it already includes many helper functions such as:
- `dump()`: Dump all class attribute values to a JSON string (often paired with `st.json`).
- Widget interaction helpers: Utilize widgets with `StateModel` following Streamlit's recommended patterns. (See the [Streamlit Documentation on Multipage Apps](https://docs.streamlit.io/develop/concepts/multipage-apps/widgets) for details.)
- Reset function: Reset all attribute values to their defaults.
## Development
For details on contributing and the CI/CD process, please refer to the [development documentation](docs/development.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "streamlit-state-model",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "streamlit, state, model, session_state",
"author": null,
"author_email": "Trenton Smith <trenton@databutsmart.com>",
"download_url": "https://files.pythonhosted.org/packages/8e/71/fcb3e25694e90e97c68a8471fc621c886a9508e976367ac560c2b3f6380e/streamlit_state_model-0.2.4.tar.gz",
"platform": null,
"description": "# Streamlit State Model\n\nI love Streamlit, but working with `st.session_state` can be tedious. Coming from an OOP background, I cringe at managing each key in `st.session_state` individually, checking if it exists, and losing intellisense for names and types.\n\nSo I made `streamlit-state-model` which offers a base class `StateModel` that you can subclass to push your class' attribute I/O directly into `st.session_state`. This means you define what should exist in `st.session_state` once in the form of a normal python class, and then access those values anywhere in your Streamlit app with the expected statefulness of `st.session_state`.\n\n## Features\n\n- **Persistence:** Class instance storage is pushed to `st.session_state` so class attribute values are retained across page refreshes and switches (in multi-page apps).\n- **Easy Setup:** `StateModel` can be used with existing or new class definitions.\n- **Default Values:** Define the default state of `st.session_state` with normal class' default annotations and gain the ability to reset them all to defaults with a single function call. \n- **Debugging:** When debugging, you can now see the current values in `st.session_state` by inspecting your class' attribute values.\n- **Intellisense Support:** Retain normal docstrings and type intellisense that you normally lose when working with `st.session_state`.\n- **Inline Integration:** Declare your class instance inline with the rest of your code and eliminate spaghetti `if` checks around current state of `st.session_state`.\n- **Docstring Access:** Retrieve attribute docstrings via the `docstrings` dictionary within your app.\n\n## Getting Started\n\nInstall the package using pip:\n\n```bash\npip install streamlit-state-model\n``` \n\nTake your existing class and subclass `StateModel`:\n```python\nimport streamlit_state_model as ssm \n\nclass Session(ssm.StateModel):\n favorite_color: str = \"#252D3D\"\n \"The user's favorite color as a hex string.\"\n favorite_number: int = 0\n \"The user's favorite number.\"\n```\n \nAt the entry point of your app, initialize your class in \"build\" mode.\n```python \n# streamlit_app.py\nsession = Session(mode=\"build\")\nst.write(session.favorite_number) # outputs default value of 0\nsession.favorite_number = 1 # set to a new value \n```\nAnywhere else in your app you can initialize in lazy (default) mode to access current values:\n```python\n# pages/page_1.py\nsession = Session() # init in lazy mode\nst.write(session.favorite_number) # outputs 1 as set in streamlit_app.py \n\"\"\n``` \n\n## Example\n\nExplore our demo Streamlit app in the `/demo_app` directory for an example of integrating `StateModel` into a multipage app on Streamlit Community Cloud. Check out: [state-model-demo-app](https://state-model-demo-app.streamlit.app/).\n\nWe're also working on generating API docs for `StateModel` since it already includes many helper functions such as:\n- `dump()`: Dump all class attribute values to a JSON string (often paired with `st.json`).\n- Widget interaction helpers: Utilize widgets with `StateModel` following Streamlit's recommended patterns. (See the [Streamlit Documentation on Multipage Apps](https://docs.streamlit.io/develop/concepts/multipage-apps/widgets) for details.)\n- Reset function: Reset all attribute values to their defaults.\n\n## Development\n\nFor details on contributing and the CI/CD process, please refer to the [development documentation](docs/development.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "A package that provides a StateModel for Streamlit applications, allowing easy management of session state through class attributes.",
"version": "0.2.4",
"project_urls": {
"Documentation": "https://github.com/trenton-ftw/streamlit-state-model#readme",
"Homepage": "https://github.com/trenton-ftw/streamlit-state-model",
"Source": "https://github.com/trenton-ftw/streamlit-state-model",
"Tracker": "https://github.com/trenton-ftw/streamlit-state-model/issues"
},
"split_keywords": [
"streamlit",
" state",
" model",
" session_state"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb77a462c4c6bab6087d5c9f44a8b20bce49d518c8d0eef7ef7b8a75e84e2fff",
"md5": "90dd818fda61ff172e26d106f3663b61",
"sha256": "1c381970557bdb0c86fe1e82f527d531ec3b05f74b3780d147aff02dfdd891b3"
},
"downloads": -1,
"filename": "streamlit_state_model-0.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90dd818fda61ff172e26d106f3663b61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7486,
"upload_time": "2025-02-16T20:37:32",
"upload_time_iso_8601": "2025-02-16T20:37:32.669843Z",
"url": "https://files.pythonhosted.org/packages/eb/77/a462c4c6bab6087d5c9f44a8b20bce49d518c8d0eef7ef7b8a75e84e2fff/streamlit_state_model-0.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8e71fcb3e25694e90e97c68a8471fc621c886a9508e976367ac560c2b3f6380e",
"md5": "1caa90b282916de882e9cb1af8d83d06",
"sha256": "c31faa82590b5c790d46e81570033adc559f975086d85dd1418aec7c2d9608c7"
},
"downloads": -1,
"filename": "streamlit_state_model-0.2.4.tar.gz",
"has_sig": false,
"md5_digest": "1caa90b282916de882e9cb1af8d83d06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11789,
"upload_time": "2025-02-16T20:37:34",
"upload_time_iso_8601": "2025-02-16T20:37:34.519305Z",
"url": "https://files.pythonhosted.org/packages/8e/71/fcb3e25694e90e97c68a8471fc621c886a9508e976367ac560c2b3f6380e/streamlit_state_model-0.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-16 20:37:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "trenton-ftw",
"github_project": "streamlit-state-model#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "streamlit",
"specs": []
},
{
"name": "streamlit-state-model",
"specs": []
}
],
"lcname": "streamlit-state-model"
}
JSON
