stui-terminal 0.1.0rc2__tar.gz

stui_terminal-0.1.0rc2/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest

stui_terminal-0.1.0rc2/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish_to_testpypi:
+        description: "Publish to TestPyPI after the testpypi environment is configured"
+        required: true
+        type: boolean
+        default: false
+      publish_to_pypi:
+        description: "Publish to real PyPI after the pypi environment is configured"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' &&
+        inputs.publish_to_testpypi &&
+        startsWith(github.ref, 'refs/tags/v')
+      }}
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+          skip-existing: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' &&
+        inputs.publish_to_pypi &&
+        startsWith(github.ref, 'refs/tags/v')
+      }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

stui_terminal-0.1.0rc2/AGENTS.md

@@ -0,0 +1,11 @@
+# stui Agent Notes
+
+- Always run `python3.11 -m pytest` after code changes.
+- Keep the public API small and Streamlit-inspired, not Streamlit-compatible.
+- Do not add browser, server, websocket, or port-forwarding code.
+- Do not depend on Streamlit at runtime.
+- Do not copy GPL slider code or depend on packages such as `textual-slider`.
+- Prefer Textual first-party widgets where they exist.
+- Keep the MVP implementation readable and direct before adding abstractions.
+- Keep public docs honest: `stui` is not official Streamlit, not affiliated with Streamlit, and not a Streamlit compatibility layer.
+- When working alongside other agents, do not revert edits you did not make.

stui_terminal-0.1.0rc2/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project is currently pre-1.0, so APIs may change while the MVP is being
+shaped.
+
+## 0.1.0rc2 - 2026-05-09
+
+### Changed
+
+- Updated install documentation for the future PyPI distribution name,
+  `stui-terminal`.
+- Clarified that the distribution name is `stui-terminal`, while the import
+  package and CLI remain `stui`.
+- Preserved editable local development install instructions for contributors.
+
+## 0.1.0rc1 - 2026-05-08
+
+### Added
+
+- Initial terminal-native `stui` MVP with top-to-bottom script reruns.
+- Public APIs for text output, alerts, button, slider, text input, checkbox,
+  and session state.
+- Textual terminal renderer with keyboard-first widget interactions.
+- CLI entrypoints for `stui run ...` and `python -m stui run ...`.
+- Example apps for the basic demo, counter, and model-parameter playground.
+- Test suite, static policy checks, CI workflow, contributor guide, and release
+  candidate documentation.

stui_terminal-0.1.0rc2/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Thanks for helping with `stui`. The project is still an MVP, so the best
+contributions keep the surface area small, readable, and easy to test.
+
+## Local Setup
+
+Use Python 3.11 or newer:
+
+```bash
+python3.11 -m pip install -e ".[dev]"
+python3.11 -m pytest
+```
+
+## Development Guidelines
+
+- Keep the public API small and Streamlit-inspired, not Streamlit-compatible.
+- Do not add browser, server, websocket, or port-forwarding code.
+- Do not depend on Streamlit at runtime.
+- Prefer Textual first-party widgets where they exist.
+- Do not copy GPL slider code or depend on packages such as `textual-slider`.
+- Keep MVP code direct before adding abstractions.
+- Keep examples local and deterministic; avoid network calls unless the project
+  explicitly grows that capability later.
+
+## Tests
+
+Run the full test suite after code changes:
+
+```bash
+python3.11 -m pytest
+```
+
+Documentation-only edits should still be checked for accuracy against the
+current API and examples.
+
+## Public Claims
+
+Please keep README and release notes honest:
+
+- Say `stui` is inspired by Streamlit, not compatible with it.
+- Say `stui` is not official Streamlit and is not affiliated with Streamlit.
+- Avoid implying production hardening, broad widget coverage, browser support,
+  or long-term API stability before those things exist.

stui_terminal-0.1.0rc2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MarMar Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stui_terminal-0.1.0rc2/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include RELEASE_NOTES_v0.1.0rc1.md
+include RELEASE_NOTES_v0.1.0rc2.md
+include CONTRIBUTING.md
+include AGENTS.md
+include pyproject.toml
+recursive-include assets *.svg
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include .github/workflows *.yml

stui_terminal-0.1.0rc2/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: stui-terminal
+Version: 0.1.0rc2
+Summary: A tiny Streamlit-inspired terminal UI experiment.
+Author: MarMar Labs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/marmar9615-cloud/stui-terminal
+Project-URL: Repository, https://github.com/marmar9615-cloud/stui-terminal
+Project-URL: Issues, https://github.com/marmar9615-cloud/stui-terminal/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.89
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# stui
+
+[![CI](https://github.com/marmar9615-cloud/stui-terminal/actions/workflows/ci.yml/badge.svg)](https://github.com/marmar9615-cloud/stui-terminal/actions/workflows/ci.yml)
+
+`stui` is a tiny Streamlit-inspired framework for building terminal-native
+Python apps. Write a short script, run it in your terminal, and get a Textual UI
+with stateful controls.
+
+It is built for local tools, demos, data scripts, model debug panels, SSH
+sessions, and headless environments where opening a browser, binding a port, or
+running a dashboard server is unnecessary ceremony. The public API is
+deliberately small and readable.
+
+`stui` is not official Streamlit, is not affiliated with Streamlit, and is not a
+Streamlit compatibility layer. The API intentionally feels familiar, but this
+project keeps its own smaller surface area.
+
+## Preview
+
+![stui model demo terminal screenshot](assets/model_demo.svg)
+
+```text
+┌─ stui ───────────────────────────────────────────┐
+│ stui demo                                        │
+│                                                  │
+│ x                                                │
+│ [██░░░░░░░░░░░░] 10                              │
+│                                                  │
+│ [ Increment ]                                    │
+│                                                  │
+│ x = 10                                           │
+│ count = 0                                        │
+│                                                  │
+│ q Quit   r Rerun   tab Focus next                │
+└──────────────────────────────────────────────────┘
+```
+
+## Install
+
+Use Python 3.11 or newer.
+
+Install the PyPI distribution named `stui-terminal`:
+
+```bash
+python3.11 -m pip install stui-terminal
+```
+
+The PyPI distribution name is `stui-terminal`, but the import package and CLI
+are both `stui`:
+
+```python
+import stui as st
+```
+
+For local development from a checkout, use an editable install with the dev
+extra:
+
+```bash
+python3.11 -m venv .venv
+. .venv/bin/activate
+python3.11 -m pip install -e ".[dev]"
+```
+
+For runtime-only local use, install without the dev extra:
+
+```bash
+python3.11 -m pip install -e .
+```
+
+## Quickstart
+
+Install from PyPI, then run your app:
+
+```bash
+python3.11 -m pip install stui-terminal
+stui run app.py
+```
+
+Or set up the project from source and run the basic example:
+
+```bash
+git clone https://github.com/marmar9615-cloud/stui-terminal.git
+cd stui-terminal
+python3.11 -m venv .venv
+. .venv/bin/activate
+python3.11 -m pip install -e ".[dev]"
+stui run examples/basic.py
+```
+
+You can also run through the module entry point:
+
+```bash
+python3.11 -m stui run examples/counter.py
+```
+
+Scripts use the public `stui` API:
+
+```python
+import stui as st
+
+st.title("stui demo")
+
+if "count" not in st.session_state:
+    st.session_state.count = 0
+
+value = st.slider("value", 0, 100, 25)
+
+if st.button("Increment"):
+    st.session_state.count += 1
+
+st.write("value =", value)
+st.write("count =", st.session_state.count)
+```
+
+More examples:
+
+```bash
+stui run examples/counter.py
+stui run examples/model_demo.py
+```
+
+## Why terminal-native?
+
+Some useful Python apps do not need a browser runtime. `stui` keeps the
+interface inside the terminal so it can fit naturally into:
+
+- SSH sessions, remote machines, and headless boxes.
+- Internal tools where opening ports or managing local server URLs is friction.
+- Offline or locked-down environments where browser access is limited.
+- Model, data, and DevOps workflows that already start from a shell.
+
+That also keeps the boundary simple: `stui` does not start a web server, use
+websockets, require port-forwarding, or depend on Streamlit at runtime.
+
+## Commands
+
+```bash
+# Install the project for local development.
+python3.11 -m venv .venv
+. .venv/bin/activate
+python3.11 -m pip install -e ".[dev]"
+
+# Run the smoke-size example app.
+stui run examples/basic.py
+
+# Run the stateful counter example.
+stui run examples/counter.py
+
+# Run the deterministic model-parameter demo.
+stui run examples/model_demo.py
+
+# Run the test suite.
+python3.11 -m pytest
+```
+
+## Keyboard Shortcuts
+
+- `q`: quit the app
+- `r`: rerun the script
+- `tab`: focus the next widget
+- `enter`: press the focused button
+- `left` or `h`: decrease the focused slider
+- `right` or `l`: increase the focused slider
+- `home`: set the focused slider to its minimum value
+- `end`: set the focused slider to its maximum value
+
+## Current API
+
+The current public API is intentionally small:
+
+- `st.title(body, *, key=None)`: render a title.
+- `st.header(body, *, key=None)`: render a section header.
+- `st.text(body)`: render plain text.
+- `st.markdown(body)`: render Markdown-flavored text.
+- `st.divider()`: render a horizontal divider.
+- `st.info(body)`, `st.success(body)`, `st.warning(body)`, `st.error(body)`: render status messages.
+- `st.write(*args)`: render simple text output.
+- `st.button(label, key=None, help=None, disabled=False, on_click=None, args=None, kwargs=None)`: render a button and return `True` for the run where it was pressed.
+- `st.slider(label, min_value=0, max_value=100, value=None, step=1, *, key=None, help=None, disabled=False, on_change=None, args=None, kwargs=None)`: render a numeric slider and return its current value.
+- `st.text_input(label, value="", *, key=None, placeholder=None, disabled=False, on_change=None, args=None, kwargs=None)`: render a single-line text input and return its current value.
+- `st.checkbox(label, value=False, *, key=None, disabled=False, on_change=None, args=None, kwargs=None)`: render a checkbox and return its current value.
+- `st.session_state`: persist values across reruns with dict-style or attribute-style access.
+- `st.rerun()`: request a script rerun.
+
+Import the API as:
+
+```python
+import stui as st
+```
+
+## Examples
+
+### Counter
+
+`examples/counter.py` shows a minimal stateful app with increment, decrement, and
+reset controls.
+
+```bash
+stui run examples/counter.py
+```
+
+### Model Demo
+
+`examples/model_demo.py` shows a small model-parameter playground using text
+input, checkbox, sliders, status messages, session state, and deterministic
+scoring. It is intentionally local and fake: there are no network calls or model
+dependencies.
+
+```bash
+stui run examples/model_demo.py
+```
+
+## Limitations
+
+- No browser, web server, websocket, or port-forwarding runtime.
+- No Streamlit dependency and no promise of Streamlit compatibility.
+- No charts, tables, dataframes, forms, columns, sidebars, or file upload yet.
+- Slider input supports numeric values only.
+- Layout is currently linear and script-driven.
+- The app reruns the script as interactions change state, so examples should keep top-level work lightweight.
+- Error handling is still early and meant for development feedback.
+- The package is an MVP and has not stabilized a long-term compatibility policy.
+
+## Roadmap
+
+- Add small text output helpers such as `caption`.
+- Add common controls such as `selectbox`, `radio`, and number inputs.
+- Add simple display primitives for tables and progress.
+- Improve focus behavior, accessibility hints, and keyboard discoverability.
+- Expand example coverage for data scripts, model controls, DevOps panels, and internal tools.
+- Keep the implementation clean-room, readable, and based on Textual first-party widgets where possible.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the local development workflow and
+project boundaries.