# Streamlit Configurator
A **declarative** and **modular** approach to building Streamlit applications. **Streamlit Configurator** allows you to define UI components and layouts in a structured, reusable manner—eliminating repetitive Streamlit calls, improving maintainability, and enabling robust state management.
## Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Example Pages](#example-pages)
- [License](#license)
- [Contact & Contributing](#contact--contributing)
## Features
- **Declarative Layouts**: Use `ComponentConfig` and `PageConfig` to define pages in a more **descriptive** style—no need to manually chain together multiple Streamlit calls.
- **Robust State Management**: Utilize **placeholders** (`PlaceholderValue`) to seamlessly store and retrieve data across page refreshes or navigations.
- **Reusable Configurations**: Once you define a component or layout, you can reuse it across different pages, ensuring consistency and reducing code duplication.
- **Integration & Compatibility**: Works **alongside** native Streamlit calls. You can still write custom functions or direct Streamlit code where it makes sense.
- **Scalable Architecture**: As your app grows, define new placeholders or restructure layouts without rewriting large sections of code.
## Installation
### From PyPI (Upcoming / Planned)
Streamlit Configurator is available on PyPI. You can install it with:
```bash
pip install st-configurator
```
### From Source (Current)
1. Clone or download this repository.
2. Navigate to the project's root directory.
3. Install using pip:
```bash
pip install .
```
4. Make sure Streamlit is installed:
```bash
pip install streamlit
```
## Quick Start
Below is a minimal example showing how to set up a page with **Streamlit Configurator**.
```python
import streamlit as st
from st_configurator import ComponentConfig, PageConfig, PageRenderer
from st_configurator.placeholder import Placeholder, PlaceholderValue
# 1. Define a custom placeholder class to hold your state
class MyPlaceholder(Placeholder):
NAME = PlaceholderValue(default="Guest")
# 2. Create a Streamlit component config (e.g., a text input)
name_input_config = ComponentConfig(
component=st.text_input,
args=("What's your name?",),
kwargs={"value": MyPlaceholder.NAME},
result_key=MyPlaceholder.NAME
)
# 3. Define a page config that includes this component
page_config = PageConfig(
page_tag="HomePage",
body=[name_input_config]
)
# 4. Render the page
PageRenderer().render_page(page_config)
```
1. Run your script with:
```bash
streamlit run your_script.py
```
2. Interact with the text input, navigate to other pages (if any), and come back. Notice the placeholder value persists.
## Basic Usage
1. **Define Placeholders:** Inherit from **`Placeholder`** and declare **`PlaceholderValues`** for any data you need to persist.
2. **Create Components:** Use **`ComponentConfig`** to wrap any Streamlit callable (e.g., **`st.button`**, **`st.text_input`**). Pass placeholders or default values as **`args`** or **`kwargs`**, and capture outputs by assigning **`result_key`**.
3. **Assemble Pages:** Group components in a PageConfig. You can place some components in body and others in sidebar.
4. **Render:** Call **`PageRenderer().render_page(my_page_config)`** to display your page.
## Advanced Usage
- **Conditional Rendering:** Add a **`condition`** to any **`ComponentConfig`** to selectively display or hide it based on a placeholder's boolean value (or the returned value of another component).
- **Nested Layouts:** Use **`children`** in a **`ComponentConfig`** for layout containers like **`st.columns`** or **`st.tabs`**.
- **Persistence:** If you need a placeholder to remain **locked** once it changes, set **`persist=True`**. The new value overrides the default permanently, ignoring subsequent resets.
- **Global Scope:** Set **`global_scope=True`** for placeholders that are shared across **all** pages.
## Example Pages
A more detailed set of usage examples and component demonstrations can be found in the **[example/](example)** directory. To see them in action, run:
```bash
streamlit run example/main.py
```
You'll find multiple pages illustrating:
- **Placeholder** usage
- **Declarative** layout building
- **Conditional** rendering
- **Nested** containers and more
Each page includes commentary and code samples demonstrating how to use **Streamlit Configurator's API**.
## License
This project is licensed under the terms of the [LICENSE](LICENSE) file.
## Contact & Contributing
- Email: x77497856@gmail.com
- GitHub: https://github.com/FrunkyLiu/Streamlit-Configurator
Contributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request. If you find this project useful, please consider giving a star ⭐ on GitHub to support its continued development.
Raw data
{
"_id": null,
"home_page": "https://github.com/FrunkyLiu/Streamlit-Configurator",
"name": "st-configurator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "streamlit configuration declarative placeholders UI",
"author": "Frunky Liu",
"author_email": "x77497856@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/21/d1d815b057e6f6fe8635bd8f0e311316b88883167e326704c99a3f42f239/st_configurator-0.1.0b1.tar.gz",
"platform": null,
"description": "# Streamlit Configurator\n\nA **declarative** and **modular** approach to building Streamlit applications. **Streamlit Configurator** allows you to define UI components and layouts in a structured, reusable manner\u2014eliminating repetitive Streamlit calls, improving maintainability, and enabling robust state management.\n\n## Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Basic Usage](#basic-usage)\n- [Advanced Usage](#advanced-usage)\n- [Example Pages](#example-pages)\n- [License](#license)\n- [Contact & Contributing](#contact--contributing)\n\n\n## Features\n- **Declarative Layouts**: Use `ComponentConfig` and `PageConfig` to define pages in a more **descriptive** style\u2014no need to manually chain together multiple Streamlit calls.\n- **Robust State Management**: Utilize **placeholders** (`PlaceholderValue`) to seamlessly store and retrieve data across page refreshes or navigations.\n- **Reusable Configurations**: Once you define a component or layout, you can reuse it across different pages, ensuring consistency and reducing code duplication.\n- **Integration & Compatibility**: Works **alongside** native Streamlit calls. You can still write custom functions or direct Streamlit code where it makes sense.\n- **Scalable Architecture**: As your app grows, define new placeholders or restructure layouts without rewriting large sections of code.\n\n\n## Installation\n\n### From PyPI (Upcoming / Planned)\nStreamlit Configurator is available on PyPI. You can install it with:\n```bash\npip install st-configurator\n```\n\n### From Source (Current)\n1. Clone or download this repository.\n2. Navigate to the project's root directory.\n3. Install using pip:\n ```bash\n pip install .\n ```\n4. Make sure Streamlit is installed:\n ```bash\n pip install streamlit\n ```\n\n## Quick Start\nBelow is a minimal example showing how to set up a page with **Streamlit Configurator**.\n \n```python\nimport streamlit as st\nfrom st_configurator import ComponentConfig, PageConfig, PageRenderer\nfrom st_configurator.placeholder import Placeholder, PlaceholderValue\n\n# 1. Define a custom placeholder class to hold your state\nclass MyPlaceholder(Placeholder):\n NAME = PlaceholderValue(default=\"Guest\")\n\n# 2. Create a Streamlit component config (e.g., a text input)\nname_input_config = ComponentConfig(\n component=st.text_input,\n args=(\"What's your name?\",),\n kwargs={\"value\": MyPlaceholder.NAME},\n result_key=MyPlaceholder.NAME\n)\n\n# 3. Define a page config that includes this component\npage_config = PageConfig(\n page_tag=\"HomePage\",\n body=[name_input_config]\n)\n\n# 4. Render the page\nPageRenderer().render_page(page_config)\n```\n\n1. Run your script with:\n ```bash\n streamlit run your_script.py\n ```\n2. Interact with the text input, navigate to other pages (if any), and come back. Notice the placeholder value persists.\n\n## Basic Usage\n\n1. **Define Placeholders:** Inherit from **`Placeholder`** and declare **`PlaceholderValues`** for any data you need to persist.\n2. **Create Components:** Use **`ComponentConfig`** to wrap any Streamlit callable (e.g., **`st.button`**, **`st.text_input`**). Pass placeholders or default values as **`args`** or **`kwargs`**, and capture outputs by assigning **`result_key`**.\n3. **Assemble Pages:** Group components in a PageConfig. You can place some components in body and others in sidebar.\n4. **Render:** Call **`PageRenderer().render_page(my_page_config)`** to display your page.\n\n## Advanced Usage\n- **Conditional Rendering:** Add a **`condition`** to any **`ComponentConfig`** to selectively display or hide it based on a placeholder's boolean value (or the returned value of another component).\n- **Nested Layouts:** Use **`children`** in a **`ComponentConfig`** for layout containers like **`st.columns`** or **`st.tabs`**.\n- **Persistence:** If you need a placeholder to remain **locked** once it changes, set **`persist=True`**. The new value overrides the default permanently, ignoring subsequent resets.\n- **Global Scope:** Set **`global_scope=True`** for placeholders that are shared across **all** pages.\n\n## Example Pages\nA more detailed set of usage examples and component demonstrations can be found in the **[example/](example)** directory. To see them in action, run:\n```bash\nstreamlit run example/main.py\n```\nYou'll find multiple pages illustrating:\n\n- **Placeholder** usage\n- **Declarative** layout building\n- **Conditional** rendering\n- **Nested** containers and more\n\nEach page includes commentary and code samples demonstrating how to use **Streamlit Configurator's API**.\n\n## License\nThis project is licensed under the terms of the [LICENSE](LICENSE) file.\n\n## Contact & Contributing\n- Email: x77497856@gmail.com\n- GitHub: https://github.com/FrunkyLiu/Streamlit-Configurator\n\nContributions, bug reports, and feature requests are welcome! Feel free to open an issue or submit a pull request. If you find this project useful, please consider giving a star \u2b50 on GitHub to support its continued development.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A declarative and modular approach to building Streamlit apps",
"version": "0.1.0b1",
"project_urls": {
"Homepage": "https://github.com/FrunkyLiu/Streamlit-Configurator"
},
"split_keywords": [
"streamlit",
"configuration",
"declarative",
"placeholders",
"ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ff92a702303eb087a37b3d36f9ed3132dcd6d45fd67f364e19d1ce57aabdf6ff",
"md5": "45d3b1c44b09a677f88856f532ee34ed",
"sha256": "2f84efddd66a0ec0be33e4a159b4e1fd90c113f62de7f008e7dcf70d058a7587"
},
"downloads": -1,
"filename": "st_configurator-0.1.0b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45d3b1c44b09a677f88856f532ee34ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9113,
"upload_time": "2025-02-13T15:31:50",
"upload_time_iso_8601": "2025-02-13T15:31:50.340129Z",
"url": "https://files.pythonhosted.org/packages/ff/92/a702303eb087a37b3d36f9ed3132dcd6d45fd67f364e19d1ce57aabdf6ff/st_configurator-0.1.0b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f21d1d815b057e6f6fe8635bd8f0e311316b88883167e326704c99a3f42f239",
"md5": "aca65666c3974c7fced60fe2ffdff44e",
"sha256": "4eadb3a6eb19d8014ac11e6e075b668fabab5b38b05a442e23c59d6eeff0ddfb"
},
"downloads": -1,
"filename": "st_configurator-0.1.0b1.tar.gz",
"has_sig": false,
"md5_digest": "aca65666c3974c7fced60fe2ffdff44e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10006,
"upload_time": "2025-02-13T15:31:51",
"upload_time_iso_8601": "2025-02-13T15:31:51.831649Z",
"url": "https://files.pythonhosted.org/packages/0f/21/d1d815b057e6f6fe8635bd8f0e311316b88883167e326704c99a3f42f239/st_configurator-0.1.0b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-13 15:31:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FrunkyLiu",
"github_project": "Streamlit-Configurator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "streamlit",
"specs": [
[
">=",
"1.4"
]
]
}
],
"lcname": "st-configurator"
}
JSON
