clidevkit 0.1.0__tar.gz

clidevkit-0.1.0/PKG-INFO

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: clidevkit
+Version: 0.1.0
+Summary: A framework for building production-ready CLI apps and Terminal UIs with minimal code.
+Author-email: Vrushabh Sonawane <shivandmau25@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourname/clidev
+Project-URL: Repository, https://github.com/yourname/clidev
+Project-URL: Issues, https://github.com/yourname/clidev/issues
+Keywords: cli,tui,terminal,framework,forms,menus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.7.0
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: PyYAML>=6.0.1
+Requires-Dist: toml>=0.10.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# clidev
+
+**clidev** is a Python framework for building **production-ready Command Line
+Applications (CLI)** and **Terminal User Interfaces (TUI)** with minimal code.
+
+Unlike traditional CLI libraries that only parse arguments, `clidev` gives you
+a complete framework for interactive terminal apps — menus, forms, workflows,
+dashboards, state management, command execution, navigation, and
+event-driven logic — so you don't have to hand-write input loops, menu
+rendering, or terminal state machines.
+
+> Think of it as the Flutter/React of terminal applications: you describe
+> what your app looks like and does, `clidev` handles the rendering loop.
+
+Built on top of [`rich`](https://github.com/Textualize/rich) for terminal
+rendering and [`questionary`](https://github.com/tmbo/questionary) for
+interactive prompts.
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+(This installs `clidev` from this repo in editable mode, along with its
+dependencies: `rich`, `questionary`, `pydantic`, `click`, `PyYAML`, `toml`.)
+
+## Quick start
+
+```python
+from clidev import App
+
+app = App("My App")
+
+home = app.menu("Home")
+home.option("Say Hello", lambda: app.success("Hello!"))
+home.option("Exit", app.exit)
+
+app.run()
+```
+
+Or scaffold a brand-new project with the bundled CLI:
+
+```bash
+clidev new myproject
+cd myproject
+python app.py
+```
+
+---
+
+## Module guide
+
+### `App` (`clidev/app.py`)
+
+The core object. Wires together state, storage, routing, events, plugins,
+theming, and every UI widget factory.
+
+```python
+from clidev import App
+
+app = App("Developer Toolkit", theme="dark", storage_backend="json")
+```
+
+### State (`clidev/state.py`)
+
+Global, dict-like state, accessible anywhere in your app.
+
+```python
+app.state["username"] = "Vrushabh"
+print(app.state["username"])
+
+app.state.on_change(lambda key, old, new: print(f"{key}: {old} -> {new}"))
+```
+
+### Storage (`clidev/storage.py`)
+
+Every form (or any code) can persist data through a pluggable backend:
+`memory`, `json`, `sqlite`, `yaml`, or `toml`.
+
+```python
+app.storage.save("user", {"name": "Bob"})
+user = app.storage.load("user")
+```
+
+```python
+app = App("My App", storage_backend="sqlite")
+```
+
+### Forms (`clidev/forms.py`, `inputs.py`, `validators.py`)
+
+Chainable form builder with automatic validation.
+
+```python
+form = app.form("User")
+form.text("Name")
+form.email("Email")
+form.password("Password")
+form.number("Age")
+
+data = form.run()
+# {"Name": "Vrushabh", "Email": "abc@gmail.com", "Password": "******", "Age": 17}
+```
+
+Supported field types: `text`, `email`, `password`, `number`, `url`, `file`,
+`folder`, `date`, `time`, `checkbox`, `toggle`, `radio`, `select`/`dropdown`,
+`multiselect`, `searchable`.
+
+Custom validators can be attached per-field via `extra_validators=[...]`
+using anything from `clidev.validators` (`min_length`, `max_length`,
+`min_value`, `max_value`, `is_date`, etc.).
+
+### Menus (`clidev/menus.py`)
+
+```python
+menu = app.menu("Main Menu")
+menu.option("Create Project", create_project)
+menu.option("Deploy", deploy)
+menu.option("Exit", app.exit)
+```
+
+Nested menus:
+
+```python
+main = app.menu("Main")
+settings = app.menu("Settings")
+main.link("Settings", settings)
+```
+
+### Page routing (`clidev/router.py`, `pages.py`)
+
+```python
+@app.page("home")
+def home():
+    ...
+
+app.goto("settings")
+app.back()
+```
+
+### Conditional navigation (`clidev/actions.py`)
+
+```python
+@app.when(lambda data: data["Role"] == "Admin")
+def admin():
+    app.goto("admin_menu")
+```
+
+or:
+
+```python
+app.if_value("Role", equals="Admin").goto("admin_menu")
+app.if_value("Age", greater_than=18).goto("adult_menu")
+```
+
+Supported comparisons: `equals`, `not_equals`, `greater_than`, `less_than`,
+`greater_equal`, `less_equal`, `contains`, `in_list`.
+
+### Workflow engine (`clidev/workflow.py`)
+
+```python
+workflow = app.workflow()
+workflow.step(login)
+workflow.step(select_project)
+workflow.step(build)
+workflow.step(deploy)
+result = workflow.start()
+```
+
+Each step can accept a shared `context` dict; whatever a step returns (as a
+dict) is merged into that context for subsequent steps.
+
+### Events (`clidev/events.py`)
+
+```python
+@app.on_start
+def startup():
+    ...
+
+@app.on_exit
+def shutdown():
+    ...
+
+@app.on_submit(some_form)
+def save(data):
+    ...
+
+@app.on_error
+def on_error(e):
+    ...
+```
+
+### Command execution (`clidev/shell.py`)
+
+```python
+app.cmd("git init")
+
+result = app.cmd("git status", capture=True)
+print(result.stdout, result.ok)
+
+app.cmd("pip install -r requirements.txt", background=True)
+```
+
+### Progress & tasks (`clidev/progress.py`, `spinner.py`, `tasks.py`, `scheduler.py`)
+
+```python
+with app.progress("Installing"):
+    app.cmd("pip install numpy")
+    app.cmd("pip install pandas")
+
+@app.task
+def build():
+    ...
+
+app.run_task("build")
+```
+
+### Plugins (`clidev/plugins.py`)
+
+```python
+from clidev.plugins import Plugin
+
+class GitPlugin(Plugin):
+    name = "git"
+
+    def on_install(self, app):
+        ...
+
+    def on_start(self, app):
+        ...
+
+app.use(GitPlugin())
+```
+
+### Themes (`clidev/themes.py`, `colors.py`)
+
+```python
+app = App("My App", theme="dark")
+
+theme = Theme()
+theme.primary("blue")
+theme.success("green")
+```
+
+### Logging (`clidev/logger.py`)
+
+```python
+app.logger.info("Started")
+app.logger.warning("Warning")
+app.logger.error("Failed")
+```
+
+### UI widgets
+
+- `app.table(title, columns=[...])` — data tables (`clidev/table.py`)
+- `app.tree(label)` — tree views (`clidev/tree.py`)
+- `app.card(title, content)` — bordered content cards (`clidev/cards.py`)
+- `app.dashboard(title)` — multi-panel grid overview (`clidev/dashboard.py`)
+- `app.dialog.confirm(...)`, `app.dialog.prompt(...)`, `app.dialog.alert(...)`
+  (`clidev/dialogs.py`)
+- `app.notify.success/error/warning/info(...)` (`clidev/notifications.py`)
+- `app.statusbar.set(...).render()` (`clidev/statusbar.py`)
+
+### Project generator (`clidev/generators/`, `cli.py`)
+
+```bash
+clidev new myproject
+```
+
+Creates:
+
+```text
+myproject/
+│
+├── app.py
+├── routes.py
+├── menus.py
+├── forms.py
+├── workflows.py
+├── commands.py
+├── storage.py
+├── settings.py
+└── assets/
+```
+
+---
+
+## Full example
+
+See [`examples/basic_app.py`](examples/basic_app.py) for the complete
+"Developer Toolkit" example (menus, page routing, forms, storage, conditional
+navigation, and shell commands), and
+[`examples/workflow_app.py`](examples/workflow_app.py) for a workflow +
+plugin + dashboard example.
+
+```python
+from clidev import App
+
+app = App("Developer Toolkit")
+
+home = app.menu("Home")
+home.option("Create Project", "project_form")
+home.option("Settings", "settings")
+home.option("Exit", app.exit)
+
+
+@app.page("project_form")
+def project_form_page():
+    project = app.form("Project")
+    project.text("Project Name")
+    project.select("Language", ["Python", "Rust", "Go"])
+    data = project.run()
+
+    if not data:
+        return
+
+    app.storage.save("project", data)
+    app._last_form_data = data
+
+    if data["Language"] == "Python":
+        app.goto("python_setup")
+    else:
+        app.success(f"Project '{data['Project Name']}' created ({data['Language']}).")
+
+
+@app.page("python_setup")
+def python_setup():
+    with app.progress("Setting up Python project"):
+        app.cmd("python -m venv .venv_demo")
+        app.cmd("git init")
+    app.success("Project Created")
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+---
+
+## Running the tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+The test suite (in `tests/`) covers global state, all storage backends, form
+field validation, the shell command wrapper, routing/history, the workflow
+engine, conditional navigation, the event dispatcher, theming, the project
+generator, and full `App` integration — 85 tests in total.
+
+---
+
+## Project layout
+
+```text
+clidev/
+├── __init__.py
+├── app.py                 # Main application
+├── router.py               # Navigation
+├── pages.py                # Pages
+├── menus.py                 # Menu engine
+├── forms.py                  # Forms
+├── inputs.py                  # Input widgets
+├── validators.py
+│
+├── state.py                   # Global state
+├── storage.py                  # JSON/SQLite/YAML/TOML storage
+├── workflow.py                  # Workflow engine
+├── events.py                     # Event dispatcher
+├── actions.py                     # Conditional navigation
+│
+├── shell.py                        # Execute commands
+├── tasks.py                          # Background tasks
+├── scheduler.py
+│
+├── progress.py
+├── spinner.py
+├── dashboard.py
+├── table.py
+├── tree.py
+├── cards.py
+├── dialogs.py
+├── notifications.py
+├── statusbar.py
+│
+├── themes.py
+├── colors.py
+├── icons.py
+│
+├── logger.py
+├── config.py
+├── plugins.py
+├── utils.py
+├── exceptions.py
+│
+├── generators/
+│   ├── project.py
+│   ├── menu.py
+│   ├── form.py
+│   └── workflow.py
+│
+├── templates/
+├── builtins/                        # Example plugins (GitPlugin, DatabasePlugin)
+└── cli.py                            # "clidev" terminal command
+```
+
+## Roadmap
+
+- Additional storage backends: PostgreSQL, MongoDB, Redis
+- `clidev-auth`, `clidev-cloud`, `clidev-testing`, `clidev-plugins` as
+  separate installable packages
+- Richer dashboard layout options and live-updating widgets
+
+## License
+
+MIT