ChukTerm
A modern terminal library with a powerful CLI interface for building beautiful terminal applications in Python.
🆕 What's New in v0.2
- 📈 Progress Indicators: New
progress_bar(),track(), andspinner()methods for better user feedback - 🎨 Theme Preview CLI:
chuk-term themes --side-by-sideto compare all 8 themes - 📚 Examples Browser:
chuk-term examplesto discover and run examples - 🧪 Improved Testing: 93% code coverage with 616 passing tests
- 📖 Better Documentation: New CONTRIBUTING.md and updated guides
- 🔧 Quality Automation: Pre-commit hooks with latest tools (ruff, black, mypy)
See CHANGELOG.md for complete release history.
✨ Features
- 🎨 Rich UI Components: Banners, prompts, formatters, and code display with syntax highlighting
- 🎯 Centralized Output Management: Consistent console output with multiple log levels
- 🎭 Theme Support: 8 built-in themes including default, dark, light, minimal, terminal, monokai, dracula, and solarized
- 📝 Code Display: Syntax highlighting, diffs, code reviews, and side-by-side comparisons
- 🔧 Terminal Management: Screen control, cursor management, hyperlinks, and color detection
- 💬 Interactive Prompts: Text input, confirmations, number input, single/multi selection menus
- 📊 Data Formatting: Tables, trees, JSON, timestamps, and structured output
- 📈 Progress Indicators: Progress bars, spinners, and task tracking with
track()andprogress_bar() - 🌊 Streaming Support: Live-updating messages for real-time content streaming (LLM-style)
- 🤖 AI-Friendly: Designed for AI agents with comprehensive docs and consistent APIs
- 🔄 Environment Adaptation: Automatically adapts to TTY, CI, and NO_COLOR environments
📦 Installation
Using uv (Recommended)
# Install as dependency
uv add chuk-term
# Install globally as tool
uv tool install chuk-term
Using pip
# Install from PyPI
pip install chuk-term
# With development dependencies
pip install chuk-term[dev]
From Source (Development)
# Clone the repository
git clone https://github.com/chrishayuk/chuk-term.git
cd chuk-term
# Install with uv (recommended)
uv sync --dev
# Or with pip
pip install -e ".[dev]"
# Verify installation
chuk-term --version
For detailed installation instructions, see the Getting Started Guide.
🚀 Quick Start
For AI Agents and LLMs
ChukTerm is designed to be AI-friendly. For comprehensive guidance:
- 📖 Read the Getting Started Guide
- 🤖 Check llms.txt for LLM-optimized documentation
- 📚 Browse examples for working code
Basic Output
from chuk_term.ui import output
# Different message types
output.success("✓ Operation completed successfully")
output.error("✗ An error occurred")
output.warning("⚠ This needs attention")
output.info("ℹ Information message")
output.debug("🔍 Debug information")
# Special formatting
output.tip("💡 Pro tip: Use themes for better visuals")
output.hint("This is a subtle hint")
output.command("git commit -m 'Initial commit'")
Interactive Prompts
from chuk_term.ui import ask, confirm, select_from_list, ask_number
# Get user input
name = ask("What's your name?")
age = ask_number("How old are you?", min_value=0, max_value=150)
# Confirmation
if confirm("Would you like to continue?"):
output.success("Great! Let's proceed...")
# Selection menu
theme = select_from_list(
["default", "dark", "light", "minimal", "terminal"],
"Choose a theme:"
)
Display Code with Syntax Highlighting
from chuk_term.ui import display_code, display_diff
# Show code with syntax highlighting
code = '''def hello_world():
print("Hello from ChukTerm!")
return True'''
display_code(code, language="python", title="Example Function")
# Show a diff
display_diff(
old_text="Hello World",
new_text="Hello ChukTerm!",
title="Changes"
)
Streaming Messages (New!)
from chuk_term.ui.streaming import StreamingMessage, StreamingAssistant
import time
# Basic streaming message
with StreamingMessage(title="🤖 Assistant") as stream:
stream.update("Processing your request")
time.sleep(0.5)
stream.update("...")
time.sleep(0.5)
stream.update(" Done!")
# Automatically finalizes with Markdown rendering
# Using StreamingAssistant for simpler API
assistant = StreamingAssistant()
stream = assistant.start()
for word in "Hello from ChukTerm streaming!".split():
assistant.update(word + " ")
time.sleep(0.2)
assistant.finalize()
Progress Indicators (New!)
from chuk_term.ui import output
import time
# Progress bar with detailed tracking
with output.progress_bar("Processing files", show_time=True) as progress:
task = progress.add_task("download", total=100)
for i in range(100):
progress.update(task, advance=1)
time.sleep(0.01)
# Simple iteration tracking
items = ['file1.txt', 'file2.txt', 'file3.txt']
for item in output.track(items, "Processing files"):
process(item) # Your processing logic
# Spinner for indeterminate tasks
with output.spinner("Loading data..."):
load_data() # Long-running operation
Theme Support
from chuk_term.ui import output
from chuk_term.ui.theme import set_theme, get_theme, get_available_themes
# Set a theme
set_theme("monokai") # or dracula, solarized, minimal, terminal
# Get current theme
current = get_theme()
output.info(f"Using theme: {current.name}")
# List all available themes
themes = get_available_themes()
output.info(f"Available themes: {', '.join(themes)}")
🖥️ CLI Usage
ChukTerm includes a powerful CLI for exploring and testing features:
# Show library information
chuk-term info
chuk-term info --verbose
# Run interactive demo
chuk-term demo
# Preview all themes (New!)
chuk-term themes # Detailed preview of each theme
chuk-term themes --side-by-side # Compact side-by-side comparison
# Explore examples (New!)
chuk-term examples # List all available examples with descriptions
chuk-term examples --list-only # Quick list of example names
chuk-term examples --run demo # Run a specific example
# Run a command with theming
chuk-term run "ls -la"
# Test with specific theme
chuk-term test --theme monokai
🛠️ Development
Setup Development Environment
# Clone the repository
git clone https://github.com/chrishayuk/chuk-term.git
cd chuk-term
# Install with dev dependencies using uv
uv sync --dev
# Install pre-commit hooks (automatic code quality checks)
uv run pre-commit install
# Verify installation
chuk-term --version
uv run pytest # Run tests
Running Tests
# Run all tests with coverage
uv run pytest --cov=chuk_term
# Run specific test file
uv run pytest tests/ui/test_output.py
# Run with verbose output
uv run pytest -v
Code Quality
# Run linting
uv run ruff check src/ tests/
# Auto-fix linting issues
uv run ruff check --fix src/ tests/
# Format code
uv run black src/ tests/
# Type checking
uv run mypy src/
# Run all checks
make check
Available Make Commands
make help # Show all available commands
make dev # Install for development
make test # Run tests with coverage
make lint # Run linting checks
make format # Format code
make clean # Remove build artifacts
📚 Documentation
Quick Start
- 🚀 Getting Started Guide - Installation, examples, and best practices
- 🤖 LLM Documentation - AI-optimized reference (llmstxt.org)
- 📂 Examples Directory - Working code examples
Core Documentation
- Output Management - Centralized console output system
- Terminal Management - Terminal control and state management
- Theme System - Theming and styling guide
- Package Management - Using uv for dependency management
- Unit Testing - Testing guidelines and best practices
- Test Coverage - Coverage requirements and reports
- Code Quality - Linting, formatting, and quality standards
API Reference
Output Levels
output.debug()- Debug information (only in verbose mode)output.info()- Informational messagesoutput.success()- Success confirmationsoutput.warning()- Warning messagesoutput.error()- Error messages (non-fatal)output.fatal()- Fatal errors (exits program)
Themes
- default - Balanced colors, good for most terminals
- dark - High contrast on dark backgrounds
- light - Optimized for light terminals
- minimal - Plain text, no colors or icons
- terminal - Basic ANSI colors only
- monokai - Popular dark theme
- dracula - Gothic dark theme
- solarized - Low contrast, easy on eyes
📁 Examples
The examples directory contains demonstration scripts:
| File | Description |
|---|---|
ui_demo.py |
Comprehensive UI component showcase |
ui_code_demo.py |
Code display and syntax highlighting |
ui_output_demo.py |
Output management features |
ui_terminal_demo.py |
Terminal control capabilities |
ui_theme_independence.py |
Theme system demonstration |
| Streaming Demos | |
ui_streaming_demo.py |
Advanced streaming UI capabilities |
ui_streaming_message_demo.py |
StreamingMessage and StreamingAssistant demos |
ui_streaming_practical_demo.py |
Real-world streaming use cases |
ui_streaming_quickstart.py |
Simple streaming examples to get started |
streaming_long_text_demo.py |
Token-by-token streaming with proper wrapping |
| Other | |
ui_quick_test.py |
Quick functionality test |
Run any example:
# Run the main demo
uv run python examples/ui_demo.py
# Try the streaming demos
uv run python examples/ui_streaming_quickstart.py
uv run python examples/ui_streaming_practical_demo.py
🏗️ Project Structure
chuk-term/
├── src/chuk_term/
│ ├── __init__.py # Package metadata
│ ├── cli.py # CLI interface
│ └── ui/ # UI components
│ ├── output.py # Output management (singleton)
│ ├── terminal.py # Terminal control
│ ├── theme.py # Theme system (8 themes)
│ ├── prompts.py # User prompts
│ ├── formatters.py # Data formatters
│ ├── code.py # Code display
│ ├── banners.py # Banner displays
│ └── streaming.py # Streaming message support
├── tests/ # Test suite (616 tests, 93% coverage)
├── examples/ # Example scripts
│ ├── ui_demo.py
│ ├── ui_streaming_*.py # Streaming demonstrations
│ └── ...
├── docs/ # Documentation
│ ├── ui/ # UI documentation
│ │ └── GETTING_STARTED.md # Quick start guide
│ └── testing/ # Testing documentation
│ ├── UNIT_TESTING.md
│ └── TEST_COVERAGE.md
├── llms.txt # LLM-optimized docs (llmstxt.org)
├── CLAUDE.md # Project context for AI agents
├── CONTRIBUTING.md # Contribution guidelines
└── pyproject.toml # Package configuration
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Quick Contribution Steps
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
uv run pytest) - Commit with a descriptive message
- Push to your fork
- Open a Pull Request
📄 License
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
🙏 Acknowledgments
📮 Support
- 📫 Report issues at GitHub Issues
- 💬 Discuss at GitHub Discussions
- 📖 Read docs at GitHub Wiki
Metadata
Release files for chuk-term 0.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chuk_term-0.4.2.tar.gz | 199.8 kB | Without provenance | Details for chuk_term-0.4.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chuk_term-0.4.2-py3-none-any.whl | Python 3 | none | any | Details for chuk_term-0.4.2-py3-none-any.whl |
Total release size: 249.9 kB
Release files / chuk_term-0.4.2.tar.gz
| Download URL | chuk_term-0.4.2.tar.gz |
|---|---|
| Size | 199.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
012c50a43515c06c8ff417e0c8e55111f5c35703e39d0af08dd69f5e8bfbd184
|
|
BLAKE2b-256 checksum How to use checksums |
a2d13ce4d3f584f35cbad0f2cefc7dbe2c6780808425d2d2bc10ed8b0db95d82
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Release files / chuk_term-0.4.2-py3-none-any.whl
| Download URL | chuk_term-0.4.2-py3-none-any.whl |
|---|---|
| Size | 50.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
493bb7c278bce348f77df1bc4116b11dbda6a7ca4c624263f9123c0c46622c53
|
|
BLAKE2b-256 checksum How to use checksums |
41d1955b22252a61dab143ce1b22f429b8daec024629ede78487d70b3f379ee8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.2
|
Security for chuk-term 0.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.