# Streamlit Parameters
## About
_Weave in interaction..._
This is one of streamlit's strengths, but it does create a challenge, namely
"How do I share my application view after I've interacted with it?".
Streamlit provides the machinery that make this possible - input widget configuration,
session state and access to the URL query string so that at the end of the day,
it merely requires copy-pasting an automagically modified URL string to share your view.
However, wiring these disparate parts together can be a non-trivial exercise.
This package endeavours to simplify that exercise for the app developer.
## Overview
The basic premise is to reduce your view to a few unique parameters that can
both be used to directly reproduce your current view in another user's
streamlit session.
* Parameters representative of your view typically come from input widgets
* Initial and current values need to be preserved in the session state to be always available
* Getting and setting the URL query string requires shims for type ⇔ string conversions
This package hides the complexity of interactions with both the session state and
url query string behind a convenient interface that focuses on what is important -
those unique parameters representative of the state of your view.
## Demo
[https://share.streamlit.io/stonier/streamlit_parameters/devel/demo.py](https://share.streamlit.io/stonier/streamlit_parameters/devel/demo.py)
## Usage
1. register a parameter
2. use the parameter default for the widget default
3. add a matching key to a widget
4. add an on_change hook to the widget.
5. set url fields
6. put on your peril-sensitive sunglasses and be froody!
```
parameters = streamlit_parameters.parameters.Parameters()
parameters.register_date_parameter(key="start_date", default_value=seven_days_ago) # <-- 1
streamlit.sidebar.date_input(
...,
value=parameters.start_date.default, # <-- 2
key="start_date", # <-- 3
on_change=functools.partial( # <-- 4
parameters.update_parameter_from_session_state,
key="start_date"
)
)
parameters.set_url_fields() # <-- 5 (sets all fields in one batch call)
streamlit.write("**Start Date**: {parameters.start_date.value}") # <-- 6
```
## Types
Supported parameter types include:
* `bool`
* `int`
* `float`
* `date`
* `string`
* `pair[int]`
* `pair[float]`
* `pair[date]`
* `list[string]`
* `list[bool]`
Pairs work well with slider widgets that specify ranges of values. Lists with, e.g. multiselects. See the demo
for a reference example.
## Modes
In general, there are two modes to support - partial or full embedding of parameters
in the URL query string.
* partial - only set url query string fields if the parameter has been modified
* full - set url query string fields for all parameters
Suppose you have an application with an *end_date* parameter which has a default that
is programmatically determined on the first time the app is loaded
(e.g. datetime.date.today()). Today that might return `11-02-2021`, tomorrow `11-03-2021`.
Now suppose you want to copy the url for someone today and they will receive
the email in the morning tomorrow. A question arises:
1. Do you want them to **experience** exactly what you experienced? In this case, you
never overrode that variable and you wish them to have that same experience,
i.e. you want them to see the latest view of that dashboard too -> you don't want to
have the *end_date* in the URL string.
2. Do you want them to **see** exactly what you saw? In this case, you need to capture
a snapshot of every single parameter -> all parameters must go to the URL string.
This class provides a toggle for the user to choose their mode of operation. It can
either be accessed directly via the streamlit session state
(`session_state._parameters_set_all`) or toggleable via a checkbox, e.g.:
```
parameters = streamlit_parameters.parameters.Parameters()
with streamlit.sidebar:
parameters.create_set_all_checkbox()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/splintered-reality/py_trees",
"name": "streamlit_parameters",
"maintainer": "Daniel Stonier",
"docs_url": null,
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"maintainer_email": "d.stonier@gmail.com",
"keywords": "streamlit",
"author": "Daniel Stonier",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4c/d1/d59a9438de74808ca148826e0cbdd49c51f0260225dcea8774c0be52e66b/streamlit_parameters-0.2.0.tar.gz",
"platform": null,
"description": "# Streamlit Parameters\n\n## About\n\n_Weave in interaction..._\n\nThis is one of streamlit's strengths, but it does create a challenge, namely\n\"How do I share my application view after I've interacted with it?\".\n\nStreamlit provides the machinery that make this possible - input widget configuration,\nsession state and access to the URL query string so that at the end of the day,\nit merely requires copy-pasting an automagically modified URL string to share your view. \nHowever, wiring these disparate parts together can be a non-trivial exercise.\n\nThis package endeavours to simplify that exercise for the app developer.\n\n![Demo](resources/demo.gif?raw=true \"Demo\")\n\n## Overview\n\nThe basic premise is to reduce your view to a few unique parameters that can\nboth be used to directly reproduce your current view in another user's\nstreamlit session. \n\n* Parameters representative of your view typically come from input widgets\n* Initial and current values need to be preserved in the session state to be always available\n* Getting and setting the URL query string requires shims for type ⇔ string conversions\n\nThis package hides the complexity of interactions with both the session state and\nurl query string behind a convenient interface that focuses on what is important -\nthose unique parameters representative of the state of your view.\n\n## Demo\n\n[https://share.streamlit.io/stonier/streamlit_parameters/devel/demo.py](https://share.streamlit.io/stonier/streamlit_parameters/devel/demo.py)\n\n## Usage\n\n1. register a parameter\n2. use the parameter default for the widget default\n3. add a matching key to a widget\n4. add an on_change hook to the widget.\n5. set url fields\n6. put on your peril-sensitive sunglasses and be froody!\n\n```\nparameters = streamlit_parameters.parameters.Parameters()\nparameters.register_date_parameter(key=\"start_date\", default_value=seven_days_ago) # <-- 1\nstreamlit.sidebar.date_input(\n ...,\n value=parameters.start_date.default, # <-- 2\n key=\"start_date\", # <-- 3\n on_change=functools.partial( # <-- 4\n parameters.update_parameter_from_session_state,\n key=\"start_date\"\n )\n)\nparameters.set_url_fields() # <-- 5 (sets all fields in one batch call)\n\nstreamlit.write(\"**Start Date**: {parameters.start_date.value}\") # <-- 6\n```\n\n## Types\n\nSupported parameter types include:\n\n* `bool`\n* `int`\n* `float`\n* `date`\n* `string`\n* `pair[int]`\n* `pair[float]`\n* `pair[date]`\n* `list[string]`\n* `list[bool]`\n\nPairs work well with slider widgets that specify ranges of values. Lists with, e.g. multiselects. See the demo\nfor a reference example.\n\n## Modes\n\nIn general, there are two modes to support - partial or full embedding of parameters\nin the URL query string.\n\n* partial - only set url query string fields if the parameter has been modified\n* full - set url query string fields for all parameters\n\nSuppose you have an application with an *end_date* parameter which has a default that\nis programmatically determined on the first time the app is loaded\n(e.g. datetime.date.today()). Today that might return `11-02-2021`, tomorrow `11-03-2021`.\n\nNow suppose you want to copy the url for someone today and they will receive\nthe email in the morning tomorrow. A question arises:\n\n1. Do you want them to **experience** exactly what you experienced? In this case, you\n never overrode that variable and you wish them to have that same experience,\n i.e. you want them to see the latest view of that dashboard too -> you don't want to\n have the *end_date* in the URL string.\n\n2. Do you want them to **see** exactly what you saw? In this case, you need to capture\n a snapshot of every single parameter -> all parameters must go to the URL string.\n\nThis class provides a toggle for the user to choose their mode of operation. It can\neither be accessed directly via the streamlit session state\n(`session_state._parameters_set_all`) or toggleable via a checkbox, e.g.:\n\n```\nparameters = streamlit_parameters.parameters.Parameters()\nwith streamlit.sidebar:\n parameters.create_set_all_checkbox()\n```\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Streamlit parameter management for page configuration",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://py-trees.readthedocs.io/en/devel/",
"Homepage": "https://github.com/splintered-reality/py_trees",
"Repository": "https://github.com/splintered-reality/py_trees"
},
"split_keywords": [
"streamlit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b1ae6634203e22b11ce6641eb7e50bda87ff8752ba586dd8ddbab5f240f6ffc",
"md5": "debffcc1b93aadc62fe35fac102dbc4a",
"sha256": "d86179e737782214ca8028491518cddf59925cd1f44306933744c324ff3dc24d"
},
"downloads": -1,
"filename": "streamlit_parameters-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "debffcc1b93aadc62fe35fac102dbc4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"size": 11442,
"upload_time": "2024-11-26T17:41:09",
"upload_time_iso_8601": "2024-11-26T17:41:09.619883Z",
"url": "https://files.pythonhosted.org/packages/1b/1a/e6634203e22b11ce6641eb7e50bda87ff8752ba586dd8ddbab5f240f6ffc/streamlit_parameters-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cd1d59a9438de74808ca148826e0cbdd49c51f0260225dcea8774c0be52e66b",
"md5": "6d4f14bfb83f7d0ca486f4b54d499875",
"sha256": "b9c84f2bf4fe354d60ddf5007d2b91bf40c067be3521119bc045851d3b403885"
},
"downloads": -1,
"filename": "streamlit_parameters-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "6d4f14bfb83f7d0ca486f4b54d499875",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,>=3.8",
"size": 10668,
"upload_time": "2024-11-26T17:41:11",
"upload_time_iso_8601": "2024-11-26T17:41:11.075003Z",
"url": "https://files.pythonhosted.org/packages/4c/d1/d59a9438de74808ca148826e0cbdd49c51f0260225dcea8774c0be52e66b/streamlit_parameters-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-26 17:41:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "splintered-reality",
"github_project": "py_trees",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "streamlit_parameters"
}
JSON
