0
# Cleo
1

2
Cleo is a comprehensive Python library for creating beautiful and testable command-line interfaces. It provides a high-level API for building CLI applications with features including command definition with arguments and options, automatic help generation, colorized output with custom styling, multiple verbosity levels, command testing utilities, and autocompletion support for bash, zsh, and fish shells.
3

4
## Package Information
5

6
- **Package Name**: cleo  
7
- **Language**: Python
8
- **Installation**: `pip install cleo`
9

10
## Core Imports
11

12
```python
13
from cleo.application import Application
14
from cleo.commands.command import Command
15
from cleo.helpers import argument, option
16
```
17

18
## Basic Usage
19

20
```python
21
from cleo.commands.command import Command
22
from cleo.helpers import argument, option
23
from cleo.application import Application
24

25
class GreetCommand(Command):
26
    name = "greet"
27
    description = "Greets someone"
28
    arguments = [
29
        argument(
30
            "name",
31
            description="Who do you want to greet?",
32
            optional=True
33
        )
34
    ]
35
    options = [
36
        option(
37
            "yell",
38
            "y", 
39
            description="If set, the task will yell in uppercase letters",
40
            flag=True
41
        )
42
    ]
43

44
    def handle(self):
45
        name = self.argument("name")
46
        
47
        if name:
48
            text = f"Hello {name}"
49
        else:
50
            text = "Hello"
51
            
52
        if self.option("yell"):
53
            text = text.upper()
54
            
55
        self.line(text)
56

57
# Create application and add command
58
application = Application()
59
application.add(GreetCommand())
60

61
if __name__ == "__main__":
62
    application.run()
63
```
64

65
## Architecture
66

67
Cleo follows a hierarchical architecture built around these core components:
68

69
- **Application**: The main container that manages commands, handles routing, and coordinates execution
70
- **Commands**: Individual CLI commands with their arguments, options, and business logic
71
- **IO System**: Input/output coordination with support for different input sources and output destinations
72
- **UI Components**: Rich interactive elements including tables, progress bars, and questions
73
- **Formatting System**: Styled text output with colors, formatting options, and custom styles
74
- **Event System**: Event-driven architecture for extensibility and command lifecycle management
75

76
This design enables building sophisticated CLI applications with extensive customization capabilities while maintaining clean separation of concerns.
77

78
## Capabilities
79

80
### Core Application Management
81

82
The main Application class that serves as the container for CLI commands. Handles command registration, routing, argument parsing, and execution coordination.
83

84
```python { .api }
85
class Application:
86
    def __init__(self, name: str = "console", version: str = "") -> None: ...
87
    def add(self, command: Command) -> Command | None: ...
88
    def get(self, name: str) -> Command: ...
89
    def has(self, name: str) -> bool: ...
90
    def run(self, input: Input | None = None, output: Output | None = None, error_output: Output | None = None) -> int: ...
91
    def find(self, name: str) -> Command: ...
92
    def all(self, namespace: str | None = None) -> dict[str, Command]: ...
93
```
94

95
[Application Management](./application.md)
96

97
### Command Development System
98

99
Command creation and configuration with arguments, options, and command execution logic. This forms the foundation for building individual CLI commands.
100

101
```python { .api }
102
class Command(BaseCommand):
103
    name: str | None = None
104
    description: str = ""
105
    arguments: ClassVar[list[Argument]] = []
106
    options: ClassVar[list[Option]] = []
107
    
108
    def handle(self) -> int: ...  # Abstract method to implement
109
    def argument(self, name: str) -> Any: ...
110
    def option(self, name: str) -> Any: ...
111
    def line(self, text: str, style: str | None = None, verbosity: Verbosity = Verbosity.NORMAL) -> None: ...
112

113
def argument(name: str, description: str | None = None, optional: bool = False, 
114
             multiple: bool = False, default: Any | None = None) -> Argument: ...
115

116
def option(long_name: str, short_name: str | None = None, description: str | None = None,
117
           flag: bool = True, value_required: bool = True, multiple: bool = False,
118
           default: Any | None = None) -> Option: ...         
119
```
120

121
[Command Development](./commands.md)
122

123
### Input/Output System
124

125
Comprehensive I/O management including input handling, output formatting, and error reporting. Supports different input sources and output destinations with verbosity control.
126

127
```python { .api }
128
class IO:
129
    def __init__(self, input: Input, output: Output, error_output: Output) -> None: ...
130
    def read(self, length: int, default: str = "") -> str: ...
131
    def read_line(self, length: int = -1, default: str = "") -> str: ...
132
    def write(self, messages: str | Iterable[str], new_line: bool = False, verbosity: Verbosity = Verbosity.NORMAL, type: OutputType = OutputType.NORMAL) -> None: ...
133
    def write_line(self, messages: str | Iterable[str], verbosity: Verbosity = Verbosity.NORMAL, type: OutputType = OutputType.NORMAL) -> None: ...
134
    def write_error(self, messages: str | Iterable[str], new_line: bool = False, verbosity: Verbosity = Verbosity.NORMAL, type: OutputType = OutputType.NORMAL) -> None: ...
135
    def write_error_line(self, messages: str | Iterable[str], verbosity: Verbosity = Verbosity.NORMAL, type: OutputType = OutputType.NORMAL) -> None: ...
136
    def overwrite(self, messages: str | Iterable[str]) -> None: ...
137
    def overwrite_error(self, messages: str | Iterable[str]) -> None: ...
138
    def flush(self) -> None: ...
139

140
class Verbosity(Enum):
141
    QUIET = 16
142
    NORMAL = 32
143
    VERBOSE = 64
144
    VERY_VERBOSE = 128
145
    DEBUG = 256
146

147
class OutputType(Enum):
148
    NORMAL = 1
149
    RAW = 2
150
    PLAIN = 4
151
```
152

153
[Input/Output System](./io.md)
154

155
### Styling and Formatting
156

157
Text styling and formatting capabilities including colors, formatting options, and custom styles for rich console output.
158

159
```python { .api }
160
class Formatter:
161
    def __init__(self, decorated: bool = False, styles: dict[str, Style] | None = None): ...
162
    def format(self, message: str) -> str: ...
163
    def set_style(self, name: str, style: Style) -> None: ...
164

165
class Style:
166
    def __init__(self, foreground: str | None = None, background: str | None = None, options: list[str] | None = None): ...
167
    def foreground(self, foreground: str) -> Style: ...
168
    def background(self, background: str) -> Style: ...
169
    def bold(self, bold: bool = True) -> Style: ...
170
    def apply(self, text: str) -> str: ...
171
```
172

173
[Styling and Formatting](./styling.md)
174

175
### User Interface Components
176

177
Rich interactive UI components including tables, progress indicators, and question prompts for building sophisticated CLI interactions.
178

179
```python { .api }
180
class Table:
181
    def __init__(self, io: IO | Output, style: str | None = None): ...
182
    def set_headers(self, headers: list[str]) -> Table: ...
183
    def set_rows(self, rows: Rows) -> Table: ...
184
    def render(self) -> None: ...
185

186
class ProgressBar:
187
    def __init__(self, io: IO | Output, max: int = 0): ...
188
    def start(self, max: int | None = None) -> None: ...
189
    def advance(self, step: int = 1) -> None: ...
190
    def finish(self) -> None: ...
191

192
class Question:
193
    def __init__(self, question: str, default: Any = None): ...
194
    def ask(self, io: IO) -> Any: ...
195
    def hide(self, hidden: bool = True) -> None: ...
196
```
197

198
[User Interface Components](./ui.md)
199

200
### Testing Utilities
201

202
Testing utilities for command and application testing with simulated input/output for comprehensive CLI testing.
203

204
```python { .api }
205
class CommandTester:
206
    def __init__(self, command: Command): ...
207
    def execute(self, args: str = "", inputs: str | None = None) -> int: ...
208

209
class ApplicationTester:
210
    def __init__(self, application: Application): ...
211
    def execute(self, args: str = "", inputs: str | None = None) -> int: ...
212
```
213

214
[Testing Utilities](./testing.md)
215

216
### Exception Handling System
217

218
Complete exception hierarchy for error handling in CLI applications with specific exception types for different error conditions.
219

220
```python { .api }
221
class CleoError(Exception):
222
    exit_code: int | None = None
223

224
class CleoLogicError(CleoError): ...       # Configuration errors
225
class CleoRuntimeError(CleoError): ...     # Runtime errors
226
class CleoValueError(CleoError): ...       # Value errors
227
class CleoNoSuchOptionError(CleoError): ... # Option not found errors
228
class CleoUserError(CleoError): ...        # User input errors
229
class CleoMissingArgumentsError(CleoUserError): ... # Missing required arguments
230
class CleoCommandNotFoundError(CleoUserError):     # Command not found
231
    def __init__(self, name: str, commands: list[str] | None = None) -> None: ...
232
class CleoNamespaceNotFoundError(CleoUserError):   # Namespace not found
233
    def __init__(self, name: str, namespaces: list[str] | None = None) -> None: ...
234
```
235

236
[Exception Handling](./exceptions.md)