0
# Clint
1

2
Python Command Line Interface Tools that provide comprehensive functionality for creating rich terminal applications. Clint offers colored output, progress bars, indented text formatting, column-based layouts, argument handling, user prompts, and application directory management with built-in cross-platform compatibility.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import clint
14
```
15

16
Common patterns for specific functionality:
17

18
```python
19
from clint.textui import puts, colored, indent
20
from clint.arguments import Args
21
from clint.textui.progress import bar
22
from clint.textui import prompt
23
from clint import resources
24
```
25

26
## Basic Usage
27

28
```python
29
from clint.textui import puts, colored, indent
30
from clint.arguments import Args
31

32
# Colored output with automatic TTY detection
33
puts(colored.red('Error: Something went wrong'))
34
puts(colored.green('Success: Operation completed'))
35

36
# Nested indentation with context manager
37
puts('Root level text')
38
with indent(4):
39
    puts('Indented text')
40
    with indent(4, quote='> '):
41
        puts('Quoted and nested text')
42

43
# Command line argument parsing
44
args = Args()
45
first_arg = args.get(0)  # Get first argument or None
46
if 'verbose' in args:
47
    puts('Verbose mode enabled')
48

49
# Progress bars for iterables
50
from clint.textui.progress import bar
51
items = range(100)
52
for item in bar(items, label='Processing: '):
53
    # Process each item
54
    pass
55
```
56

57
## Architecture
58

59
Clint is organized into several main modules:
60

61
- **Arguments Module**: Provides `Args` class for command-line argument parsing with filtering and grouping
62
- **TextUI Module**: Comprehensive text output system with colors, formatting, progress indicators, and user prompts
63
- **Resources Module**: Application directory management for cross-platform data, cache, and log storage
64
- **Utils Module**: Path expansion, collection testing, and directory creation utilities
65
- **Pipes Module**: Unix pipe detection and stdin data reading
66

67
The textui module includes submodules for specialized functionality: core output functions, colored text, progress bars, user prompts, input validators, column formatting, and text formatters.
68

69
## Capabilities
70

71
### Command Line Arguments
72

73
Comprehensive command-line argument parsing with filtering, grouping, and file/flag detection. The Args class provides chainable methods for finding, filtering, and extracting arguments with support for complex argument patterns.
74

75
```python { .api }
76
class Args:
77
    def __init__(self, args=None, no_argv=False): ...
78
    def get(self, x): ...
79
    def contains(self, x): ...
80
    def first(self, x): ...
81
    def all_with(self, x): ...
82
    def grouped(self): ...
83
    def flags(self): ...
84
    @property
85
    def files(self): ...
86
```
87

88
[Command Line Arguments](./arguments.md)
89

90
### Text Output and Formatting
91

92
Core text output functions with indentation context management, colored text support, and cross-platform compatibility. Includes puts/puts_err functions and indent context managers for nested text formatting.
93

94
```python { .api }
95
def puts(s='', newline=True, stream=STDOUT): ...
96
def puts_err(s='', newline=True, stream=STDERR): ...
97
def indent(indent=4, quote=''): ...
98
def columns(*cols, **kwargs): ...
99
```
100

101
[Text Output and Formatting](./text-output.md)
102

103
### Colored Text
104

105
Rich colored text output with automatic TTY detection and cross-platform terminal color support. Provides color functions and ColoredString class with string operation compatibility.
106

107
```python { .api }
108
def red(string, always=False, bold=False): ...
109
def green(string, always=False, bold=False): ...
110
def blue(string, always=False, bold=False): ...
111
class ColoredString:
112
    def __init__(self, color, s, always_color=False, bold=False): ...
113
```
114

115
[Colored Text](./colored-text.md)
116

117
### Progress Indicators
118

119
Progress bars, dots, and mill/spinner indicators for long-running operations. Supports both iterator wrapping and manual progress updates with customizable appearance and automatic terminal width detection.
120

121
```python { .api }
122
def bar(it, label='', width=32, hide=None, expected_size=None, every=1): ...
123
def dots(it, label='', hide=None, every=1): ...
124
class Bar:
125
    def __init__(self, label='', width=32, hide=None): ...
126
    def show(self, progress, count=None): ...
127
```
128

129
[Progress Indicators](./progress.md)
130

131
### User Prompts and Input
132

133
Interactive user prompts with validation, including yes/no questions, text input with validation, and multiple choice options. Supports batch mode for automated testing and custom validators.
134

135
```python { .api }
136
def yn(prompt, default='y', batch=False): ...
137
def query(prompt, default='', validators=None, batch=False): ...
138
def options(prompt, options, default=None, batch=False): ...
139
```
140

141
[User Prompts and Input](./prompts.md)
142

143
### Input Validation
144

145
Comprehensive input validation system with regex, path, file, integer, and option validators. Extensible validation framework with custom error messages and validator chaining.
146

147
```python { .api }
148
class RegexValidator:
149
    def __init__(self, regex=None, message=None): ...
150
class PathValidator:
151
    def __init__(self, message=None): ...
152
class IntegerValidator:
153
    def __init__(self, message=None): ...
154
```
155

156
[Input Validation](./validation.md)
157

158
### Application Resources
159

160
Cross-platform application directory management for user data, site data, cache, and log directories. Provides file operations and subdirectory management with automatic directory creation.
161

162
```python { .api }
163
def init(vendor, name): ...
164
class AppDir:
165
    def write(self, filename, content, binary=False): ...
166
    def read(self, filename, binary=False): ...
167
    def sub(self, path): ...
168
```
169

170
[Application Resources](./resources.md)
171

172
### Unix Pipes and Utilities
173

174
Unix pipe detection for stdin data, path expansion utilities, collection testing, and directory creation helpers. Includes string manipulation functions for delimiter splitting and chunking.
175

176
```python { .api }
177
def piped_in(): ...
178
def expand_path(path): ...
179
def is_collection(obj): ...
180
def mkdir_p(path): ...
181
```
182

183
[Unix Pipes and Utilities](./utilities.md)
184

185
### English Language Helpers
186

187
English language string joining with Oxford comma support and customizable conjunctions. Useful for generating human-readable lists and messages.
188

189
```python { .api }
190
def join(l, conj='and', im_a_moron=False, separator=','): ...
191
```
192

193
[English Language Helpers](./english.md)
194

195
## Types
196

197
```python { .api }
198
class Args:
199
    """CLI Argument management class with filtering and grouping capabilities."""
200
    pass
201

202
class ColoredString:
203
    """Enhanced string class that maintains color information and string operations."""
204
    pass
205

206
class Bar:
207
    """Progress bar implementation with customizable appearance and timing."""
208
    pass
209

210
class AppDir:
211
    """Application directory manager with file operations and path management."""
212
    pass
213

214
class ValidationError(Exception):
215
    """Exception raised during input validation failures."""
216
    pass
217
```