0
# Command Execution and System Integration
1

2
Execute shell commands with enhanced features, platform detection, and system integration utilities for cross-platform compatibility.
3

4
## Capabilities
5

6
### Command Execution
7

8
Enhanced subprocess execution with features like verbose output, result capturing, and flexible parameter handling.
9

10
```python { .api }
11
def cmd(command, shell=False, detach=False, verbose=0, tee=None, cwd=None, env=None, tee_backend='auto', check=False, system=False, timeout=None, capture=True):
12
    """
13
    Execute subprocess with enhanced features.
14
    
15
    Args:
16
        command (str|list): Command to execute
17
        shell (bool): Use shell for execution
18
        detach (bool): Detach process (don't wait)
19
        verbose (int): Verbosity level (0-3)
20
        tee (bool|None): Print output while capturing
21
        cwd (str): Working directory
22
        env (dict): Environment variables
23
        tee_backend (str): Tee backend ('auto', 'thread', etc.)
24
        check (bool): Raise exception on non-zero exit
25
        system (bool): Use os.system instead of subprocess
26
        timeout (float): Command timeout in seconds
27
        capture (bool): Capture output
28
        
29
    Returns:
30
        CmdOutput: Enhanced result with stdout, stderr, ret attributes
31
    """
32

33
class CmdOutput(dict):
34
    """
35
    Container for command output with dict-like and subprocess.CompletedProcess compatibility.
36
    
37
    Attributes:
38
        out (str): Standard output
39
        err (str): Standard error  
40
        ret (int): Return code
41
        proc: Subprocess object
42
    """
43
    @property
44
    def stdout(self): ...
45
    
46
    @property
47
    def stderr(self): ...
48
    
49
    @property
50
    def returncode(self): ...
51
```
52

53
### Platform Detection
54

55
Constants and utilities for detecting the current operating system and platform-specific behavior.
56

57
```python { .api }
58
# Platform detection constants
59
WIN32: bool  # True if running on Windows
60
LINUX: bool  # True if running on Linux
61
DARWIN: bool  # True if running on macOS  
62
POSIX: bool  # True if running on POSIX system
63

64
def find_exe(name, **kwargs):
65
    """
66
    Find executable in PATH.
67
    
68
    Args:
69
        name (str): Executable name
70
        **kwargs: Additional search options
71
        
72
    Returns:
73
        str|None: Path to executable or None if not found
74
    """
75

76
def find_path(name, **kwargs):
77
    """
78
    Find path to executable or library.
79
    
80
    Args:
81
        name (str): Name to search for
82
        **kwargs: Additional search options
83
        
84
    Returns:
85
        str|None: Path to item or None if not found
86
    """
87
```
88

89
### Platform Directories
90

91
Cross-platform utilities for accessing standard system directories like cache, config, and data directories.
92

93
```python { .api }
94
def platform_cache_dir():
95
    """
96
    Get platform-specific cache directory.
97
    
98
    Returns:
99
        str: Cache directory path
100
        
101
    Examples:
102
        - Linux: ~/.cache
103
        - macOS: ~/Library/Caches
104
        - Windows: %LOCALAPPDATA%
105
    """
106

107
def platform_config_dir():
108
    """
109
    Get platform-specific config directory.
110
    
111
    Returns:
112
        str: Config directory path
113
        
114
    Examples:
115
        - Linux: ~/.config
116
        - macOS: ~/Library/Application Support
117
        - Windows: %APPDATA%
118
    """
119

120
def platform_data_dir():
121
    """
122
    Get platform-specific data directory.
123
    
124
    Returns:
125
        str: Data directory path
126
        
127
    Examples:
128
        - Linux: ~/.local/share
129
        - macOS: ~/Library/Application Support
130
        - Windows: %APPDATA%
131
    """
132
```
133

134
### Deprecated Platform Functions
135

136
```python { .api }
137
# These functions are deprecated - use platform_*_dir() instead
138
def ensure_app_cache_dir(*args, **kwargs):
139
    """DEPRECATED: Use platform_cache_dir() instead"""
140

141
def ensure_app_config_dir(*args, **kwargs):
142
    """DEPRECATED: Use platform_config_dir() instead"""
143

144
def ensure_app_data_dir(*args, **kwargs):
145
    """DEPRECATED: Use platform_data_dir() instead"""
146

147
def get_app_cache_dir(*args, **kwargs):
148
    """DEPRECATED: Use platform_cache_dir() instead"""
149

150
def get_app_config_dir(*args, **kwargs):
151
    """DEPRECATED: Use platform_config_dir() instead"""
152

153
def get_app_data_dir(*args, **kwargs):
154
    """DEPRECATED: Use platform_data_dir() instead"""
155
```
156

157
## Usage Examples
158

159
### Command Execution
160

161
```python
162
import ubelt as ub
163

164
# Basic command execution
165
result = ub.cmd('echo "Hello World"')
166
print(result['out'])  # "Hello World\n"
167
print(result.ret)     # 0
168

169
# Verbose execution with real-time output
170
result = ub.cmd('ls -la', verbose=2)
171

172
# Command with custom environment
173
env = {'MY_VAR': 'custom_value'}
174
result = ub.cmd('echo $MY_VAR', shell=True, env=env)
175

176
# Capture both stdout and stderr
177
result = ub.cmd('python -c "import sys; print(\\"out\\"); print(\\"err\\", file=sys.stderr)"')
178
print("STDOUT:", result['out'])
179
print("STDERR:", result['err'])
180

181
# Check if command succeeded
182
if result.ret == 0:
183
    print("Command succeeded")
184
else:
185
    print(f"Command failed with code {result.ret}")
186
```
187

188
### Platform Detection
189

190
```python
191
import ubelt as ub
192

193
# Platform-specific logic
194
if ub.WIN32:
195
    # Windows-specific code
196
    cmd = 'dir'
197
elif ub.LINUX:
198
    # Linux-specific code  
199
    cmd = 'ls'
200
elif ub.DARWIN:
201
    # macOS-specific code
202
    cmd = 'ls -G'
203
else:
204
    # Generic POSIX
205
    cmd = 'ls'
206

207
result = ub.cmd(cmd)
208

209
# Find executables
210
python_path = ub.find_exe('python')
211
if python_path:
212
    print(f"Python found at: {python_path}")
213
else:
214
    print("Python not found in PATH")
215
```
216

217
### Platform Directories
218

219
```python
220
import ubelt as ub
221

222
# Get platform-appropriate directories
223
cache_dir = ub.platform_cache_dir()
224
config_dir = ub.platform_config_dir()
225
data_dir = ub.platform_data_dir()
226

227
print(f"Cache: {cache_dir}")
228
print(f"Config: {config_dir}")
229
print(f"Data: {data_dir}")
230

231
# Use for application-specific paths
232
app_cache = ub.ensuredir(cache_dir, 'myapp')
233
app_config = ub.ensuredir(config_dir, 'myapp')
234
```
235

236
### Cross-Platform Command Patterns
237

238
```python
239
import ubelt as ub
240

241
# Cross-platform file listing
242
if ub.WIN32:
243
    result = ub.cmd('dir /B', shell=True)
244
else:
245
    result = ub.cmd('ls -1')
246

247
files = result['out'].strip().split('\n')
248

249
# Cross-platform path operations
250
if ub.WIN32:
251
    # Windows uses different path separators
252
    separator = '\\'
253
else:
254
    separator = '/'
255

256
# Better to use ubelt's path utilities instead
257
from pathlib import Path
258
path = ub.Path('/some/path')  # Works cross-platform
259
```