yotta-framework 1.0.1

A modern CLI framework based on Click, Rich and Textual.

yotta

Build complete CLIs and TUIs in Python, the fast way. (Django inspired)

yotta is designed to simplify the creation of Command Line Interfaces (CLI) and Terminal User Interfaces (TUI).

It combines the robustness of Click, the beauty of Rich, and the interactivity of Textual within a modular architecture inspired by Django.

Why yotta?

As lots of implementation in programming, building a CLI app is always following a universal pattern which yotta tries to simplify in order to program faster while maintaining security and efficience on the forescene.

Building a CLI app with yotta is making sure to get:

• Modular Architecture: Split your code into reusable "Apps" (startproject, startapp).
• UI-First Spirit: A native UX engine. Display tables, spinners, and alerts without manually importing Rich.
• Hybrid TUI Mode: Transform a command into a full interactive dashboard (mouse/keyboard) via native Textual integration.
• Smart Arguments: Automatic validation (Email, Files, Ranges) before your code even runs.

Installation

For now (local development):

git clone https://github.com/dim-gggl/yotta.git
cd yotta
uv sync
uv pip install -e .

Quick Start

1. Create a new project

yotta scaffolds the entire folder structure for you.

yotta startproject my_cli
cd my_cli
# A pyproject.toml and .env.example (with YOTTA_SETTINGS_MODULE) are created for you

2. Create an app (module)

uv run python manage.py startapp inventory

Note: Don't forget to add 'my_cli.inventory' (replace with your project name) to INSTALLED_APPS in your settings.py file.

3. Scaffold a command interactively (optional)

uv run python manage.py startcommand

Follow the prompts to pick the target app, command name, arguments, and options. yotta will append a ready-to-edit function to the selected app's commands.py. 4. Write your first command In src/inventory/commands.py:

from yotta.cli.decorators import command, argument
from yotta.core.context import YottaContext
from yotta.core.types import EMAIL

@command(name="add_user", help="Adds a user to the inventory")
@argument("email", type=EMAIL)
def add_user(yotta: YottaContext, email: str):
    # Using the native UI engine
    yotta.ui.header("New User")
    # Access project configuration without extra imports
    # (settings are loaded lazily on first attribute access)
    _ = yotta.settings
    
    with yotta.ui.spinner("Checking database..."):
        # Simulate work
        import time; time.sleep(1)
        
    yotta.ui.success(f"User [bold]{email}[/] added successfully!")
    
    # Automatic formatted table
    yotta.ui.table(
        columns=["ID", "Email", "Status"],
        rows=[["1", email, "Active"]],
        title="Summary"
    )

5. Run the command

uv run python manage.py add_user [e-mail]

Settings and environment

• YOTTA_SETTINGS_MODULE is loaded from .env or .env.local (the latter overrides).
• You can also set YOTTA_ENV=prod to auto-load settings_prod.py.
• YOTTA_DEBUG=1 will surface full tracebacks during settings import and loader errors.
• THEME controls the console palette. Supported values: "default", "dark" (unknown values fall back to "default").

To override the theme, set it in your project's settings.py:

# settings.py
THEME = "dark"

Debugging imports and discovery

• Loader warnings surface when an app has no commands.py; use --verbose for extra details or --quiet to silence.
• Use --strict to fail fast on missing/broken command modules (useful in CI).

TUI Mode (Textual Integration)

Need a real-time interactive dashboard? yotta integrates Textual natively.

Define a view in src/inventory/ui.py:

from yotta.ui.tui import yottaApp
from textual.widgets import Placeholder

class MonitorDashboard(yottaApp):
    def compose(self):
        yield Placeholder("Performance charts here")

Launch it from a standard command:

@command(name="monitor")
def launch_monitor(ctx: Context):
    app = MonitorDashboard(title="Super Monitor")
    app.run()

Key Features

The UI Context (yotta.ui)

yotta injects a ui wrapper into all your commands. No need to instantiate Console everywhere.

Method	Description
yotta.ui.header(title, subtitle)	Displays a stylized panel header.
yotta.ui.success(msg)	Displays a success message (green).
yotta.ui.error(msg)	Displays an error message (red).
yotta.ui.table(cols, rows)	Generates a formatted Rich table.
yotta.ui.spinner(msg)	Context manager for an animated loader.
yotta.ui.confirm(question)	Interactive Yes/No prompt.

RichUI - Unified Access to All Rich Components

Need direct access to Rich components? Use the rich singleton to instantiate any Rich component without manual imports.

from yotta.ui import rich

# Instead of: from rich.align import Align
align = rich.align("Centered text", align="center")

# Instead of: from rich.syntax import Syntax
syntax = rich.syntax(code, "python", theme="monokai")

# Instead of: from rich.table import Table
table = rich.table(title="My Data")

# Instead of: from rich.tree import Tree
tree = rich.tree("Root")

# Instead of: from rich.panel import Panel
panel = rich.panel("Content", title="Info")

Available components and utilities:

• Core: console, group
• Layout: align, columns, constrain, layout, padding
• Containers: panel
• Text & Styling: color, emoji, pretty, style, styled, syntax, text, theme, markdown
• Tables & Trees: table, tree
• Progress: progress, spinner, status, live (with bar_column, text_column, etc.)
• Prompts: prompt, confirm, int_prompt, float_prompt
• Rendering: rule, segment, traceback, json
• Utilities: pprint, pretty_repr, install_traceback, escape_markup, render_markup

Box styles: Access via rich.ROUNDED, rich.HEAVY, rich.DOUBLE, rich.MINIMAL

This singleton approach provides seamless access to all Rich functionality through a single import, keeping your code clean and consistent.

Smart Types (yotta.core.types)

Validate user input without writing a single if/else.

EMAIL: Validates email format (Regex).

File(extension='.json'): Checks for file existence AND specific extension.

Range(min=18, max=99): Enforces numeric range.

Choice([...]): Restrict values to a predefined list (case-insensitive by default).

Path() / Directory(): Validate existing filesystem paths (files or directories).

UUID(): Validate UUID strings.

URL(): Validate http/https URLs.

JSON(): Accept JSON strings or paths to JSON files, returns parsed objects.

Port(min,max): Validate port numbers in the allowed range.

EnumChoice(MyEnum): Use Python Enums as a source of allowed values.

Project Structure

my_cli/
├── manage.py            # Entry point (Django-like)
├── settings.py          # Global configuration
└── my_cli/              # Your applications folder (as a package)
    ├── main/
    │   ├── commands.py  # Your CLI commands
    │   └── ui.py        # Your visual components
    └── inventory/
        ├── commands.py
        └── ...