0
# Text Output and Formatting
1
2
Core text output functions with indentation context management, column formatting, and cross-platform terminal compatibility. Provides puts/puts_err functions for consistent output and indent context managers for nested text formatting with automatic newline handling.
3
4
## Capabilities
5
6
### Basic Output Functions
7
8
Core functions for printing text to stdout and stderr with consistent formatting and newline handling.
9
10
```python { .api }
11
def puts(s='', newline=True, stream=STDOUT):
12
"""
13
Prints given string to stdout with proper indentation.
14
15
Parameters:
16
- s: str, string to print (default: '')
17
- newline: bool, whether to add newline (default: True)
18
- stream: function, output stream function (default: STDOUT)
19
"""
20
21
def puts_err(s='', newline=True, stream=STDERR):
22
"""
23
Prints given string to stderr with proper indentation.
24
25
Parameters:
26
- s: str, string to print (default: '')
27
- newline: bool, whether to add newline (default: True)
28
- stream: function, output stream function (default: STDERR)
29
"""
30
```
31
32
### Indentation Management
33
34
Context manager for nested text indentation with support for custom quotes and automatic indentation tracking.
35
36
```python { .api }
37
def indent(indent=4, quote=''):
38
"""
39
Indentation manager that returns an indentation context manager.
40
41
Parameters:
42
- indent: int, number of spaces to indent (default: 4)
43
- quote: str, quote string to prepend (default: '')
44
45
Returns:
46
context manager for use with 'with' statement
47
"""
48
49
def dedent():
50
"""
51
Dedent next strings, use only if you use indent otherwise than as a context.
52
Removes the last indentation level from the global indent stack.
53
"""
54
```
55
56
### Column Formatting
57
58
Advanced column formatting with automatic terminal width detection and text wrapping.
59
60
```python { .api }
61
def columns(*cols, **kwargs):
62
"""
63
Format text in columns with automatic width adjustment.
64
65
Parameters:
66
- cols: tuple of (string, width) pairs where width can be None for auto-expand
67
- kwargs: dict, optional parameters including 'width' for manual console width
68
69
Returns:
70
str: formatted columnar text
71
"""
72
```
73
74
### Text Formatters
75
76
Text width management functions for consistent formatting and alignment.
77
78
```python { .api }
79
def max_width(string, cols, separator='\n'):
80
"""
81
Returns text formatted to maximum width with word wrapping.
82
83
Parameters:
84
- string: str or ColoredString, text to format
85
- cols: int, maximum width in characters
86
- separator: str, line separator (default: '\n')
87
88
Returns:
89
str or ColoredString: formatted text with proper wrapping
90
"""
91
92
def min_width(string, cols, padding=' '):
93
"""
94
Returns given string with right padding to minimum width.
95
96
Parameters:
97
- string: str or ColoredString, text to pad
98
- cols: int, minimum width in characters
99
- padding: str, padding character (default: ' ')
100
101
Returns:
102
str: padded text
103
"""
104
```
105
106
### Stream Constants
107
108
Predefined stream functions for consistent output handling.
109
110
```python { .api }
111
STDOUT = sys.stdout.write # Standard output stream function
112
STDERR = sys.stderr.write # Standard error stream function
113
```
114
115
## Usage Examples
116
117
```python
118
from clint.textui import puts, indent, columns
119
120
# Basic output
121
puts("Hello, world!")
122
puts_err("Error occurred")
123
124
# Nested indentation
125
puts("Root level")
126
with indent(4):
127
puts("Level 1 indented")
128
with indent(4):
129
puts("Level 2 indented")
130
puts("Back to level 1")
131
puts("Back to root")
132
133
# Email-style quoting
134
puts("Original message:")
135
with indent(4, quote='> '):
136
puts("This is quoted text")
137
puts("Multiple lines work too")
138
139
# Column formatting
140
text1 = "This is some long text that will be wrapped"
141
text2 = "This is other text that goes in the second column"
142
text3 = "Third column text here"
143
144
formatted = columns(
145
(text1, 20), # Fixed width of 20
146
(text2, 25), # Fixed width of 25
147
(text3, None) # Auto-expand to fill remaining space
148
)
149
puts(formatted)
150
151
# Manual column width control
152
formatted_custom = columns(
153
(text1, 30),
154
(text2, None),
155
width=100 # Force console width to 100
156
)
157
puts(formatted_custom)
158
```
159
160
## Advanced Usage
161
162
```python
163
from clint.textui.formatters import max_width, min_width
164
from clint.textui.colored import red
165
166
# Text wrapping with colored text
167
long_text = red("This is a very long red text that needs to be wrapped")
168
wrapped = max_width(long_text, 40)
169
puts(wrapped)
170
171
# Padding with minimum width
172
short_text = "Short"
173
padded = min_width(short_text, 20, padding='.')
174
puts(padded) # Output: "Short..............."
175
176
# Complex indentation patterns
177
puts("Multi-level indentation example:")
178
with indent(2):
179
puts("Level 1")
180
with indent(3, quote='* '):
181
puts("Bullet point 1")
182
puts("Bullet point 2")
183
with indent(3, quote='- '):
184
puts("Different bullet style")
185
puts("Another item")
186
```