{"id":15501685,"url":"https://github.com/whitphx/streamlit-server-state","last_synced_at":"2025-05-16T06:05:27.954Z","repository":{"id":38302342,"uuid":"378999709","full_name":"whitphx/streamlit-server-state","owner":"whitphx","description":"A \"server-wide\" state object shared across sessions on a Streamlit server.","archived":false,"fork":false,"pushed_at":"2025-04-07T13:20:19.000Z","size":508,"stargazers_count":148,"open_issues_count":12,"forks_count":15,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-08T18:18:44.194Z","etag":null,"topics":["hacktoberfest","streamlit"],"latest_commit_sha":null,"homepage":"https://discuss.streamlit.io/t/new-library-streamlit-server-state-a-new-way-to-share-states-over-the-sessions-on-the-server/14981","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whitphx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["whitphx"],"patreon":"whitphx","open_collective":null,"ko_fi":"whitphx","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.buymeacoffee.com/whitphx"]}},"created_at":"2021-06-21T16:45:08.000Z","updated_at":"2025-04-07T13:20:22.000Z","dependencies_parsed_at":"2024-06-19T01:36:32.367Z","dependency_job_id":"5ce5436e-3a9c-4e0a-a4ba-d3ab75c37b78","html_url":"https://github.com/whitphx/streamlit-server-state","commit_stats":{"total_commits":185,"total_committers":3,"mean_commits":"61.666666666666664","dds":"0.33513513513513515","last_synced_commit":"d76ac77fac8f239f4fa79509cc935a30eaab03ca"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whitphx%2Fstreamlit-server-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whitphx%2Fstreamlit-server-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whitphx%2Fstreamlit-server-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whitphx%2Fstreamlit-server-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whitphx","download_url":"https://codeload.github.com/whitphx/streamlit-server-state/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478187,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","streamlit"],"created_at":"2024-10-02T09:05:19.899Z","updated_at":"2025-05-16T06:05:27.918Z","avatar_url":"https://github.com/whitphx.png","language":"Python","funding_links":["https://github.com/sponsors/whitphx","https://patreon.com/whitphx","https://ko-fi.com/whitphx","https://www.buymeacoffee.com/whitphx","https://ko-fi.com/D1D2ERWFG"],"categories":[],"sub_categories":[],"readme":"# streamlit-server-state\nA \"server-wide\" state shared across the sessions.\n\n[![Tests](https://github.com/whitphx/streamlit-server-state/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/whitphx/streamlit-server-state/actions/workflows/tests.yml?query=branch%3Amain)\n\n[![PyPI](https://img.shields.io/pypi/v/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)\n[![PyPI - License](https://img.shields.io/pypi/l/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/D1D2ERWFG)\n\n\u003ca href=\"https://www.buymeacoffee.com/whitphx\" target=\"_blank\" rel=\"noreferrer\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" width=\"180\" height=\"50\" \u003e\u003c/a\u003e\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/whitphx?label=Sponsor%20me%20on%20GitHub%20Sponsors\u0026style=social)](https://github.com/sponsors/whitphx)\n\n```python\nimport streamlit as st\n\nfrom streamlit_server_state import server_state, server_state_lock\n\nst.title(\"Global Counter Example\")\n\nwith server_state_lock[\"count\"]:  # Lock the \"count\" state for thread-safety\n    if \"count\" not in server_state:\n        server_state.count = 0\n\nincrement = st.button(\"Increment\")\nif increment:\n    with server_state_lock.count:\n        server_state.count += 1\n\ndecrement = st.button(\"Decrement\")\nif decrement:\n    with server_state_lock.count:\n        server_state.count -= 1\n\nst.write(\"Count = \", server_state.count)\n\n```\n\nAs above, the API is similar to [the built-in SessionState](https://blog.streamlit.io/session-state-for-streamlit/), except one major difference - a \"lock\" object.\nThe lock object is introduced for thread-safety because the server-state is accessed from multiple sessions, i.e. threads.\n\n## Auto-rerun\nWhen you assign a value to a server-state item, `server-state[key]`,\nserver-state automatically triggers re-running of all other sessions in which that server-state item is referred to so that all the references to the server-state return the latest value and all the sessions are kept up-to-date.\n\nFor example, with this mechanism, the [sample chat app (`app_chat.py`)](./app_chat.py) keeps showing the latest message list for all users.\n\n### Suppressing auto-rerun\n\nWhen this auto-rerun mechanism is not good for your use case, you can suppress auto-reruns upon the value assignments by using `no_rerun` context as below.\n```python\nfrom streamlit_server_state import server_state, no_rerun\n\n\nwith no_rerun:\n    server_state[\"foo\"] = 42  # This does not trigger re-running of other sessions\n```\n\n### Manually trigger re-running\nUpon each value assignment, server-state checks whether the value has been changed and skips re-running if it has not for efficiency.\nThis works well in most cases, but it does not for example when the value is a complex mutable object and its field is mutated, while such usages are not recommended.\n\nAs exceptions, in such cases where the auto-rerun mechanism does not work well, you can manually trigger re-running by using `force_rerun_bound_sessions(key)`.\n\n```python\nif \"foo\" not in server_state:\n    server_state[\"foo\"] = SomeComplexObject()\n\nserver_state[\"foo\"].field = 42  # If this assignment does not trigger re-running,\n\nforce_rerun_bound_sessions(\"foo\")  # You can do this.\n```\n\nBackground: https://discuss.streamlit.io/t/new-library-streamlit-server-state-a-new-way-to-share-states-across-sessions-on-the-server/14981/10\n\n## Examples\n* [`app_global_count`](./app_global_count.py): A sample app like [the official counter example for SessionState](https://blog.streamlit.io/session-state-for-streamlit/) which uses `streamlit-server-state` instead and the counter is shared among all the sessions on the server. This is a nice small example to see the usage and behavior of `streamlit-server-state`. Try to open the app in multiple browser tabs and see the counter is shared among them.\n* [`app_global_slider`](./pages/app_global_slider.py): A slider widget (`st.slider`) whose value is shared among all sessions.\n* [`app_chat.py`](./pages/app_chat.py): A simple chat app using `streamlit-server-state`.\n* [`app_chat_rooms.py`](./pages/app_chat_rooms.py): A simple chat app with room separation.\n  [![Open in Streamlit](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://share.streamlit.io/whitphx/streamlit-server-state/main/app_chat_rooms.py)\n\n## Resources\n* [New library: streamlit-server-state, a new way to share states among the sessions on the server (Streamlit Community)](https://discuss.streamlit.io/t/new-library-streamlit-server-state-a-new-way-to-share-states-among-the-sessions-on-the-server/14981)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhitphx%2Fstreamlit-server-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhitphx%2Fstreamlit-server-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhitphx%2Fstreamlit-server-state/lists"}