streamlit-server-state


Namestreamlit-server-state JSON
Version 0.17.1 PyPI version JSON
download
home_pagehttps://github.com/whitphx/streamlit-server-state
Summary
upload_time2023-08-21 03:36:05
maintainer
docs_urlNone
authorYuichiro Tachibana (Tsuchiya)
requires_python>=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # streamlit-server-state
A "server-wide" state shared across the sessions.

[![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)

[![PyPI](https://img.shields.io/pypi/v/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)
[![PyPI - License](https://img.shields.io/pypi/l/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/streamlit-server-state)](https://pypi.org/project/streamlit-server-state/)

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/D1D2ERWFG)

<a href="https://www.buymeacoffee.com/whitphx" target="_blank" rel="noreferrer"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="180" height="50" ></a>

[![GitHub Sponsors](https://img.shields.io/github/sponsors/whitphx?label=Sponsor%20me%20on%20GitHub%20Sponsors&style=social)](https://github.com/sponsors/whitphx)

```python
import streamlit as st

from streamlit_server_state import server_state, server_state_lock

st.title("Global Counter Example")

with server_state_lock["count"]:  # Lock the "count" state for thread-safety
    if "count" not in server_state:
        server_state.count = 0

increment = st.button("Increment")
if increment:
    with server_state_lock.count:
        server_state.count += 1

decrement = st.button("Decrement")
if decrement:
    with server_state_lock.count:
        server_state.count -= 1

st.write("Count = ", server_state.count)

```

As 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.
The lock object is introduced for thread-safety because the server-state is accessed from multiple sessions, i.e. threads.

## Auto-rerun
When you assign a value to a server-state item, `server-state[key]`,
server-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.

For example, with this mechanism, the [sample chat app (`app_chat.py`)](./app_chat.py) keeps showing the latest message list for all users.

### Suppressing auto-rerun

When 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.
```python
from streamlit_server_state import server_state, no_rerun


with no_rerun:
    server_state["foo"] = 42  # This does not trigger re-running of other sessions
```

### Manually trigger re-running
Upon each value assignment, server-state checks whether the value has been changed and skips re-running if it has not for efficiency.
This 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.

As 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)`.

```python
if "foo" not in server_state:
    server_state["foo"] = SomeComplexObject()

server_state["foo"].field = 42  # If this assignment does not trigger re-running,

force_rerun_bound_sessions("foo")  # You can do this.
```

Background: https://discuss.streamlit.io/t/new-library-streamlit-server-state-a-new-way-to-share-states-across-sessions-on-the-server/14981/10

## Examples
* [`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.
* [`app_global_slider`](./app_global_slider.py): A slider widget (`st.slider`) whose value is shared among all sessions.
* [`app_chat.py`](./app_chat.py): A simple chat app using `streamlit-server-state`.
* [`app_chat_rooms.py`](./app_chat_rooms.py): A simple chat app with room separation.
  [![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)

## Resources
* [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)

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/whitphx/streamlit-server-state",
    "name": "streamlit-server-state",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
    "maintainer_email": "",
    "keywords": "",
    "author": "Yuichiro Tachibana (Tsuchiya)",
    "author_email": "t.yic.yt@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/83/5a/8087e1ecb6be590d2c79c9fd66faf302c5031a82c61fc3d4a7164d939d3c/streamlit_server_state-0.17.1.tar.gz",
    "platform": null,
    "description": "# 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<a href=\"https://www.buymeacoffee.com/whitphx\" target=\"_blank\" rel=\"noreferrer\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" width=\"180\" height=\"50\" ></a>\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/whitphx?label=Sponsor%20me%20on%20GitHub%20Sponsors&style=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`](./app_global_slider.py): A slider widget (`st.slider`) whose value is shared among all sessions.\n* [`app_chat.py`](./app_chat.py): A simple chat app using `streamlit-server-state`.\n* [`app_chat_rooms.py`](./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",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "",
    "version": "0.17.1",
    "project_urls": {
        "Homepage": "https://github.com/whitphx/streamlit-server-state",
        "Repository": "https://github.com/whitphx/streamlit-server-state"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "adda699164acbc7cebdb4f36b241dd4efc0509629db3ff0bda0c45b22927ec5d",
                "md5": "c49040736d51367dd3e01936b76aa775",
                "sha256": "528bf795beaecb51d90156fe153326e22ffcd3bf955673e8871de1b6ac67a7ea"
            },
            "downloads": -1,
            "filename": "streamlit_server_state-0.17.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c49040736d51367dd3e01936b76aa775",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
            "size": 12310,
            "upload_time": "2023-08-21T03:36:02",
            "upload_time_iso_8601": "2023-08-21T03:36:02.831410Z",
            "url": "https://files.pythonhosted.org/packages/ad/da/699164acbc7cebdb4f36b241dd4efc0509629db3ff0bda0c45b22927ec5d/streamlit_server_state-0.17.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "835a8087e1ecb6be590d2c79c9fd66faf302c5031a82c61fc3d4a7164d939d3c",
                "md5": "8cf046be66a2aa118ee0c77a252dc3f4",
                "sha256": "b4b6d6c0801626f1bcf94a010cf8be67d31ceb51ad762b1735ea7a1f6a487cf7"
            },
            "downloads": -1,
            "filename": "streamlit_server_state-0.17.1.tar.gz",
            "has_sig": false,
            "md5_digest": "8cf046be66a2aa118ee0c77a252dc3f4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*",
            "size": 10605,
            "upload_time": "2023-08-21T03:36:05",
            "upload_time_iso_8601": "2023-08-21T03:36:05.573183Z",
            "url": "https://files.pythonhosted.org/packages/83/5a/8087e1ecb6be590d2c79c9fd66faf302c5031a82c61fc3d4a7164d939d3c/streamlit_server_state-0.17.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-08-21 03:36:05",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "whitphx",
    "github_project": "streamlit-server-state",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "streamlit-server-state"
}
Yuichiro Tachibana (Tsuchiya)
Elapsed time: 0.17837s